In a namespace bootstrap YAML file, you should add a custom field like the following example (an example with SimpleJPQLExternalDocumentServiceFacade executing JPQL queries against external database):
/hippo:namespaces/mynamespace/mydocumenttype:
/hipposysedit:nodetype:
/hipposysedit:nodetype:
...
/informantextdocselector:
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 example, same as example.external.docs.field.name below.
hipposysedit:path: exdocpickerbasedemo:informantids
hipposysedit:primary: false
hipposysedit:type: String
...
/editor:templates:
/_default_:
...
/informantextdocselector:
jcr:primaryType: frontend:plugin
caption: Informant
engine: ${engine}
mode: ${mode}
wicket.id: ${cluster.id}.left.item
wicket.model: ${wicket.model}
// plugin with configuration properties
plugin.class: org.onehippo.forge.exdocpicker.impl.field.ExternalDocumentFieldSelectorPlugin
initial.search.enabled: true
selection.mode: multiple
external.document.service.facade: org.onehippo.forge.exdocpicker.demo.jpa.field.SimpleJPQLExternalDocumentServiceFacade
// custom facade configuration properties
jpql.external.docs.field.name: exdocpickerbasedemo:informantids
jpql.item.description.prop: description
jpql.item.iconlink.prop: photo
jpql.item.id.prop: id
jpql.item.id.type.prop: long
jpql.item.search.query: SELECT i FROM Informant i WHERE i.id = :id
jpql.item.search.query.param: id
jpql.item.title.prop: name
jpql.persistence.unit: newsPU
jpql.term.search.query: SELECT i FROM Informant i
jpql.term.search.query.param: ''
/cluster.options:
jcr:primaryType: frontend:pluginconfig
See the following for a full example in the demo project: https://github.com/bloomreach-forge/external-document-picker/tree/master/demo/bootstrap/configuration/src/main/resources/namespaces/exdocpickerbase-demo/newsdocument.xml
See an example JPA/JPQL based ExternalDocumentServiceFacade implementation code here:
https://github.com/bloomreach-forge/external-document-picker/tree/master/demo/cms/src/main/java/org/onehippo/forge/exdocpicker/demo/jpa/field/SimpleJPQLExternalDocumentServiceFacade.java
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. | "Informant" | "Related external documents" |
| external.document.service.facade | org.onehippo.forge.exdocpicker.api.ExternalDocumentServiceFacade implementation class FQN. |
"org.onehippo.forge.exdocpicker.demo.jpa.field.SimpleJPQLExternalDocumentServiceFacade" | |
| 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 |
The following parameters are set for the SimpleJPQLExternalDocumentServiceFacade implementation
additionally.
| Parameter name | Description | Example value(s) | Default value(s) |
|---|---|---|---|
| jpql.external.docs.field.name | The physical node property name to read from or store to when selection an external document. | exdocpickerbasedemo:informantids | |
| jpql.persistence.unit | JPA persistence unit name defined in persistence-unit.xml | newsPU | |
| jpql.term.search.query | JPQL full text search statement to find multiple external documents by a search term when user enters a search term and clicks on the search button in the picker dialog. | SELECT i FROM Informant i | |
| jpql.term.search.query.param |
If there is a named parameter in 'jpql.term.search.query' property, then you can specify the parameter name
in this property.
For example, if 'jpql.term.search.query' is set to 'SELECT i FROM Informant i WHERE i.name = :name', then you can set this property to 'name'. |
||
| jpql.item.search.query | JPQL search query statement to find single external document by a parameter such as ID. | SELECT i FROM Informant i WHERE i.id = :id | |
| jpql.item.search.query.param |
If there is a named parameter in 'jpql.item.search.query.param' property, then you can specify the parameter name
in this property.
For example, if 'jpql.item.search.query.param' is set to 'SELECT i FROM Informant i WHERE i.id = :id', then you can set this property to 'id'. |
id | |
| jpql.item.id.prop |
The ID property name to retrieve after selecting a JPA POJO bean.
For example, if the JPQL query selects multiple Informant beans and user selects one from it, then
the plugin will need to retrieve the ID property from the Informant bean instance.
If this property is set to 'id' for instance, then the plugin will invoke Informant#getId() to retrieve
the ID in the end.
|
id | |
| jpql.item.id.type.prop | The type of the ID property of the JPA POJO bean. It must be 'int', 'long', 'float', 'double' or 'String'. This type information is used for the parameter when executing the JPQL query configured by 'jpql.item.search.query' property. | long | |
| jpql.item.title.prop |
The title property name to display in the picker dialog after selecting a JPA POJO bean.
For example, if the JPQL query selects multiple Informant beans and user selects one from it, then
the plugin will need to retrieve the title property from the Informant bean instance.
If this property is set to 'name' for instance, then the plugin will invoke Informant#getName() to retrieve
the title in the end.
|
name | |
| jpql.item.description.prop |
The description property name to display in the picker dialog after selecting a JPA POJO bean.
For example, if the JPQL query selects multiple Informant beans and user selects one from it, then
the plugin will need to retrieve the description property from the Informant bean instance.
If this property is set to 'description' for instance, then the plugin will invoke Informant#getDescription() to retrieve
the title in the end.
|
description | |
| jpql.item.iconlink.prop |
The icon URL link property name to display in the picker dialog after selecting a JPA POJO bean.
For example, if the JPQL query selects multiple Informant beans and user selects one from it, then
the plugin will need to retrieve the icon URL link property from the Informant bean instance.
If this property is set to 'photo' for instance, then the plugin will invoke Informant#getPhoto() to retrieve
the icon URL link in the end.
|
photo |