HOWTO: Configure Web UI Global Settings

Nuxeo Web UI provides a simple way to configure global settings to have consistent behavior across the platform. These configurations are handled as a configuration extension.
For more details, please take a look at the HOWTO: Contribute to an Extension page.

Default Settings

The XML contribution for the configuration extension is located here and contains a set of predefined default settings using org.nuxeo.web.ui namespace.

For the moment, the default settings include:

Enrichers

In Nuxeo Platform, a concept of Content Enrichers is used for several reasons, such as to optimize the number of requests sent to the server. More details about them could be found on the Content Enrichers documentation.

By default, the following enrichers are being used:

<component name="org.nuxeo.web.ui.properties.contrib">
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">

    <!-- Enrichers -->
    <property name="org.nuxeo.web.ui.enrichers.document" list="true">hasContent</property>
    <property name="org.nuxeo.web.ui.enrichers.document">firstAccessibleAncestor</property>
    <property name="org.nuxeo.web.ui.enrichers.document">permissions</property>
    <property name="org.nuxeo.web.ui.enrichers.document">breadcrumb</property>
    <property name="org.nuxeo.web.ui.enrichers.document">preview</property>
    <property name="org.nuxeo.web.ui.enrichers.document">favorites</property>
    <property name="org.nuxeo.web.ui.enrichers.document">subscribedNotifications</property>
    <property name="org.nuxeo.web.ui.enrichers.document">thumbnail</property>
    <property name="org.nuxeo.web.ui.enrichers.document">renditions</property>
    <property name="org.nuxeo.web.ui.enrichers.document">pendingTasks</property>
    <property name="org.nuxeo.web.ui.enrichers.document">runnableWorkflows</property>
    <property name="org.nuxeo.web.ui.enrichers.document">runningWorkflows</property>
    <property name="org.nuxeo.web.ui.enrichers.document">collections</property>
    <property name="org.nuxeo.web.ui.enrichers.document">audit</property>
    <property name="org.nuxeo.web.ui.enrichers.document">subtypes</property>
    <property name="org.nuxeo.web.ui.enrichers.document">tags</property>
    <property name="org.nuxeo.web.ui.enrichers.document">publications</property>
    <property name="org.nuxeo.web.ui.enrichers.blob" list="true">appLinks</property>

  </extension>
</component>

Special HTTP Headers

Similarly, Nuxeo Platform also makes use of special HTTP headers with the same general purpose: to have more control on REST API calls. Please consider the Special HTTP Headers page to learn more about this concept and be aware of the available options.

By default, only the fetch.document HTTP header is defined to ensure that all the properties are being fetched for a given document.

<component name="org.nuxeo.web.ui.properties.contrib">
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">

     <!-- Properties to be fetched when loading current document, default 'properties' means all -->
    <property name="org.nuxeo.web.ui.fetch.document" list="true">properties</property>

  </extension>
</component>

Date Formats

Since Nuxeo Web UI is an internationalized and localized application, there is a concern with language and culture. For this reason, it is possible to configure some date and time-related formats.

By default, the dateFormat and dateTimeFormat are defined according to Moment.js syntax (check the Moment.js website for more information), since it is the library used by Web UI to manage time. Also, a firstDayOfWeek is considered to display a date picker, for example, according to cultural needs. If the variable is not customized, it will default to the most common case, which is Sunday.

An example of its usage can be found on the Nuxeo Date Picker.

<component name="org.nuxeo.web.ui.properties.contrib">
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">

    <!-- Date (time) format -->
    <property name="org.nuxeo.web.ui.dateFormat">LL</property>
    <property name="org.nuxeo.web.ui.dateTimeFormat">LLL</property>

    <!-- First Day Of Week -->
    <property name="org.nuxeo.web.ui.firstDayOfWeek"></property>

  </extension>
</component>

Timezone

By default, Web UI displays dates according to the timezone detected by the user's web browser. However, by configuring the timezone setting, it's possible to specify the name of a specific timezone (according to the IANA tz database) to be used globally instead. For the moment, the only valid value for this setting is Etc/UTC, which assumes that the time specified by the user is UTC.

<component name="org.nuxeo.web.ui.properties.contrib">
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">

    <!-- Timezone -->
    <property name="org.nuxeo.web.ui.timezone">Etc/UTC</property>

  </extension>
</component>

Others

By default, there are also two more settings defined related to Amazon S3 Direct Upload for Web UI and Page Providers. The first defines if the S3 Direct Upload is used, and the second defines the maximum number of results displayed by the Page Provider.

<component name="org.nuxeo.web.ui.properties.contrib">
  <extension target="org.nuxeo.runtime.ConfigurationService" point="configuration">

     <!-- S3 Direct upload -->
    <property name="org.nuxeo.web.ui.s3.useDirectUpload">${nuxeo.s3storage.useDirectUpload:=false}</property>

    <!-- Max Results for Tables, Grids and Lists plugged on a Nuxeo Page Provider. Falls back on elasticsearch max result window by default. -->
    <property name="org.nuxeo.web.ui.listingMaxItems">${org.nuxeo.elasticsearch.provider.maxResultWindow:=10000}</property>

  </extension>
</component>

Customize Settings

As any other configuration, the best way to create new settings or change/override the default ones, is to contribute a new extension as explained on this tutorial.

Usage Examples

When Web UI is built, these settings will be available to be used (details here).

The recommended way to access and use these settings is through Nuxeo.UI.config, and several examples can be found in Web UI.

Nuxeo App

 _computeHeaders() {
  const headers = {
    'translate-directoryEntry': 'label',
  };

  const fetch = (Nuxeo.UI && Nuxeo.UI.config && Nuxeo.UI.config.fetch) || {};

  // add required fetchers
  const required = { document: ['lock'], directoryEntry: ['parent'], task: ['actors'] };

  Object.keys(required).forEach((k) => {
    fetch[k] = fetch[k] || [];
    required[k].forEach((v) => {
      if (!fetch[k].includes(v)) {
        fetch[k].push(v);
      }
    });
  });

  // generate fetch headers
  Object.keys(fetch).forEach((f) => {
    headers[`fetch-${f}`] = fetch[f].join(',');
  });

  return headers;
},

Nuxeo Format Behavior

 /**
  * Formats a date time as a string. Default format is 'MMMM D, YYYY HH:mm'.
  * Use format "relative" to show date relative to current time
  *
  * @param {string} date the date
  * @param {string} format the format, falls back on Nuxeo.UI.config.dateFormat or 'MMMM D, YYYY HH:mm' if null.
  */
  formatDateTime(date, format) {
    return this._formatDate(date, format || (Nuxeo.UI && Nuxeo.UI.config && Nuxeo.UI.config.dateTimeFormat) || 'LLL');
  },