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 Studio Modeler
• The Web UI addon installed on your instance

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

Create a Page Provider

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

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.

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 Form Layout

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

Click on Customize, two layouts are available. Let's edit the Form layout.

1. Click on Form, then Customize. The form layout is now displayed in bold with an asterisk next to it. 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. Click on the Full text one, on the right you can edit the label to display Full text.

You now need to add your labels to your translations file to display them correctly in the UI. To do so:

1. Click on the UI table.
2. Click on Translations.
3. Use the default messages.json or create your own language.
4. Create a new entry in the JSON file with key label.ui.aggregate.<label> and the label as value. Here it's:
   • "label.ui.aggregate.from_now-1y_to_now-1M":"Last year",
   • "label.ui.aggregate.from_now-1M_to_now-7d":"Last month",
   • "label.ui.aggregate.from_now-7d_to_now-24H":"Last week",
   • "label.ui.aggregate.from_now-24H_to_now":"Last 24H"

Create a Drawer

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 Drawer.
2. Roll over the Create button and select the Search type .
3. Fill in the page like this:
   • Name: Contract
   • Available: enabled
   • provider: Search
   • schemas: dublincore, contract
   • search-name: search
   • name: contract
   • Label: Contracts
   • Icon: icons:assignment
4. Expand the Elements & Attributes box and check the Auto attribute to automatically execute the search each time a param is changed.
5. 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.html contributes the Default Search and the nuxeo-expired-search.html contributes the Expired Search.

$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-assets-search.html
│   ├── nuxeo-default-search.html
│   ├── nuxeo-expired-search.html
│   ├── nuxeo-saved-search-actions.html
│   ├── nuxeo-search-form.html
│   └── nuxeo-search-results.html
├── ...
...

Referring to Web UI deployment documentation, you can override these nuxeo-default-search.html and nuxeo-expired-search.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 thanks to the SEARCH_MENU_BUTTONS slot.

The DAM Example

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

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

Here are some explanations about nuxeo-menu-icon properties:

route="search:assets"

will trigger a navigation to /search/assets.

Navigating to /search/assets will display the search filters form defined by nuxeo-assets-search.html in the left drawer menu content. Note that this is only possible because it is convention-based:

• nuxeo-assets-search.html is deployed in the $NUXEO_SERVER/nxserver/nuxeo.war/ui/search directory.

• the name of nuxeo-assets-search.html is in the form nuxeo-{searchName}-search.html where {searchName} is assets and matches the second part of the routing directive:

  route="search:assets"
  

  on the nuxeo-menu-icon.

  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 directory. However, it is important that this elements provides the proper information to perform the search.