HOWTO: Configure Searches

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

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 Modeler
• Make sure that the Nuxeo Web UI addon is 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 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.
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:

   Aggregate Type	Date Range
   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.
3. Save your changes.

Now, click on Configure layouts in Designer at the top-right of your screen. You are now in Studio Designer, where you can configure the layouts of your Search.

Create a Search Layout

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

Two layouts are available. Let's edit the form layout first.

1. Click on form, then Configure.
   The form layout is now displayed in bold. On the right, in the properties catalog, the elements that we defined in Studio are displayed.
2. Click on the System Fulltext 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 configure the results layout now.

1. On the left menu, click on results, then Configure.
2. It automatically creates the result view by default (grid and table). Leave it like this and click on Save.

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 New Drawer Item

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

1. Go back to your Search page provider, in Modeler.
2. In the Bind more elements section, select Drawer item search to create your menu item.
3. Fill in the page like this:
   • Name: Contract
   • Available: enabled
   • Label: Contracts
   • Icon: icons:assignment
   • provider: Search
   • schemas: dublincore, contract
   • search-name: search
4. Click on Show Advanced Options:
   • auto: enabled
5. Save your changes, deploy your Studio project on your instance and you're done :)

Going Further

Visually Configure Table Results Layout

In Studio Designer's layout tab:

1. Go back to your Search page provider results layout configuration.
   ×
   
2. Edit the table layout configuration.
   ×
   
3. You will be taken to the element's configuration. From there, click on the Switch to Table Editor icon at the bottom of the page.
   ×
   

You are now in the table editor.

Each result column is shown with the corresponding field and element. Clicking on an element will display its properties on the right side of the screen so that you can configure it.

More columns can be added using drag and drop from the catalog on the right side of the screen. For each column, the label can be edited directly and translated by entering the [[i18n('your.translation.key')]] pattern.

Columns can be reordered by drag and dropping them around.

Finally, when hovering on a column, you can use additional icons to configure them:

• The arrows icon toggles the possibility to sort results using this column.

• The eye icon toggles the default visibility of the column. If you make it optional, it won't appear by default but can be made visible by users in Web UI. When made visible, it will be placed exactly where you put it in your configuration.

• The trash icon deletes the column.

When you are finished, click on Save work in progress at the top right of the screen.

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 to the Default Search form and results layouts and the nuxeo-expired-search-form.html and nuxeo-expired-search-results.html contribute to 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 search 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-search-form element. However, it is important that these elements provide the proper information to perform the search.

---