Fork me on GitHub

Developer's How-to (Tree 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 ExampleExternalSubjectCategoryServiceFacade having embedded external XML 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="externaltaxonomyselector">
        <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>External Taxonomy</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}.left.item</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 Tree List View dialog option. -->
        <sv:property sv:name="plugin.class" sv:type="String">
          <sv:value>org.onehippo.forge.exdocpicker.impl.field.tree.ExternalTreeItemFieldSelectorPlugin</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>

        <!--
          Initial tree expanding depth parameter. The default setting is 0.
          If set to a positive number, tree will be expanded to show all the nodes up to the configured depth level initially.
        -->
        <sv:property sv:name="initial.tree.expand.depth" sv:type="String">
          <sv:value>1</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.tree.ExampleExternalSubjectCategoryServiceFacade</sv:value>
        </sv:property>

        <!-- Physical document node property name to store the external document IDs. This is used by the implementation (ExampleExternalSubjectCategoryServiceFacade). -->
        <sv:property sv:name="example.external.cats.field.name" sv:type="String">
          <sv:value>exdocpickerbasedemo:excategories</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/tree/ExampleExternalSubjectCategoryServiceFacade.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. "External Taxonomy" "Related external documents"
external.document.service.facade org.onehippo.forge.exdocpicker.api.ExternalDocumentServiceFacade implementation class FQN. "org.onehippo.forge.exdocpicker.demo.field.tree.ExampleExternalSubjectCategoryServiceFacade"
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.tree.expand.depth The depth of tree nodes to which the popup dialog should show initially by expanding its ancestor tree nodes. The depth of the root tree node(s) is 0. So, if this is set to 2 for instance, all the tree nodes up to the depth of 1 will be expanded initially, in order to show all the tree nodes up to the depth of 2. 1 0

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.cats.field.name The physical node property name to read from or store to when selection an external document. exdocpickerbasedemo:excategories