Web UI

HOWTO: Customize Searches

Updated: May 22, 2017 Page Information Edit on GitHub

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.

View Designer is not available for everyone yet, but if you can't wait any longer to try it, do not hesitate to contact your sales representative to enable it on your project.

Prerequisites

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 Customization, 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 View Designer.

Create a Form Layout

In the View Designer, on the Layout tabs, under 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'n'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 View 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

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.

Default search Expired search

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.

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.

Property Description Example
provider the name of the page provider to be used, defined server side default_search page provider
schemas a comma-separated value list of schema names to be fetched when loading documents retrieved by the search schemas needed for default search
displayQueue boolean property. If true, then the queue will be displayed by default instead of search filters expired_search displays a queue by default

It is not possible to customize the screen showing search results in the main container yet.

a month ago GitHub Fix error in scenario
a month ago Manon Lumeau fix link to page provider page
2 months ago manonlumeau NXDOC-1181:WIP
2 months ago manonlumeau Add howto info in frontmatter
History: Created by manonlumeau