Exceptions

You can define user/device-specific options using the exceptions feature. Creating an exception basically means starting a new configuration different from the main one when certian matchers match. If multiple exceptions match with the current user/device, then they are merged from top to bottom creating a new configuration and if they have an order property, it will be merged too. As well as in the main configuration, it is possible to extend from extendable configurations using the extend_from advanced configuration option. Consult the Extendable Configurations section to know how two or more configurations are merged together.

info

Only in exceptions, it is possible to extend from the main configuration if the the extend_from option is used with the value base. Consult the Extendable Configurations section to know how is the process of extending configurations.

In an exception you can define all the configuration options from the main configuration and the themable configuration (excluding the Advanced Configuration Options js_variables, jinja_variables, partials, and extendable_configs). And on top of these options, the next ones will be available:

Matcher Options

This options define how an exception should match with the current user or device.

Options	Type	Required	Description
user	String or String[]	no	Name of the user(s) you would like to display this order for. This option can be set alone or combined with device, not_device, is_admin, or is_owner
not_user	String or String[]	no	Name of the user(s) you would not like to display this order for. This option can be set alone or combined with device, not_device, is_admin, or is_owner
device	String or String[]	no	Device(s) you would like to display this order for. E.g. ipad, iphone, macintosh, windows, android (it uses the device's [user-agent]). This option can be set alone or combined with user, not_user, is_admin, or is_owner
not_device	String or String[]	no	Device(s) you wouldn't like to display this order for. E.g. ipad, iphone, macintosh, windows, android (it uses the device's [user-agent]). This option can be set alone or combined with user, not_user is_admin, or is_owner
is_admin	Boolean	no	Checks if the user is admin or not. This option can be set alone or combined with user, not_user, device, not_device, or is_owner
is_owner	Boolean	no	Checks if the user is owner of the system. This option can be set alone or combined with user, not_user, device, not_device, or is_admin

Other Options

Options	Type	Required	Description
matchers_conditions	OR or AND	no	Defines if at least one of the matchers should match (OR which is the default value) or if all the matchers should match (AND)

Important

• Take into account that creating exceptions means creating a new configuration. By default, the options in the main configration will not be in the new configuration resulted from exceptions. If you would like to start with the same options from the main configuration and override some of them, you need to use the option extend_from with the value base. In this way the main configuration will be merged into the desired exception.
• Take into account that user and not_user make reference to the name of the user(s) not the usernames.
• If matchers_conditions is "OR" (default value), only one match from the matchers is needed for the exception to be picked. But if this option is "AND" then all of the matcher must match for the exception to be picked, in this case if any matcher does't match, then the exception will be discarded.
• You cannot use user and not_user at the same time, doing so will end in an error
• You cannot use device and not_device at the same time, doing so will end in an error

Short Configuration Example

YAML

<config directory>/www/sidebar-config.yaml

exceptions:
  - user:
    - 'Jim Hawkins'
    - 'Long John Silver'
    extend_from: 'base'
    title: 'My Home'
    order:
      ...
  - not_user:
    - 'John Doe'
    - 'Jack Sparrow'
    is_admin: true
    matchers_conditions: 'AND'
    order:
      ...
  - not_device: 'Android'
    order:
      ...
  - is_admin: true
    order:
      ...

JSON

<config directory>/www/sidebar-config.json

{
  ...
  "exceptions": [
    {
      "user": ["Jim Hawkins", "Long John Silver"],
      "extend_from": "base",
      "title": "My Home",
      "order": [
        ...
      ]
    },
    {
      "not_user": ["John Doe", "Jack Sparrow"],
      "is_admin": true,
      "matchers_conditions": "AND",
      "order": [
        ...
      ]
    },
    {
      "not_device": "Android",
      "order": [
         ...
      ]
    },
    {
      "is_admin": true,
      "order": [
        ...
      ]
    }
  ]  
}