Website Development Best Practices
Overview
The Essentials setup application implements a set of best practices for developing projects with Bloomreach Content. Following these practices helps maintain project quality, avoid common issues, and streamline future upgrades.
This page lists recommended development practices for Bloomreach Content projects.
Avoid Static Text in Rendering Templates
Do not include static text directly in WAR-based rendering templates. If you need to change static text, you would have to redeploy the project. Instead, store static text in resource bundle documents and reference them in your templates.
The setup application installs resource bundle documents under /administration/labels. For details on using resource bundles, see the Resource Bundle Editor documentation.
Validate User Input Against Malicious Data
Always validate input from external sources, including website users submitting forms. Malicious input can compromise your project. Bloomreach Content provides tools to parse and sanitize input.
All generic HST components provided by Essentials use these tools. For example, see org.onehippo.cms7.essentials.components.CommonComponent#cleanupSearchQuery().
You should also protect against malicious input from CMS users (authors and editors). All rendering templates included with out-of-the-box features apply XML escaping to CMS content. For example, use the following Freemarker syntax:
${document.title?html}
Reuse Existing HST Components
Leverage existing HST components to use proven implementations and reduce development and maintenance effort. The setup application provides a library of HST components for common use cases.
You can customize these components by adjusting parameters or by extending them with your own custom components.
Register HST Components as Catalog Components
When developing custom components, register them as Channel Editor catalog components. This enables you or site administrators to configure component parameters through the Channel Editor UI. It also allows you to use the Switch Templates feature.
To enable this, annotate your component with a parameters info interface and configure your HST setup so the component resides in an HST container.
Many features in the setup application install catalog components in the essentials catalog and provide page configurations with containers for these components.
Make Catalog Components Recognizable in the Channel Editor
When you add a catalog component to a container in the Channel Editor, it may require configuration before rendering content. Until configured, components may not display anything.
Catalog components installed by the setup application include markup that only appears in the Channel Editor, making it clear where unconfigured components are available for setup.
To implement this in your own custom catalog components, review the rendering templates in your project's /repository-data/webfiles/src/main/resources/site/freemarker/hstdefault directory.
Limit Content Queries
When querying content, always specify appropriate limits to control resource usage. Unbounded queries can consume excessive resources.
Generic HST components from the setup application use the org.hippoecm.hst.content.beans.query.HstQuery#setLimit() method to set query limits.
If you configure faceted navigation, ensure you also apply suitable query limits.
Use Iterators Instead of Fetching Lists
When iterating over data in HST components or content beans, use provided iterators rather than retrieving the entire dataset in a non-native format. This approach improves performance.
Generic HST components and content beans from the setup application use iterators wherever possible.
Provide Page-Not-Found Support
There are two scenarios where no content is available to display:
- The requested URL does not map to any sitemap item.
- The matched sitemap item is not associated with any content.
For the first case, configure a root-level catch-all sitemap item to render a page-not-found page. For the second case, configure HST components to redirect to a page-not-found page when no content is found.
The setup application implements this by installing a root-level _any_ catch-all sitemap item. The base HST component in the setup application demonstrates how to handle the second case with the org.onehippo.cms7.essentials.components.CommonComponent#setContentBeanWith404() method.
Stay Up to Date with Maintenance Releases
Bloomreach regularly releases maintenance updates for Bloomreach Content, addressing issues and introducing new features. After creating your project, check for new maintenance releases regularly to benefit from the latest improvements.
The setup application is updated with the latest maintenance releases through new archetype versions. Refer to the project creation guide for the recommended archetype version.