Hippo Forge Quality Checklist - Bloomreach Experience - Open Source CMS

Hippo Forge Quality Checklist

If your project meets all items in this list, it rocks!



Documentation available

Use project POM as parent

Upgrade logic (if applicable)

Screenshots available

Package name starts with org.onehippo.forge.PROJECT_NAME

Clear project name

Description includes name of the project

Description explains what the project does

Trove categories applied

Versioning information in description

POM guidelines applied

Example available

News article posted

Translatable labels

Document permissions

Query limits

Faceted Navigation limits

Hide your namespaces

Product ready





The proper way to add documentation is by using the Maven XDoc format. For an example see the Feeds plugin:
These docs come from the documentation in SVN:
Docs are automatically generated by the Forge in a cron job - so it will take some hours before they are live.

If your documentation is not in trunk/src/site but in subproject/trunk/src/site they cannot be generated automatically for the first time.
Please try to have your documentation in /docs, /trunk or ${PROJECT_NAME}/trunk.
If it has to be elsewhere for some reason, you can ask a Forge system administrator to check out the documentation by hand.
Please add a screenshot of your work to the forge project. So we know what it actually looks like.

Use Project POM as Parent

Use the project pom as a parent to the plugin project. It provides a number of standard pom sections and has some basic dependencies defined that are common to all Hippo projects.

The project pom thus helps to reduce the amount of configuration that needs to be there in a plugin. This also makes it easier for projects to pick those plugins up.


and don't forget to add the maven repository that contains this pom as well, or the build will fail when the project pom is not already available locally:


Package Name

Use a package name that starts with " org.onehippo.forge.PROJECT_NAME". In your project name only use small letters [ a-z].

Example: org.onehippo.forge.dropdown

Artifact Names

Use artifact names that starts with " PROJECT_NAME-". The artifactId of the main pom should be just " PROJECT_NAME".

Example: dropdown-addon-repository

Maven Repository

Create a folder /maven2 in the root of the subversion of your project. See also Publishing Maven artifacts for your Hippo Forge project

Example: https://forge.onehippo.org/svn/dropdown-plugin/maven2/

Project Name and Description

Give your project a name that makes it unique and that explains what it does. If possible, make the name stand out of other projects that do the same thing but in a different way.
Good examples:

  • Dropdown
  • Dropdown AJAX

Bad examples:

  • MyDropDown
  • DropDown2
  • ExampleDropDown

The description of your project is important. The search functionality in the Forge *only* searches within the description (not the name of the project!). So make sure the description makes sense, and make sure that it contains some proper keywords for the search.

Clearly describe whether the plugin is production ready or not.


Please help to categorize all projects in the right categories. Go into the project and update its Trove map. This will give far more exposure to your project, and will make it much easier for newcomers to find your project! And it's simple to do!
So how do you apply the new Trove categories?

  1. Login to the Hippo Forge ( http://forge.onehippo.org).
  2. Go to the full project listing and click the project you want to update: http://forge.onehippo.org/top/mostactive.php.
  3. Click the "Admin" tab, next to "Summary".
  4. Click the "[Edit]" button next to "Trove Categorization".
  5. Select the right development status, programming language, license, audience, component and topic.
  6. Hit the bit "Update All Category Changes" button.

Note that you can select up to three values for each category. The more matching values you pick, the better. It will improve the changes that a newcomer finds your project.
After you've done this, it takes some time before the map is updated but after a couple of hours it will show up under all the sections you've selected under the main "Projects" menu.

Version Management

Give the plugin a version number lower than 1.0 if it is not production ready.

Use the text below as a template for the short description:
Short text explaining the plugin.
Add to the short description of the plugin the following table:

CMS Version

Plugin Version





add to the *repositories* section of the MAIN POM:

  <name>Hippo Forge Project Name</name> caps

add to the *dependencies* of the SITE POM:


add to the *dependencies* of the CMS POM:



Provide an example with your project. If it's an HST component - then add a mini website that demonstrates how to use the component. If it's a CMS plugin - then add an example CMS configuration that demonstrates the CMS plugin.

Releasing the Plugin

Please post a news article on the Forge project! This will then show up on the Forge home page, and can be cross posted to the Forge homepage by one of the Forge admins.See this post as an example:

If the Documentation-link in the menu of your project does not show up, go to Admin > Edit project info and enter the url of the documentation in the Homepage URL field.

When you are satisfied with the forge site make sure it is publicly available. Go to Admin > Edit Observer Permissons and change the settings to "Public".

Make all your Labels Translatable

Use i18n property files or repo translations for labels in your plugin, so others can translate your plugin into another language. By default, we need two languages: English and Dutch.

Document Permissions

If your forge site component needs write access to the repository you have to document exactly which privileges the siteuser needs. For local development it's often convenient to use the admin user as siteuser which has all privileges. On production systems the siteuser's privileges are restricted to what it exactly needs. If you don't document the privileges properly you forge plugin will not work on production! You need to specify:

  • privileges for paths. For example: the siteuser needs write privileges on /poll/votes

  • privileges for document types. For example: the siteuser needs hippo:editor privileges on type poll:votes

Query Result Size / Limit

Queries in plugins must make use of setLimit. If you need the actual total number of hits for paging, but there might be 100.000 hits, then don't implement it with the getSize() method. Who wants to page to page 12.567 anyway? Say: there are more then 200 hits and page until page 20 for example. Use a setLimit of 200.

You must add a order by clause to the query when you want getSize() of the QueryResult. From jackrabbit 2.0 and higher (CMS trunk now) you'll get -1 for getSize() if you do not have ordering. If you don't know where to sort on, just add: ' order by @jcr:score descending'.

Note that the HstQuery by default sets a 'order by @jcr:score descending', so, if you search with the HST-2, you do not need this.

Faceted Navigation limits

Make sure you set limits for the size of the resultset on your Faceted Navigation nodes. Otherwise the default is used, which is 1000. When the resultset has 1000 documents, the repository will become very slow. Also make sure when fetching the documents from a resultset, that you use


This is much more efficient than HippoFolder#getDocuments(). Also see Faceted Navigation Configuration


Make extensive and smart usage of logging in debug level. Try to follow logically what the program is doing and log at key points. This is valuable when trying to figure out a problem that occurs in a client environment. There, you may only have access to logs and the logging servlet. By setting the log level to debug, you may be able to pinpoint where things go wrong. Also, it is recommended not to use ERROR level for anything else than unrecoverable errors, or errors that the end user must take action. For all other cases, WARN level should be enough. Last, it is a good practice exposing a stacktrace in debug level, but only an informative message in all other levels. That way a problem does not go unnoticed, but you also prevent the logs from being cluttered with stacktraces.

Hide your Namespaces

When your plugin defines a namespace and that namespace is not intended for editing in the CMS make sure that you hide it. See Hide a Namespace in the CMS editor for how this can be achieved

Template Composer

The Template Composer poses certain restrictions on your HST components. See HstComponent ParametersInfo annotation

Product Ready

In most cases a plugin is developed in the context of a project. However to make the plugin work in different contexts you should take a look at the following constraints:

Internationalization and Localization

Take translations awareness, internalization and localization into account.

Localized Metadata Services

If the plugin uses metadata services, such as those provided by the taxonomy or selection plugins, it should retrieve the metadata in the correct (document) language. This could be as easy as using an indirection that takes care of the localization. It should be included in the demo project.


Make sure the plugin runs within a clustered environment, preferably without additional configuration (out-of-the-box)

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?