Settings Search Index

App Suite provides a searchable settings interface, where every app can provide its own set of search terms. Each entry for the search index has to be provided individually as follows:

[
  {
    title: <String>, // mandatory
    additionalTerms: <Array[String]>, // optional
    requires: <String|Function>, // optional. defaults to true
    highlight: <Selector|Function>, // optional
  },
  {
    ... // next search term
  }
  ...
]

Fields

title

The title of the search term. This is part of the index and will be displayed as a search result. This field is mandatory.

additionalTerms

A set of additional terms that can be used as alternative expressions to search for. Those will never be displayed to the user.

requires

This is used to programmatically remove the entry from the search index depending of the state of the application. It is either a capability string (e.g. 'read_create_shared_folders || caldav') or a function that returns true when this entry should be part of the index, and false otherwise. The function can also return a Promise that resolves with true/false.

highlight

A selector to a node to highlight or a function returning the corresponding node as jQuery object. If the provided element is a focusable element, the highlighting might automatically choose a more visible element to be highlighted (e.g. the label of a checkbox), even though the focus will stay on exactly that element. Therefore, it is recommended to return focusable elements with this method.

How to use

There a two different ways to provide a search index entry. First, as part of an app with settings. The search terms should be provided as an array as follows:

ui.createApp({
    id: 'io.ox/mail',
  name: 'io.ox/mail',
  title: gt.pgettext('app', 'Mail'),
  requires: 'webmail',
  refreshable: true,
  searchable: true,
  settings: () => import('@/io.ox/mail/settings/pane.js'),
  settingsSearchTerms: [{
    title: gt('Vacation notice'),
    additionalTerms: [gt('Out of office')],
    async requires () {
      if (!capabilities.has('mailfilter_v2')) return false
      const { default: mailfilter } = await import('@/io.ox/core/api/mailfilter')
      const config = await mailfilter.getConfig()
      return !!_(config.actioncmds).findWhere({ id: 'vacation' })
    },
    highlight: 'button[data-action="edit-vacation-notice"]'
  }
  ...]
})

Or alternatively directly on a settings extension point:

ext.point('io.ox/settings/pane/tools').extend({
  id: 'zoom',
  title: gt('Zoom Integration'),
  ref: 'io.ox/switchboard',
  index: 10,
  load: () => import('@/io.ox/switchboard/settings/pane.js'),
  searchTerms: [{
      title: gt('Always add a random meeting password'),
      highlight: '#io-ox-switchboard-zoom-addmeetingpassword'
  }
  ...]
})

Additional notes

• It is recommended to translate the searchable terms with gt.

• It is worth noting that each settings pane will automatically contain a search term for the whole page itself and therefore no extra entry is needed.