Fork me on GitHub

Developer's How-to: Document Field Tree List Picker

Configuring Field in Document Type Definition

You should add a custom field configuration like the following example in YAML format. This is an example with ExampleExternalSubjectCategoryServiceFacade having embedded external XML data in a classpath resource: 

/hippo:namespaces/mynamespace/mydocumenttype:
  /hipposysedit:nodetype:
    /hipposysedit:nodetype:
      ...
      /externaltaxonomyselector:
        jcr:primaryType: hipposysedit:field
        hipposysedit:mandatory: false
        // flag indicating whether the data is saved by the facade implementation as single or multiple string
        hipposysedit:multiple: true
        hipposysedit:ordered: false
        // property name to store the external document IDs. In this case, same as example.external.cats.field.name below.
        hipposysedit:path: exdocpickerbasedemo:excategories
        hipposysedit:primary: false
        hipposysedit:type: String
      ...
  /editor:templates:
    /_default_:
      ...
      /externaltaxonomyselector:
        jcr:primaryType: frontend:plugin
        caption: External Taxonomy
        engine: ${engine}
        mode: ${mode}
        wicket.id: ${cluster.id}.left.item
        wicket.model: ${wicket.model}

        // Plugin class configuration for Tree List View dialog option.
        plugin.class: org.onehippo.forge.exdocpicker.impl.field.tree.ExternalTreeItemFieldSelectorPlugin
        // 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.
        initial.tree.expand.depth: '1'
        // Item selection mode plugin parameter: single or multiple
        selection.mode: multiple

        // ExternalDocumentServiceFacade class FQN plugin parameter.
        external.document.service.facade: org.onehippo.forge.exdocpicker.demo.field.tree.ExampleExternalSubjectCategoryServiceFacade

        // Facade configuration: Physical document node property name to store the external document IDs. This is used by the implementation (ExampleExternalSubjectCategoryServiceFacade).
        example.external.cats.field.name: exdocpickerbasedemo:excategories

        /cluster.options:
          jcr:primaryType: frontend:pluginconfig

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