Damir's Corner.

Linking a Document to a Hippo Component

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();
    }
  

  

• @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();
    }
  

  

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.