Web UI

HOWTO: Customize Searches

Updated: July 25, 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 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 View Designer.

Create a Search Layout

In the View Designer, on the Layouts tab, under 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'n'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.

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 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 View 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

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-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.

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.

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
queue Boolean property. If true, then the queue will be displayed by default instead of search filters. expired_search displays a queue by default
auto Boolean property. If true, automatically execute the search each time a param is changed. auto search
label String property. The key to the i18n label to be shown as the search title expiredSearch.expiredDocuments search
search-name String property. The name of the search layout, as explained above expired name-search
23 days ago manonlumeau NXDOC-1270-review-how-tos
a month ago Andrew Goodricke Merge branch 'master' into web-ui-1.0
a month ago manonlumeau NXDOC-1254: updates web-ui documentation to v1.0
a month ago manonlumeau NXDOC-1254: adds search-form properties. fixes broken link on webui-routing
a month ago manonlumeau Fix typo
a month ago manonlumeau Fix capitalization
3 months ago GitHub Fix error in scenario
3 months ago Manon Lumeau fix link to page provider page
3 months ago manonlumeau NXDOC-1181:WIP
3 months ago manonlumeau Add howto info in frontmatter
History: Created by manonlumeau