Linking a Document to a Hippo Component

March 9th 2018 Hippo CMS Java

Most built-in components in Hippo CMS have a link to one or more documents as they are designed to render the CMS content documents. Sooner or later you'll want to achieve that with your own custom component as well.

The document will be represented as a String in your configuration parameter interface. However, to present the user with a built-in UI component for selecting the document, you need to use the right annotations. You have two choices:

  • @DocumentLink will create a dropdown of documents that match the specified document type. It will only work well for a small number of matching documents.

      public interface CustomComponentInfo {
        @Parameter(name = "documentLink", displayName = "Document Link")
        @DocumentLink(docType = "gogreen:newsdocument")
        String getDocumentLinkPath();

    Built-in editor for DocumentLink

  • @JcrPath will open a standalone picker dialog for navigating the content hierarchy and selecting a node. You can choose any of the picker configurations defined in /hippo:configuration/hippo:frontend/cms. Also, isRelative flag will cause the selection to be stored as a relative path instead of absolute, just like in the case of @DocumentLink. This is required for the next step to work.

      public interface CustomWebComponentInfo {
        @Parameter(name = "documentLink", displayName = "Document Link")
        @JcrPath(isRelative = true,
                 pickerConfiguration = "cms-pickers/documents-only")
        String getDocumentLinkPath();

    Built-in editor for JcrPath

In the component, you can then get an instance of the document type model class filled in with document properties from the CMS:

public void doBeforeRender(final HstRequest request, final HstResponse response) {
  super.doBeforeRender(request, response);
  CustomComponentInfo paramInfo = getComponentParametersInfo(request);
  String documentPath = paramInfo.getAssociatedDocumentPath();
  HippoDocument document = getHippoBeanForPath(documentPath, HippoDocument.class);
  if (document != null) {
    // process document data

The second parameter of getHippoBeanForPath is the model class for the document type. If no document can be found with the given relative path or the document type doesn't match, null will be returned.

Get notified when a new blog post is published (usually every Friday):

If you're looking for online one-on-one mentorship on a related topic, you can find me on Codementor.
If you need a team of experienced software engineers to help you with a project, contact us at Razum.
Creative Commons License