Fork me on GitHub

Developer's How-to: Document Field Flat 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 ExampleExternalDocumentServiceFacade having embedded external JSON data in a classpath resource: 

/hippo:namespaces/mynamespace/mydocumenttype:
  /hipposysedit:nodetype:
    /hipposysedit:nodetype:
      ...
      /relatedextdocselector:
        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.docs.field.name below.
        hipposysedit:path: exdocpickerbasedemo:relatedexdocids
        hipposysedit:primary: false
        hipposysedit:type: String
      ...
  /editor:templates:
    /_default_:
      ...
      /relatedextdocselector:
        jcr:primaryType: frontend:plugin
        caption: Related External Documents
        engine: ${engine}
        mode: ${mode}
        wicket.id: ${cluster.id}.left.item
        wicket.model: ${wicket.model}

        // Plugin class configuration for Flat List View dialog option.
        plugin.class: org.onehippo.forge.exdocpicker.impl.field.ExternalDocumentFieldSelectorPlugin
        // 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.ExampleExternalDocumentServiceFacade

        // Facade configuration: physical document node property name to store the external document IDs.
        example.external.docs.field.name: exdocpickerbasedemo:relatedexdocids

        /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/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