Document Selector Plugin - Installation

Documentation
Other

How to install the Document Selector Plugin

Let's assume we have a project generated with the Maven Archetype provided by the site toolkit . Such a Maven project contains three modules:

  • ecm
  • content
  • site

We need to add the plugin to the "ecm" module, and add some configuration to the "content" project.

Add the plugin to your CMS

First, we need to add the actual plugin jar to the CMS. In the POM of the "ecm" module, add the following dependency: 


<dependency>
  <groupId>org.onehippo.forge</groupId>
  <artifactId>docselector</artifactId>
  <version>1.01.00</version>
  <type>jar</type>
</dependency>

Add the widget to your namespace

Now we need to add the Document Selector Widget to our project namespace, so it can be used in document types.

In the "content" module, there is an XML file in src/main/resources called "myproject-namespace.xml" (replace myproject with your project's name). Add the following XML as a child node to the document's root element (<sv:node sv:name="myproject">). 



    <sv:node sv:name="docselector">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>hippo:templatetype</sv:value>
        </sv:property>
        <sv:node sv:name="hippo:nodetype">
            <sv:property sv:name="jcr:primaryType" sv:type="Name">
                <sv:value>hippo:handle</sv:value>
            </sv:property>
            <sv:node sv:name="hippo:nodetype">
                <sv:property sv:name="jcr:primaryType" sv:type="Name">
                    <sv:value>hippo:nodetype</sv:value>
                </sv:property>
                <sv:property sv:name="jcr:mixinTypes" sv:type="Name">
                    <sv:value>hippo:remodel</sv:value>
                </sv:property>
                <sv:property sv:name="hippo:uri" sv:type="String">
                    <sv:value>http://www.hippoecm.org/hst/nt/myproject/1.0</sv:value>
                </sv:property>
                <sv:property sv:name="hippo:node" sv:type="Boolean">
                    <sv:value>true</sv:value>
                </sv:property>
                <sv:property sv:name="hippo:supertype" sv:type="String">
                    <sv:value>hippo:facetselect</sv:value>
                </sv:property>
                <sv:node sv:name="hippo:field">
                    <sv:property sv:name="jcr:primaryType" sv:type="Name">
                        <sv:value>hippo:field</sv:value>
                    </sv:property>
                    <sv:property sv:name="hippo:name" sv:type="String">
                        <sv:value>location</sv:value>
                    </sv:property>
                    <sv:property sv:name="hippo:path" sv:type="String">
                        <sv:value>hippo:docbase</sv:value>
                    </sv:property>
                    <sv:property sv:name="hippo:mandatory" sv:type="Boolean">
                        <sv:value>true</sv:value>
                    </sv:property>
                    <sv:property sv:name="hippo:type" sv:type="String">
                        <sv:value>Link</sv:value>
                    </sv:property>
                </sv:node>
            </sv:node>
        </sv:node>
        <sv:node sv:name="hippo:prototype">
            <sv:property sv:name="jcr:primaryType" sv:type="Name">
                <sv:value>hippo:handle</sv:value>
            </sv:property>
            <sv:node sv:name="hippo:prototype">
                <sv:property sv:name="jcr:primaryType" sv:type="Name">
                    <sv:value>myproject:docselector</sv:value>
                </sv:property>
                <sv:property sv:name="hippo:docbase" sv:type="String">
                    <sv:value>cafebabe-cafe-babe-cafe-babecafebabe</sv:value>
                </sv:property>
                <sv:property sv:name="hippo:facets" sv:type="String">
                </sv:property>
                <sv:property sv:name="hippo:values" sv:type="String">
                </sv:property>
                <sv:property sv:name="hippo:modes" sv:type="String">
                </sv:property>
            </sv:node>
        </sv:node>
        <sv:node sv:name="hippo:template">
            <sv:property sv:name="jcr:primaryType" sv:type="Name">
                <sv:value>hippo:handle</sv:value>
            </sv:property>
            <sv:node sv:name="hippo:template">
                     <sv:property sv:name="jcr:primaryType" sv:type="Name">
                    <sv:value>frontend:plugincluster</sv:value>
                </sv:property>
                <sv:property sv:name="frontend:properties" sv:type="String">
                    <sv:value>mode</sv:value>
                </sv:property>
                <sv:property sv:name="frontend:references" sv:type="String">
                    <sv:value>engine</sv:value>
                    <sv:value>wicket.model</sv:value>
                </sv:property>
                <sv:property sv:name="frontend:services" sv:type="String">
                    <sv:value>wicket.id</sv:value>
                </sv:property>
                <sv:property sv:name="mode" sv:type="String">
                    <sv:value>edit</sv:value>
                </sv:property>
                <sv:node sv:name="root">
                    <sv:property sv:name="item" sv:type="String">
                        <sv:value>${cluster.id}.field</sv:value>
                    </sv:property>
                    <sv:property sv:name="jcr:primaryType" sv:type="Name">
                        <sv:value>frontend:plugin</sv:value>
                    </sv:property>
                    <sv:property sv:name="plugin.class" sv:type="String">
                        <sv:value>org.onehippo.forge.docselector.DocumentSelectorPlugin</sv:value>
                    </sv:property>
                    <sv:property sv:name="wicket.id" sv:type="String">
                        <sv:value>${wicket.id}</sv:value>
                    </sv:property>
                    <sv:property sv:name="wicket.model" sv:type="String">
                        <sv:value>${wicket.model}</sv:value>
                    </sv:property>
                    <sv:property sv:name="mode" sv:type="String">
                        <sv:value>${mode}</sv:value>
                    </sv:property>
                    <sv:property sv:name="type" sv:type="String">
                        <sv:value>myproject:textpage</sv:value>
                    </sv:property>
                </sv:node>
            </sv:node>
        </sv:node>
    </sv:node>

Search for the following parts in the XML you just added, and adapt them to your project's name and namespace: 


      <sv:property sv:name="hippo:uri" sv:type="String">
        <sv:value>http://www.hippoecm.org/hst2/myproject/1.0</sv:value>
      </sv:property>



      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>myproject:docselector</sv:value>
      </sv:property>

Also search for the following section. This is where you configure which document type the selector should display. All documents in the repository of that type will be listed. Replace "myproject:mydocumenttype" with your document type of choice. 


        <sv:property sv:name="type" sv:type="String">
          <sv:value>myproject:mydocumenttype</sv:value>
        </sv:property>

Also located in the "content" module inside src/main/resources is the file "myproject-types.cnd". Add the docselector type to it using the following code. Make sure you add it before the document type you want to use the document selector widget in. 

[myproject:docselector] > hippo:facetselect

Add the widget to your document type

To add the document selector widget to a document type, first locate the definition of that document type in your namespace XML document. For example, a document type named "textpage" will be defined as <sv:node sv:name="textpage">. Under sv:node[@sv:name="textpage"]/sv:node[@sv:name="hippo:nodetype"]/sv:node[@sv:name="hippo:nodetype"], add the following XML code: 


<sv:node sv:name="hippo:field">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:field</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:name" sv:type="String">
    <sv:value>document</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:path" sv:type="String">
    <sv:value>myproject:document</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:type" sv:type="String">
    <sv:value>myproject:docselector</sv:value>
  </sv:property>
</sv:node>

Again, replace "myproject" with your project's namespace prefix.

Under sv:node[@sv:name="textpage"]/sv:node[@sv:name="hippo:template"]/sv:node[@sv:name="hippo:template"], add the following XML code: 


    <sv:node sv:name="docselector">
        <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>Document</sv:value>
        </sv:property>
        <sv:property sv:name="engine" sv:type="String">
            <sv:value>${engine}</sv:value>
        </sv:property>
        <sv:property sv:name="field" sv:type="String">
            <sv:value>document</sv:value>
        </sv:property>
        <sv:property sv:name="mode" sv:type="String">
            <sv:value>${mode}</sv:value>
        </sv:property>
        <sv:property sv:name="plugin.class" sv:type="String">
            <sv:value>org.hippoecm.frontend.editor.plugins.field.NodeFieldPlugin</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>
</sv:node>

Finally, we need to add the field to the node type definition in "myproject-types.cnd" too. Locate your document type and add the following line: 

+ myproject:document (myproject:docselector)

For a "textpage" document type provided by the Maven Archetype this might look as follows: 

[myproject:textpage] > hippostd:publishable, hippostd:publishableSummary, hippo:document
- myproject:body (string)
- myproject:summary (string)
- myproject:title (string)
- myproject:date (date)
+ myproject:document (myproject:docselector)

Rebuild & Restart

Stop your CMS if it is still running, and rebuild your project using 

mvn clean install

from the project root directory. Now restart your CMS (in the "ecm" subdirectory) and open a textpage document. It should have a new field called "Document", showing as a dropdown containing a list of documents.