HOWTO: Customize Searches

After having created your own document type you will probably want to create your own search.

We will learn how to create a new search screen with an icon in the left menu. The search will be compose of a full text search, a search by date range, a search by owners and finally by tags.

Prerequisites

• A Contract document type created in Nuxeo Studio
• The Web UI addon installed on your instance

Once you are all set, you can navigate to Nuxeo Studio to start creating your search.

Create a Page Provider

The first step is to create a page provider in Nuxeo Studio.

In Configuration, go to Page Providers, click on New and name it Search.

The full text search:

1. Next to Predicates click on Add. A popup window appears.
2. Click on Edit binding and select schema:system > fulltext.
3. Save your changes.

The search by date range:

1. Next to Aggregates click on Add. A popup window appears.
2. Fill the popup window like this:

   Field	dc:created
   Date Ranges	Label: Last year From: now-1y To: now-1M Label: Last month From: now-1M To: now-7d Label: Last week From: now-7d To: now-24H Label: Last 24h From: now-24H To: now

The search by tags:

1. Add another new Predicates.
2. Click on Edit binding and select schema:system > tag[].

The search by owner of the contract:

1. Add another new Predicates.
2. Click on Edit binding and select schema:contract > owner.

You can now save your changes and go to the Studio Designer.

Create a Search Layout

In the Studio Designer, in the UI tab, under Layouts > Page Providers you will find your page provider created previously.

Click on your page provider, two layouts are available. Let's edit the Form layout first.

1. Click on form, then Customize. The form layout is now displayed in bold. On the right, in the properties catalog, the elements that we defined in Studio are displayed here.
2. Expand the first element and drag and drop the Edit mode into the editor. Do the same for the three other elements.
3. Once it's done, click on the Full text element on the main view, you can edit the label in the left catalog to display Full text. You can do the same with the other elements.

Let's customize the results layout now.

1. Click on results, then Customize.
2. It automatically creates the result view by default. Leave it like this and click on Save.

Create a New Left Menu Item

The next step is to add a button in the left menu to display the search screen.

1. Go to the UI tab in the Studio Designer and then on Left Menu Items.
2. Roll over the Create button and select the Search type .

3. Fill in the page like this:

   • Name: Contract
   • Available: enabled
   • Label: Contracts
   • Icon: icons:assignment
   • provider: Search
   • schemas: dublincore, contract
   • search-name: search
   • auto: enabled

4. Save your changes, deploy your Studio project on your instance and you're done :)

Technical Overview

Overriding Existing Nuxeo Web UI Search

Nuxeo Web UI comes with the Default Search and Expired Search both plugged on server side page providers default_search and expired_search by default.

Within the Web UI, a search is composed of 2 main parts:

• the search form displayed on the left in the drawer panel.

• the search result panel displayed on the right in the main content.

  ×
  

The search form itself has 2 rendering modes:

• filter mode where you can set filter and criteria. Each time a filter changes, it updates the results displayed in the main container.
• queue mode where search results are displayed with a vertical scroll (like in the expired search screenshot above).

A toggle button allows you to switch between filter mode and queue mode.

The search form is a dynamically loaded element. For instance, nuxeo-default-search-form.html and nuxeo-default-search-results.html contribute the Default Search form and results layouts and the nuxeo-expired-search-form.html and nuxeo-expired-search-results.html contribute the Expired Search form and results layouts.

$NUXEO_SERVER/nxserver/nuxeo.war/ui% tree
.
├── document
│   ├── ...
├── elements.html
├── favicon.ico
├── i18n
│   ├── ...
├── images
│   ...
├── index.jsp
├── manifest.json
├── nuxeo-admin
│   ├── ...
├── nuxeo-dam
│   ├── ...
├── nuxeo-drive
│   ├── ...
├── nuxeo-home.html
├── nuxeo-liveconnect
│   ├── ...
├── nuxeo-user-group-management
│   ├── ...
├── search
│   ├── nuxeo-saved-search-actions.html
│   ├── nuxeo-search-form.html
│   ├── default
│   │   ├── nuxeo-default-search-form.html
│   │   ├── nuxeo-default-search-results.html
│   ├── expired
│   │   ├── nuxeo-expired-search-form.html
│   │   ├── nuxeo-expired-search-results.html
├── ...
...

Referring to Web UI deployment documentation, you can override these nuxeo-default-search.html and nuxeo-expired-search-form.html in order to customize the Default Search and Expired Search filter form. To do so, your own marketplace must deploy and override the proper HTML files in $NUXEO_SERVER/nxserver/nuxeo.war/ui/search.

Add New Searches

You can insert a new search in the left drawer menu the same exact way you insert any slot contribution to it, by using the DRAWER_ITEMS slot.

The DAM Example

The Nuxeo DAM addon defines its own Asset Search with the following:

<nuxeo-slot-content name="damSearchMenuButtons" slot="DRAWER_ITEMS" order="45">
  <template>
    <nuxeo-menu-icon id="assetsSearchButton" name="assetsSearch" icon="icons:perm-media" label="dam.assets.heading">
    </nuxeo-menu-icon>
  </template>
</nuxeo-slot-content>

And the corresponding DRAWER_PAGE slot, containing a nuxeo-search-form element.

<nuxeo-slot-content name="damSearchMenuButtons" slot="DRAWER_PAGES">
  <template>
    <nuxeo-search-form name="assetsSearch" search-name="assets" auto display-auto-control
                       provider="assets_search"
                       schemas="dublincore,common,uid,thumbnail"></nuxeo-search-form>
  </template>
</nuxeo-slot-content>

Here are some explanations about nuxeo-menu-icon and nuxeo-search-form properties:

name="assets"

The nameproperty links the nuxeo-menu-iconto the nuxeo-search-form, so that clicking the former will trigger the latter to show.

search-name="assets"

The search-name property defines the name of the search and it is used to support the for the dynamic loading of the search-form as follows:

Navigating to /search/assets will display the search form and searh results defined by nuxeo-assets-search-form.html and nuxeo-assets-search-results.html. This is only possible because they follow the following convention:

• they are both located on the $NUXEO_SERVER/nxserver/nuxeo.war/ui/search/assets which has the same name as the search-name property

• the name of nuxeo-assets-search-form.html and nuxeo-assets-search-results.html are in the form nuxeo-{searchName}-search-form.html and nuxeo-{searchName}-search-results.html respectively where {searchName} is assets, matching the search-name property of the nuxeo-search-form element, and are both placed on the assets directory mentioned above.

  search-name="assets"
  

  Please refer to the Web UI routing documentation for further details.

icon="icons:perm-media"

defines the icons to be displayed in the left drawer menu.

label="dam.assets.heading"

is the key label to be retrieved from i18n resources to be used as tooltip in the left drawer menu.

Meaningful Properties When Defining Your Own Search

As just explained, to create a search, you just need to deploy a new nuxeo-{searchName}-search.html element in your $NUXEO_SERVER/nxserver/nuxeo.war/ui/search/{searchName} directory and add it as a slot contribution using the nuxeo-searh-form element. However, it is important that these elements provides the proper information to perform the search.