fontoxml-find-and-replace

Find and Replace

The Find and Replace add-on provides find and replace functionality over the content of your documents. This add-on is suitable for every Fonto application, and is also compatible with just-in-time loading configurations.

After integrating the add-on package in your application using FDT, the Find and Replace functionality becomes automatically enabled in the sidebar. It can be configured further by setting the find-and-replace-configuration configuration variable.

How to integrate a server-side presearch

The server-side presearch can only be used by editors that use just-in-time loading of documents.

For just-in-time loading configurations the CMS can reduce the time required to perform a search across all documents by filtering all the documents that do not contain a search term from a list.

  • Client-side, Fonto can be configured to use a CMS contract to this end by setting the presearchEnabled property of find-and-replace-configuration to true. Fonto will then call the POST /document/presearch endpoint at various times.

    configurationManager.set('find-and-replace-configuration', {
    	enableReplaceAll: false,
    	enablePresearch: true
    });
  • Server-side, the CMS should implement the POST /document/presearch endpoint as documented in Fonto's standard CMS contracts.

In a production environment

To return accurate results the POST /document/presearch endpoint needs to be aware of which elements are block-level elements, which elements are shown (in Fonto) in a different order than their XML order, and which elements may be ignored altogether. The endpoint may return false positives (documents that are believed to contain the search term) as those documents are filtered out when the Fonto client performs the definitive, client-side search. The endpoint may not return false negatives, as that would disqualify a document from the definitive search -- this would result in search results erroneously being omitted.

Please refer to the documentation of POST /document/presearch for the request parameters that will be used by Fonto, and the response parameters that are expected to be returned by the CMS.

In Fonto's development server

Fonto's development server stubs the standard CMS contracts so that the editor can be developed independent of a full CMS running on the developer machine. For more accurate results in Fonto's development server the POST /document/presearch endpoint may need additional configuration. For our development server this can be achieved by adding the findAndReplacePresearch object to your config.json file. It may contain the following properties:

  • blockElementXPathTest, an XPathTest for block level elements

  • outOfOrderElementXPathTest, an XPathTest for out-of-order elements

  • removedElementXPathTest, an XPathTest for removed/invisible elements

For example:

{
	"scope": {
		"documentIds": ["clogs/clogs.ditamap"]
	},
	"findAndReplacePresearch": {
		"blockElementXPathTest": "self::p",
		"outOfOrderElementXPathTest": "self::footnote",
		"removedElementXPathTest": "self::metadata"
	}
}

User experience

Find and Replace listens to some key presses for opening the sidebar and to navigate through the results.

The following keybindings can be used:

  • ctrl+f ( cmd+f on macOS) or F3: Open the Find and Replace sidebar (focuses the find text input)

  • enter: If the search UI is opened and search input is focused it initiates search.

  • enter or F3: If the search UI is opened and there are results it navigates to the next search result.

  • shift+enter or shift + F3: If the search UI is opened and there are results it navigates to the previous search result.

  • ctrl+shift+f ( cmd+shift+f on macOS) or ctrl+h ( cmd+h on macOS): Open the Find and Replace sidebar (focuses the replace input).

  • enter: If the replace UI is opened and there are results it replaces the current result.

Recommendations

Besides using the sidebar UI it is only possible to access the find functionality from a dropdown. The dropdown is designed for quick navigation in editors that have limited screen estate. It has to be manually enabled by including it in the masthead:

<FindAndReplaceDropButton />

See also the documentation of FindAndReplaceDropButton for an overview of the available props.

Scoped search

Scoped search allows the user to scope both search and replace within selected topics.

The feature uses the Structure View component and a modal in order to display the hierarchy of topics in your editor.

Configuration

For this configuration the CVK currently defines configureAsStructureViewItem and configureStructureViewItemProperties, the first one used to configure the items that will be shown in the StructureView and the second one used to configure the properties of the items. This configuration is also valid to configure the fontoxml-structure-view add-on.

We do recommend that everything that is a sheet frame is also configured for the Structure View.

This configuration is optional, but in the case that no items are configured an empty modal will be shown.

Example

The following steps will guide you to configure structure view items. Please follow the instructions in fontoxml-structure-view to get a more in depth configuration.

  • Create the file packages/structure-view-config/src/configureSxModule.js in your editor.

import configureAsStructureViewItem from 'fontoxml-families/src/configureAsStructureViewItem.js';


export default function configureSxModule(sxModule) {
    sxModule.markAsAddon();

    // Your configuration
}
  • Add the new package to config/fonto-manifest.json.

{
	"dependencies": {
		...
		"structure-view-config": "packages/structure-view-config"
	}
}


APIs in fontoxml-find-and-replace

Was this page helpful?