Custom Panels

since v2.10.0

Karma offers rich configuration possibilities to customize the view of user and account overview pages through panels. You can configure multiple panels per user / account and define per panel which attribtues are shown and also how they are displayed.

Configuring user, account and role panels

All panels are displayed in the configured order on the users / accounts overview page. The first configured panel (considered the main panel) is shown on the users details page for the specific user and each corresponding account as well.

Panels are basically configured in your default configuration file, e.g. config/local.yaml. You can decide whether you want to configure your panels directly in the users / account section or whether you prefer re-usable presets that can be referenced in users and accounts.

Example for simple configuration in users section (the same config applies to accounts)

users:
  # example: panels inline
  panels:
    -
      # configuration for first panel
    -
      # configuration for second panel
    -
      # configuration for third panel
    # ...

  # example: panels config as separate file (relative to config directory)
  panels: 'panels.yaml'

Example for using presets:

# show presets `main`, `detailAttributes`, `passwordStatus` for users
users:
  # ...
  panels:
    - { preset: 'main' }
    - { preset: 'detailAttributes' }
    - { preset: 'passwordStatus' }

# show only the preset `passwordStatus` for accounts
accounts:
  # ...
  panels:
    - { preset: 'passwordStatus' }

Panel Presets

Allows to define shared presets for panels and rows.

# define panel presets (inline or in a separate file)
panelPresets:
  # presets for panels
  panels:
    # panel names can be chosen freely
    main:
      # ...
    detailAttributes:
      # ...
    passwordStatus:
      # ...
  
  # presets for rows
  rows:
    fullName:
      # ...

# example: panels presets as separate file (relative to config directory)
panelPresets: 'panel-presets.yaml'

Example panel-presets.yaml:

# presets for panels
panels:
  # panel names can be chosen freely
  main:
    # ...
  detailAttributes:
    # ...
  passwordStatus:
    # ...

# presets for rows
rows:
  fullName:
    # ...

Example

This section provides example panel preset configurations

panelPresets:
  panels:
    main:
      header: { label: '{{entry.$type}}s.panelHeaderPrefix', preset: 'link' }
      rows:
        - { preset: 'fullName' }
        - { label: 'users.detail.overview.login', attribute: '$name' }
        - { attribute: 'workforceId' }
        - { attribute: 'mail', forEach: 'mail', template: '<a href="mailto:{{entry.mail}}">{{entry.mail}}</a>' }
        - { preset: 'phones', attributes: 'telephoneNumber facsimileTelephoneNumber' }
        - { attribute: 'roomNumber' }
        - { preset: 'address' }
    detailAttributes:
      header: { label: 'Attributes' }
      rows:
        - { resolve: 'directReports', preset: 'link', style: 'warning' }
        - { attribute: 'employeeNumber' }
        - { attribute: 'employeeStatus' }
        - { attribute: 'employeeType' }
    passwordStatus:
      header: { label: 'Passwortstatus' }
      permission: 'can view password status'
      rows:
        - { label: 'Password required', template: '<span class="fa fa-fw fa{{["", "-check"][+entry.passwordRequired]}}-square-o"></span>' }
        - { label: 'Password change allowed', template: '<span class="fa fa-fw fa{{["", "-check"][+entry.passwordAllowChange]}}-square-o"></span>' }
        - { label: 'Unique password required', template: '<span class="fa fa-fw fa{{["", "-check"][+entry.passwordUniqueRequired]}}-square-o"></span>' }
  rows:
    fullName:
      label: 'Name'
      template: 'entry.fullName || [entry.title, entry.givenName, entry.sn].filter(Boolean).join(" ")'

Panel configuration options

A single panel offers the following configuration options

The properties label, style, icon, template, placeholder allow template expressions like

  • html escaped value: {{ entry.bar }} or {%- entry.bar %}
  • raw (no escape) value: {%= entry.bar %}
  • evaluate: <ul>{% _.forEach(entry.mail, function(mail) { %}<li>{{ mail }}</li>{% }); %}</ul>

permission

Defines a permission that must be assigned to the logged-in user for the panel to be displayed. If permission is not set, all users can view the panel.

panelPresets:
  panels:
    main:
      # ...
      permission: 'can view main panel'

allowEmpty

By default, an empty row will not be displayed. If all rows of a panel are empty, the according panel will not be displayed. This behaviour can be overwritten by setting allowEmpty to true. This setting instructs Karma to show the panel even if it is empty.

panelPresets:
  panels:
    main:
      # ...
      allowEmpty: true

style

Allows to define custom css classes for the panel. Pre-defined classes are: primary, success, info, warning, danger

panelPresets:
  panels:
    main:
      # simple example
      style: 'warning my-custom-panel-class'
      # advanced example: display based on attribute value
      style: '{{ {"true": "danger", "false": "info"}[+entry.isDisabled] }}'

rows

rows is an array of objects. Each object represents a single row within a panel. See below for possible configuration options.

header

Configures the panel header.

panelPresets:
  panels:
    main:
      # example for a simple header
      header: { label: 'my.panel.header' } # the label attribute will be translated

      # example for a link to the according object (e.g. user)
      header: { label: '{{entry.$type}}s.panelHeaderPrefix', preset: 'link' }

Note: All row configuration options, except forEach, resolve, permission, are supported as well.

Row configuration options

label

translation key for a label shown on the left side of the row (default: {{ entry.$type || 'user' }}s.detail.overview.${attribute} / required if template is used)

placeholder

translation key for a placeholder that is displayed if the value is empty (by default the row won't be displayed)

allowEmpty

if true, the row will be shown even if there is no value or placeholder

permission

the permission required to view the row (if not set, the row will be shown)

style

defines one or more css classes. Pre-defined classes are: 'primary', 'success', 'info', 'warning', 'danger', 'muted'

icon

an icon to be shown in front of the value (list of possible icons: https://fontawesome.com/v4.7.0/icons/). The icon must be prefixed with fa-

attribute

the entry attribute that shall be shown (optional if template is used)

forEach

Can be used to iterate over multivalue attributes and render a template for each value. It is used in conjunction with template, e.g.: { forEach: 'mail', template: '<a href="mailto:{{entry.mail}}">{{entry.mail}}</a>' }

template

template to render (optional if 'attribute' or 'link' is used). Must be used in conjuntion with 'label'

Example: <span class="my-custom-class">{{entry.title}} {{entry.givenName}} {{entry.sn}}</span>

preset

a pre-defined template, Karma ships with templates: 'address', 'link', 'phones'.

You can define you own presets in panelPresets.rows

attributes

configured presets or templates rely on a specified set of attributes (e.g. 'phones' shows fascimileTelephoneNumber, telephoneNumber and mobile). With this setting you can restrict the attributes that are avaiable within the preset or template

link

boolean to indicate to render a link to the referenced entry; if this is used 'template' and 'attribute' are both optional; default is false

resolve

attribute referencing (DN) an LDAP object to load which is then used as the entry. Can be used in conjunction with 'preset: link' or a custom template to show information of the referenced object

take

a number to limit how many referenced LDAP objects should be loaded by resolve

Migration notes

The configuration options: detailAttributes and sapAttributes are now obsolete. Please use the new panel configuration instead.

← DALTranslations →