Fork me on GitHub

Developer's How-to (Flat List View)

Configuring Field in Document Template (a.k.a 'namespace')

You should add a custom field configuration like the following example (in System View XML format). This is an example with ExampleExternalDocumentServiceFacade having embedded external JSON data in a classpath resource:

<?xml version="1.0" encoding="UTF-8"?>
<sv:node sv:name="newsdocument" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hipposysedit:templatetype</sv:value>
  </sv:property>

  <!-- SNIP -->

  <sv:node sv:name="editor:templates">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>editor:templateset</sv:value>
    </sv:property>
    <sv:node sv:name="_default_">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>frontend:plugincluster</sv:value>
      </sv:property>

      <!-- SNIP -->

      <!--
        You should add something like the following for each External Document Picker field.
        Most part will be used without modification except of the plugin parameters.
      -->

      <sv:node sv:name="relatedextdocselector">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
          <sv:value>frontend:plugin</sv:value>
        </sv:property>
        <sv:property sv:name="caption" sv:type="String">
          <sv:value>Related External Documents</sv:value>
        </sv:property>
        <sv:property sv:name="engine" sv:type="String">
          <sv:value>${engine}</sv:value>
        </sv:property>
        <sv:property sv:name="mode" sv:type="String">
          <sv:value>${mode}</sv:value>
        </sv:property>
        <sv:property sv:name="wicket.id" sv:type="String">
          <sv:value>${cluster.id}.field</sv:value>
        </sv:property>
        <sv:property sv:name="wicket.model" sv:type="String">
          <sv:value>${wicket.model}</sv:value>
        </sv:property>

        <!-- Plugin class configuration for Flat List View dialog option. -->
        <sv:property sv:name="plugin.class" sv:type="String">
          <sv:value>org.onehippo.forge.exdocpicker.impl.field.ExternalDocumentFieldSelectorPlugin</sv:value>
        </sv:property>

        <!-- Item selection mode plugin parameter -->
        <sv:property sv:name="selection.mode" sv:type="String">
          <sv:value>multiple</sv:value>
        </sv:property>

        <!-- ExternalDocumentServiceFacade class FQN plugin parameter -->
        <sv:property sv:name="external.document.service.facade" sv:type="String">
          <sv:value>org.onehippo.forge.exdocpicker.demo.field.ExampleExternalDocumentServiceFacade</sv:value>
        </sv:property>

        <!-- Physical document node property name to store the external document IDs. This is used by the implementation (ExampleExternalDocumentServiceFacade) -->
        <sv:property sv:name="example.external.docs.field.name" sv:type="String">
          <sv:value>exdocpickerbasedemo:relatedexdocids</sv:value>
        </sv:property>

        <sv:node sv:name="cluster.options">
          <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>frontend:pluginconfig</sv:value>
          </sv:property>
        </sv:node>
      </sv:node>

      <!-- SNIP -->

    </sv:node>
  </sv:node>
</sv:node>
          

Implementing your ExternalDocumentServiceFacade class

See an example ExternalDocumentServiceFacade implementation code here: https://github.com/bloomreach-forge/external-document-picker/tree/master/demo/cms/src/main/java/org/onehippo/forge/exdocpicker/demo/field/ExampleExternalDocumentServiceFacade.java

Put your own implementation class in your CMS module project.

See Javadocs for detail about the ExternalSearchServiceFacade.

Plugin Parameters

You may configure the following plugin parameters in the field definition of your document template definition (a.k.a 'namespace').

Parameter name Description Example value(s) Default value(s)
caption Field caption, used as field label and dialog title. "Introductory Blog Article" "Related external documents"
external.document.service.facade org.onehippo.forge.exdocpicker.api.ExternalDocumentServiceFacade implementation class FQN. "org.onehippo.forge.exdocpicker.demo.field.ExampleExternalDocumentServiceFacade"
external.documents.container.visible Whether or not to show the currently selected external document items in the plugin.
Note: In some use cases, the facade implementation may choose to creates other compound or link fields in the document, without having to show the selected items by itself.
false true
selection.mode External document selection mode. Either 'single' or 'multiple'. If this is 'single', then users can select only one external document item in the UI. Otherwise, users can select multiple external document items. "single" or
"multiple"
"multiple"
dialog.size The size of the picker popup dialog. "width=600,height=400" "width=835,height=650"
initial.search.enabled Flag whether the popup dialog box will search external documents initially when opening up. true false
initial.search.query Search query string or search term when the initial search is made in the dialog box when opening up if initial.search.enabled is set to true.

Note: it's up to the ExternalDocumentServiceFacade implementation to determine how to deal with the search query argument.
"*" ""
page.size The page size (item count per page) in the popup dialog. 10 5
icon.style Optional style attribute for the icon image in the dialog. "WIDTH: 40px; HEIGHT: 40px"

Plugin Specific Parameters of ExampleExternalDocumentServiceFacade

The following parameters are set for the ExampleExternalDocumentServiceFacade implementation additionally.

Parameter name Description Example value(s) Default value(s)
example.external.docs.field.name The physical node property name to read from or store to when selection an external document. exdocpickerbasedemo:relatedexdocids