Virtual Navigation

You have to create a vocabulary that will be used for the new Virtual Navigation, keep in mind that you can set up a multi-level vocabulary, so you can imagine a vocabulary with parent and children. There is no limitation on this side.

You have to select the element in a schema that will store your vocabulary data. In the basic Nuxeo 5 configuration it is dublincore:coverage and dublincore:subjects that store vocabularies data for Virtual Navigation. If fact, when you select a country (coverage) in a document's meta-data, the country is stored in the dublincore:coverage element. It's not mandatory to select a dublincore element, you can select an element coming from your own schemas.

If you have a "only-one-level" vocabulary you can create a file to store it like this :

id, label, obsolete
"art","label.directories.topic.art","0"
"human sciences","label.directories.topic.humanscience","0"
"society","label.directories.topic.society","0" 
"daily life","label.directories.topic.dailylife","0" 
"technology","label.directories.topic.technology","0"
     

If you have a "multi-level" vocabulary you have to split him in sub vocabulary, and keep in mind that you have to indicate which vocabulary element is the child of which parent vocabulary element, here is an example, the full example can be found in Nuxeo 5 sources, check topic.csv and subtopic.csv:

CONTENT OF THE FIRST FILE (parents)

id, label, obsolete
"art","label.directories.topic.art","0"
"human sciences","label.directories.topic.humanscience","0"
"society","label.directories.topic.society","0" 
"daily life","label.directories.topic.dailylife","0" 
"technology","label.directories.topic.technology","0"


CONTENT OF THE SECOND FILE (with a "parent" parameter added)

id, label, parent, obsolete
"architecture","label.directories.subtopic.architecture","art","0"
"comics","label.directories.subtopic.comics","art","0"
"rights","label.directories.subtopic.rights","human sciences","0"
"economy","label.directories.subtopic.economy","human sciences","0"
...

When you have created your different files for vocabularies you have to register them in an extension point as new vocabularies. In an xml file that you won't forget to place in a OSGI-INF directory and won't forget to register in the MANIFEST.MF file of the package, you have to contribute the following extension point.

For a full example you can check the nxdirectories-contrib.xml file of the webapp-core package. Don't forget to use the xvocabulary schema if your vocabulary is a child of another, if the vocabulary is the first parent or is alone just use the vocabulary schema. Don't forget to indicate the parent if your vocabulary has more than one level with the following tag <parentDirectory></parentDirectory>.

<extension target="org.nuxeo.ecm.directory.sql.SQLDirectoryFactory"
  point="directories">

//here your new vocabularies contribution

</extension>
     

The query based search service of Nuxeo 5 requires that you create a document type that will be a base for a document model to register data handled by the query. To understand it more here is an example:

You are browsing your documents by coverage. You are selecting the path Europe/France in the tree. The data Europe/France is the base of the query and need to be registered in a document model created from a document type. In this case the document type can be very simple, cause the query must register only one data at a time. Creating a document type with only one schema that contains one field will be enough.

This document type will be referenced as query document type in this walkthrough. Create it and register it as a normal document type. See Nuxeo Book part 6 to get more informations about document type creation.

Now you must contribute to another extension point to create a new navigation tree based on vocabularies you contributed just before. See below for an example of the file you have to create. For a full example you can see the directorytreemanager-contrib.xml file in the virtualNavigation package.

The new tree contribution needs many informations, a queryModel to indicate the query you will use to get your documents, a schema and a field coming from the query document type you just set up in part 3, an outcome that indicates the page where documents will be displayed after the request and a list of vocabularies you can indicate with the tag <directory></directory>.

<require>
  org.nuxeo.ecm.webapp.directory.DirectoryTreeService
</require>

<extension
  target="org.nuxeo.ecm.webapp.directory.DirectoryTreeService"
  point="trees">

//here your new navigation tree contribution

</extension>

Now you need to contribute to 2 extension points that will set up the query and the results provider. Here are the 2 extension point you will need to contribute. For a full example see the file querymodel-contrib.xml and resultsprovider-contrib.xml in the virtualNavigation package.

The query model contribution needs many information. In the docType parameter you have to put the name of the documentType you created in part 3. In the <predicate></predicate> tag you must set up the name of the element (field) that is the field storing the data used for virtual tree construction.

EXAMPLE :

You want to browse documents by coverage, each of your document have a coverage registered in dc:coverage field. You have to use the dc:coverage parameter.

If there is no prefix set the name like this schema:field, if there is a prefix set it up like this prefix:field. In the operator param put the value STARTSWITH. In the <field/> tag put the schema and the name of the field coming from the query document type you set up in part 3.

<extension
   target="org.nuxeo.ecm.core.search.api.client.querymodel.QueryModelService"
   point="model">

//Here your new query model

</extension>


<extension
    target="org.nuxeo.ecm.webapp.pagination.ResultsProviderService"
    point="model">

//Here your new result provider

</extension>

Now you need to register a new indexing configuration in the search service. You will index the field that register the data you want to apply the search on, it is the same data as saw at the end of part 5 . Here is the extension point you have to contribute. For a full example see the nxsearch-contrib.xml file in the search-core package.

You will have to create a new <resource></resource> tag if it doesn't exist for your schema. For the name parameter you have to put the name of your schema, type param must be "schema" and indexAllFields param must be "true". In a <field/> tag you have to indicate the indexing strategy, the type param must be "Path", if the field that register your vocabulary is a complexType (list of String for example) you can add the parameter multiple and set it at "true".

<extension
    target="org.nuxeo.ecm.core.search.service.SearchServiceImpl"
    point="resource">

//Here your new search configuration

</extension>

You must not forget to add some navigation cases in a deployment-frgament.xml file. Those navigation cases must correspond at each outcome you set up in part 3. Each page named in navigation cases shall display search result so you have to customize those pages with the good queryModel call. For a full example see coverage_virtual_navigation.xml .

All theme contributions and tree navigation widget already exist in webapp-core and virtualNavigation package, you can take a look for information purpose.

Indeed you have to add vitualNavigation to Nuxeo 5 plugin if you want a fully fonctional Virtual Navigation immediatly.