Help Center

Menu

Create a new plugin project

Before you start, ensure you have set up an appropriate development environment for creating plugins.

A plugin is created using a command line tool that creates a new empty plugin project from a template.

The source code for a plugin must be set up using a pre-defined folder structure that includes a set of standard files and plugin-specific files.

This tool creates the folder structure provides basic java files required to start working on a new plugin.

The template is defined as a Maven archetype template and will always produce a folder and file structure based on the current version of the plugin framework.

When you create a new plugin you need to have the following information:

Plugin descriptors

The following descriptors must be defined when creating a new plugin:

Artifact ID

The artifactId defines the name of the plugin. The name should be concise but describe the function of the plugin. Note: Avoid using the word "plugin" in the ID, it doesn’t provide any value and makes names unnecessarily longer.

Group ID

A groupId defines your organization/subgroup. This should be based on your organization’s domain name. e.g. If your organization is ExampleORG, and it has a domain name of example.com then you should use com.example.plugin. Plugins written by Squiz staff for generic reuse in the Squiz DXP should have a Group ID of net.squiz.plugin or com.funnelback.plugin.

Package name

The package name identifies the plugin in Java. It should follow the format GROUP-ID.ARTIFACT-ID.

Plugin name

A human-readable name for the plugin, for display on the plugin dashboard.

Plugin description

A short description of the plugin, also be shown on the plugin dashboard.

Interface templates

You also need to know what functionality your plugin will implement. If you provide these at creation time the template will create the relevant java files that include required imports and methods to make it easy to start writing your code.

gatherer

Only works for a custom data source. Lets you create a custom gatherer, which will get documents in unique ways.

filtering

Lets you create a document filter or HTML document filter for modifying documents before they are indexed.

indexing

Lets you hook into different parts of the indexing process; providing metadata mappings, external metadata mappings, gscopes or to kill documents

facets

Lets you provide faceted navigation configuration.

search-servlet-filtering

Lets you hook into the servlet request and response lifecycle by implementing the SearchServletFilterHook interface

searchLifeCycle

Lets you write code that enables you to manipulate the query processing and search results or provide custom faceted navigation category sorting.

startUrlProvider

Lets you provide logical that will define additional start URLs.

Plugin scope

A plugin can run on a data source and/or a results page. These flags indicate if a plugin applies in a certain scope and will also determine if you can enable the plugin from the search dashboard on a results page or data source.

runs-on-datasource

The plugin can be run on a data source. Plugins that implement the following interfaces should run on a data source:

  • gatherer

  • filtering

  • jsoup-filtering

  • indexing

runs-on-result-page

The plugin can be run on a results page. Plugins that implement the following interfaces should run on a results page:

  • searchLifecycle

  • facets

  • search-servlet-filtering

Running the command line tool

Change to the folder where you intend to work on all your plugin projects. Each plugin project will be created in a sub-folder of this directory.

Run the following command:

$ mvn archetype:generate -DarchetypeGroupId=com.funnelback -DarchetypeArtifactId=plugin-archetypes -Dversion=1.0.0

Interactive setup

When the Maven command is run it will prompt for a number of required fields.

Open up a terminal and change to the folder that houses all of your plugins. If this is the first time creating a plugin then create a new folder to use for your plugin development. Each plugin that you develop will be in a sub-folder of this.

$ cd my-plugins-directory

Run the maven command.

$ mvn archetype:generate -DarchetypeGroupId=com.funnelback -DarchetypeArtifactId=plugin-archetypes -Dversion=1.0.0

The archetype will ask you a series of questions which are used to generate the files for your new plugin.

Archetype questions

Define value for property 'gatherer'

Set this to true if your plugin is implementing a custom gatherer.

Accepted values: true or false.

Define value for property 'facets'

Set this to true if your plugin is implementing faceted navigation customization - providing faceted navigation configuration or implementing a custom sort comparator.

Accepted values: true or false.

Define value for property 'indexing'

Set this to true if your plugin is implementing any of the indexing features - providing metadata mappings or external metadata, XML configuration, Gscopes, QIE, kill configuration or generating auto-completion.

Accepted values: true or false.

Define value for property 'searchLifeCycle'

Set this to true if your plugin is implementing any of the search lifecycle features - providing hook script equivalent functionality to manipulate the search data model at query time.

Accepted values: true or false.

Define value for property 'filtering'

Set this to true if your plugin is implementing any document filters - providing groovy filter equivalent functionality to manipulate the downloaded content prior to indexing.

Accepted values: true or false.

Define value for property 'jsoup-filtering'

Set this to true if your plugin is implementing any HTML document/Jsoup filters - providing groovy Jsoup filter equivalent functionality to manipulate downloaded HTML content prior to indexing.

Accepted values: true or false.

Define value for property 'search-servlet-filtering'

Set this to true if your plugin is implementing any of the servlet filter hook script features - providing groovy servlet hook script equivalent functionality to manipulate the search transaction at query time.

Accepted values: true or false.

Define value for property 'start-url-provider'

Set this to true if your plugin is generating any start URLs.

Accepted values: true or false.

Define value for property 'groupId'

The groupId defines your organization/subgroup. This should be based on your organization’s domain name. e.g. If your organization is Funnelback, and it has a domain name of 'funnelback.com' then you should use com.funnelback.plugin. For this exercise a fictitious organization Example Pty. Ltd. with domain of example.com will be used.

The should match expression note in the prompt tells you that the ID can only be made up of lowercase or uppercase alphabetic characters, numbers, periods and dashes.

Generic plugins owned and maintained by Squiz for use within the Squiz DXP should either use net.squiz.plugin or com.funnelback.plugin as the groupId. Customer-specific plugins should be set to the customer’s domain name e.g. com.example.plugin

Accepted values: letters, numbers, spaces and periods. e.g. net.squiz.plugin

Define value for property 'artifactId'

The artifactId defines a unique ID for the plugin. The ID should be concise but describe the function of the plugin.

e.g. In this tutorial a plugin that modifies the prefix of a title in search results will be written. For this we will use title-prefix-plugin as the artifact ID.

Accepted values: letters, numbers, spaces and periods.

Define value for property 'plugin-name'

The plugin name is the human-readable name for the plugin.

This is the name you see when browsing the installed plugins in the DXP and should be set to a name that encapsulates the plugin’s purpose. The name should be supplied in sentence case.

Accepted values: letters, numbers, spaces and periods. e.g. Clean result titles

Define value for property 'plugin-description'

The plugin description should contain a short description that tells a user when the plugin should be used. This is the description that is shown on the plugin screen when you are looking through the installed plugins.

e.g. Use this plugin when you need to sort your faceted navigation categories using a custom sort order.

Define value for property 'archetypeVersion'

This defines the version of the plugin framework that is used by the plugin, and determines which version of Funnelback that the plugin will function with.

This should normally be set to the current DXP version (e.g. LATEST), and this will be updated to the current DXP version as part of the review process.

However, if you need the plugin to work in Funnelback 16.10 (Funnelback legacy pods or Squiz Cloud) then set this to 16.10.0, or if you need it to work with Funnelback 16.4 then set this to 16.4.0

If you set the version to an older release of the plugin framework, certain features mentioned in the developer guides may not be available as these were added in later versions of the framework. You will also be asked to provide an upgraded version of the plugin that works with the current plugin framework so that this can be made available in the DXP plugin library.
Define value for property 'runs-on-datasource'

Set this to true if your plugin is designed to be used with data sources. Note that a plugin can be designed to work with both data sources and results pages.

Accepted values: true or false.

Define value for property 'runs-on-result-page'

Set this to true if your plugin is designed to be used with results pages. This typically only applies to plugins that implement search lifecycle or search servlet filtering. Note that a plugin can be designed to work with both data sources and results pages.

Accepted values: true or false.

Define value for property 'package'

The package ID is used by Java to identify the plugin. It should be entered following the format <groupId>.<artifactId>, without hyphens. A unique package name is recommended to avoid conflicts with other plugins and you should always be able to accept the default suggestion.

Accepted values: letters, numbers, spaces and periods. e.g. com.funnelback.plugin.examplePlugin

Non-interactive setup

The interactive setup instructions prompt (interactively) for a number of required parameters. It is also possible to run the maven command and supply all the required options directly as parameters to the command. This allows creation of the new plugin to be scripted.

The following command is an example command that creates a plugin similar to the one you create in the tutorial.

$ mvn archetype:generate -DarchetypeGroupId=com.funnelback        \
    -DarchetypeArtifactId=plugin-archetypes                       \
    -DarchetypeVersion=LATEST                                     \
    -DgroupId=com.example.plugin                                  \
    -DartifactId=title-prefix-plugin                              \
    -Dpackage=com.example.plugin.titleprefixplugin                \
    -Dversion=1.0.0                                               \
    -Dfacets=false                                                \
    -Dplugin-description="Adds a prefix to search result titles"  \
    -Dplugin-name="Title Prefix Plugin"                           \
    -Dfiltering=false                                             \
    -Dgatherer=false                                              \
    -Dindexing=false                                              \
    -Djsoup-filtering=false                                       \
    -DstartUrlProvider=false                                      \
    -Druns-on-datasource=false                                    \
    -Druns-on-result-page=true                                    \
    -Dsearch-servlet-filtering=true                               \
    -DsearchLifeCycle=true

See: Tutorial - Part 2.1: Generate a new plugin from a Maven archetype template

See also