Part 3.2: Documenting your plugin

This guide covers what you need to document when writing a plugin.

A plugin must include documentation file that covers the purpose of the plugin and how to use it. The documentation is generated as part of building the plugin and is automatically included in both the Squiz Help Center plugins documentation and also within the administration dashboard.

See: Create or edit the plugin documentation for detailed information on writing the plugin documentation.

Capture basic information

At a minimum, the documentation must cover:

  1. The purpose of the plugin and what problems it solves

  2. How to configure the plugin

  3. Examples showing how to use the plugin

  4. Links to other supporting information.

Review the contents of PluginUtils.java

PluginUtils.java is where most of the automatically generated fields in the plugin documentation are sourced.

This is automatically populated when you first generate the plugin, using the values that you entered when you ran the archetype. You will often need to edit the values you entered, and you can safely do this in the PluginUtils.java file.

You should carefully review each of methods that return content for the documentation. This includes:

  • The label and description.

  • The configuration key names, descriptions and long descriptions.

  • The filter and Jsoup filter class names (if you are implementing either of these for your plugin).

Update the metadata fields to ensure that appropriate values are returned. The metadata assists with discovery and categorization, particularly when using the plugin screens on the administration dashboard.

Review the plugin configuration keys

You added the following key definitions when implementing the plugin functionality.

Review the configuration key properties:

public final PluginConfigKey<String> PATTERN = PluginConfigKey.<String>builder()
        .pluginId(getPluginId())
        .id("pattern")
        .type(PluginConfigKeyType.builder().type(PluginConfigKeyType.Format.STRING).build())
        .defaultValue(".")
        .label("Prefix pattern") (1)
        .description("Pattern of characters to match prefix against.") (2)
        .longDescription("The pattern specified here is a _Java regular expression_ that is matched against the title.\n"+
                        "\n"+
                "See also: link:https://www.regexplanet.com/advanced/java/index.html[Java regex tester]") (3)
        .build();

public final PluginConfigKey<String> REPLACEMENT = PluginConfigKey.<String>builder()
        .pluginId(getPluginId())
        .id("replaceWith")
        .type(PluginConfigKeyType.builder().type(PluginConfigKeyType.Format.STRING).build())
        .label("Replacement text") (1)
        .description("Text that will replace any matches.") (2)
        .build();
1 Check that the label sets an appropriate name for the plugin. This name is displayed as the title for the documentation page. (Remember this is also the name shown on the plugin dashboard).
2 Check that the short description is a one line Use this plugin to…​ type statement that gives some context about why you might want to use the plugin. This is the first paragraph of the key description in the documentation and also used as the description shown on the plugin dashboard. Note that this field must not include any formatting and must be a single paragraph.
3 Consider if you need to provide a long description which is appended as additional paragraphs to the short description in the documentation. The long description field can contain Asciidoc formatting.

Add the metadata categories

There are four methods that need to be updated that set the metadata properties for the plugin.

These methods return a comma-separated list of keywords, which are chosen from an enumerated/controlled list of terms.

When editing you can click on the word that is shown in the {@link WORD} comment above the method, then press alt+space or select View  Quick definition from the menu. This will show a popup with the values that are acceptable. If you start to type a value in the listOf method it will autocomplete with the values that are acceptable.

Note that the popup shown for the ProductSubtopicCategory is paginated for each of the different subtypes.

For each of these methods specify any metadata values that are relevant for this plugin.

For the clean title plugin add the following:

  • Audience: site builder, developer - This plugin is suitable for both the site builder and developer audiences.

  • Marketplace subtype: Search lifecycle - This plugin implements the search lifecycle interface.

  • Product topic: Results pages - The plugin modifies search result titles, affecting results pages.

  • Product sub-topic: Search results and templates, Data model manipulation, Search data model - The plugin modifies search results titles, so it affects the search results, by modifying the search data model.

Update the methods in PluginUtils.java as shown below. Experiment with adding the categories by using the IntelliJ lookups described above.

    /**
      *  Audience field is used to flag the content of the documentation page as being suitable for one or more of these DXP audiences.
      *  There are different types of Audience defined here {@link Audience}
      *
      *  This method returns list of Audience selected for the plugin.
     */
    @Override public List <Audience> getAudience() {
        return List.of(Audience.SITE_BUILDER, Audience.DEVELOPER);
    }

    /**
     *  Marketplace subtype is mostly defined by the interfaces that are implemented for the plugin.
     *  Complete list if marketplace subtypes is defined here {@link MarketplaceSubtype}
     */
    @Override public List <MarketplaceSubtype> getMarketplaceSubtype() {
        return List.of(MarketplaceSubtype.SEARCH_LIFECYCLE);
    }

    /**
     *   Product topic is about describing the topics that the plugin you’re building relates to.
     *   So when you select one of those topics in the facets for example the plugin will come up in the possible results.
     *   Available options can be found here {@link ProductTopic} (2)
     */
    @Override public List <ProductTopic> getProductTopic() {
        return List.of(ProductTopic.RESULTS_PAGE);
    }

    /**
     *   Product subtopics are defined for each of the product topic.
     *   Available options can be found here {@link ProductSubtopicCategory} (2)
     */
    @Override public List <ProductSubtopicCategory> getProductSubtopic() {
        return List.of(ProductSubtopic.ResultsPage.DATA_MODEL_MANIPULATION, ProductSubtopic.ResultsPage.DATA_MODEL_SEARCH, ProductSubtopic.ResultsPage.RESULTS_TEMPLATES);
    }

Add additional information to the Asciidoc include files

Several additional asciidoc files are provided in the src/main/resources/ascii.sections folder of your plugin source.

These files allow you to provide additional, free-form asciidoc-formatted documentation which is included in the generated documentation.

Detailed description

Edit the detaileddescription.adoc file.

Remember that this should be used to provide additional background information on the plugin, and this information is included as additional paragraphs after the (short) description sourced from PluginUtils.java.

Enter the following as your detailed description:

detaileddescription.adoc
This plugin works by replacing parts of the title using a pair of configuration keys that define a link:https://www.regexplanet.com/advanced/java/index.html[Java regular expression] that identifies what should be replaced, and a corresponding key that defines the replacement for the matched text.

The title is updated within the search data model and works with both Freemarker templating, and integrations with the search JSON and XML endpoints.

WARNING: If you choose to sort your search results by title then sorting may not work correctly. This is because your changes to the title are applied after the results are returned by the query processor (which applies any sorting to the result set). Sorting will work correctly if your title modifications are to remove a suffix from your titles, or a prefix that is common to every title in your index.

Additional configuration settings

Edit the additionalconfigsettings.adoc file.

This should be used to provided additional instructions for configuring the plugin, such as information on other (core-Funnelback) configuration settings that need to be configured for your plugin to work correctly.

This file is often not required. For our plugin we don’t need this so delete the contents of the file and save it.

Provide an example

Every plugin must include at least one example to show how the plugin might be used to solve a problem. Provide additional examples where it makes sense.

Edit the example.adoc file.

example.adoc
=== Example: Remove a prefix from search result titles

Consider a website where the page titles include a common suffix, 'ACME Corporation - ', for every title. This looks terrible in the search results and makes the results difficult to read. The following plugin configuration will strip this off the start of a title when the results are returned from the index.

Enable the title prefix plugin on your results page and add the following configuration

|===
|Configuration key|Value

|Prefix pattern|`^ACME Corporation -\s+`
|Replace with|
|===

This configuration matches the string 'ACME Corporation -' including any following whitespace, at the start of a tit

Provide keywords

The keywords.adoc file should be used to provide a (hidden) comma-separated list of additional keywords to assist with discovery of the plugin in the search.

You don’t need to include anything in here if the words appear in the documentation content. Including things like alternate words that describe the feature, or other names that might be in common use for the feature.

For our plugin we don’t need to supply any additional keywords so delete the contents of this file and then save it.

The seealsolinks.adoc file should provide a bulleted list containing links to any relevant supporting resources, either within the documentation or on external websites.

the documentation will automatically include a link to the plugins section of the documentation at the top of the bulleted list.

To link to a page in the documentation identify the page you want to link to e.g. https://docs.squiz.net/funnelback/docs/latest/build/results-pages/search-results-html/index.html. To create the link you need everything after /latest/, and you need to replace the html extension with adoc.

We will add the link identified above, and also the link we have previously mentioned in the detailed description to the regex tester.

seealsolinks.adoc
* xref:build/results-pages/search-results-html/index.adoc[Search result templates]
* link:https://www.regexplanet.com/advanced/java/index.html[Java regular expression tester]

In Asciidoc, and xref cross-reference) is an internal documentation link to another page within the same set of documentation - this must be specified using a path that references the asciidoc file, relative to the root of the documentation site. A link can include a web address and links to an external resource. The text within the square brackets is the text displayed on the hyperlink.

Changelog

The changelog.adoc file provides information on differences between versions of the plugin and only needs to be provided if you are extending or updating a plugin.

As this is the first version of the plugin the changelog is not required. Edit the file and remove the contents before saving.

Viewing the assembled documentation

When you build the plugin the documentation is also generated to index.adoc which is written to the src/main/resources folder.

You should review the generated file (open this in IntelliJ and read through the rendered version of it in your preview window). This will assist in finding any formatting issues, which should be corrected at the source (don’t make changes to index.adoc as this will be overwritten when you build the plugin).

See: Part 4.1: Building and packaging your plugin for instructions on how to build the plugin.

Example index.adoc

The example Asciidoc file below documents the title-prefix plugin. This file is generated when you build the plugin from the work you have completed above.

Compare the generated asciidoc file below to the parts you edited above and familiarize yourself with where the pieces you edited fit into the assembled document. This is very valuable for when you need to update the plugin documentation./
index.adoc
= Plugin: Modify title prefix
:page-description: Use this plugin to modify the prefix of search result titles
:page-keywords:
:page-content-type: Documentation|Plugins
:page-hc-audience: Site builder|Developer
:page-marketplace-type: Plugin
:page-marketplace-subtype: Search lifecycle
:page-marketplace-version: 1.0.0
:page-plugin-scope: Results page
:page-plugin-package: com.example.plugin.titleprefix
:page-plugin-id: title-prefix
:page-plugin-interface: searchLifeCycle
:page-product-topic: Search results pages
:page-product-subtopic: Data model manipulation|Search data model|Search results and templates

== Purpose

Use this plugin to modify the prefix of search result titles

This plugin works by replacing parts of the title using a pair of configuration keys that define a link:https://www.regexplanet.com/advanced/java/index.html[Java regular expression] that identifies what should be replaced, and a corresponding key that defines the replacement for the matched text.

The title is updated within the search data model and works with both Freemarker templating, and integrations with the search JSON and XML endpoints.

WARNING: If you choose to sort your search results by title then sorting may not work correctly. This is because your changes to the title are applied after the results are returned by the query processor (which applies any sorting to the result set). Sorting will work correctly if your title modifications are to remove a suffix from your titles, or a prefix that is common to every title in your index.


== Usage

=== Enable the plugin

. Select menu:Plugins[] from the side navigation pane and click on the *Modify title prefix* tile.
. From the *Location* section, select the results page to which you would like to enable this plugin from the _Select a results page_ select list.

NOTE: The plugin will take effect as soon as you finish running through the plugin setup steps.

=== Configuration settings

The *configuration settings* section is where you do most of the configuration for your plugin. The settings enable you to control how the plugin behaves.

NOTE: The configuration key names below are only used if you are configuring this plugin manually. The configuration keys are set in the results page configuration to configure the plugin. When setting the keys manually you need to type in (or copy and paste) the key name and value.

==== Prefix pattern

[%autowidth.spread]
|===
|Configuration key| `plugin.title-prefix.config.pattern`
|Data type|string
|Default value|`+.+`
|Required|This setting is optional
|===

Pattern of characters to match prefix against.

The pattern specified here is a _Java regular expression_ that is matched against the title.

See also: link:https://www.regexplanet.com/advanced/java/index.html[Java regex tester]

==== Replace with

[%autowidth.spread]
|===
|Configuration key| `plugin.title-prefix.config.replaceWith`
|Data type|string
|Required|This setting is optional
|===

Text that will replace any matches.



== Examples

=== Example: Remove a prefix from search result titles

Consider a website where the page titles include a common suffix, 'ACME Corporation - ', for every title. This looks terrible in the search results and makes the results difficult to read. The following plugin configuration will strip this off the start of a title when the results are returned from the index.

Enable the title prefix plugin on your results page and add the following configuration

|===
|Configuration key|Value

|Prefix pattern|`^ACME Corporation -\s+`
|Replace with|
|===

This configuration matches the string 'ACME Corporation -' including any following whitespace, at the start of a title and replaces it with an empty string. In other words, it removes the prefix from the title.


== Change log


== See also

* xref:build/plugins/index.adoc[Plugins]
* xref:build/results-pages/search-results-html/index.adoc[Search result templates]
* link:https://www.regexplanet.com/advanced/java/index.html[Java regular expression tester]

Next steps

The next tutorial covers how to write unit tests to test your plugin.