Bookmark favorites

General principles #

By default, when displaying a new Dock element, ActiveUI shows the different widgets that have been registered in tiles, classified by category.

The tiles displayed can be modified in three ways:

• Adding new tiles which are bookmark favorites
• Adding new tiles, which changes the default configuration of widgets
• Removing tiles that a user does not want to see, or should not have access to

Adding a new bookmark favorite tile #

The bookmark favorites feature enables a user to have additional tiles by default in the dock, providing quick access to the bookmarks the user needs the most. Clicking a tile linked to a bookmark favorite directly loads it in the current dock.

A bookmark favorite can be added from the UI: #

To do so, right-click on a bookmark favorite in the bookmarks tree, and select “Add to favorites”.

• Fill-out the category section, by either selecting an already existing category, or type a new category name.
• Fill-out the name you want to give to your favorite, and submit.

A bookmark favorite can also be added programmatically: #

The bookmark favorites feature is based on the Settings mechanism of the content server.

Therefore, a bookmark favorite defined in the:

• default preferences/permissions will be seen by all users (if not overridden at a more granular level),
• roles/ROLE_USER preferences/permissions will only be seen by the members of this ROLE_USER role
• user/USER_A preferences/permissions will only be seen by USER_A

To create a new bookmark favorite, simply add a new key, starting with the mandatory prefix bookmarks.favorites.*. A suffix is needed, but there is no constraints on it, except it must be unique, and not contain any more dots.

Regarding the value of the setting, the mandatory attributes are:

• A type attribute, corresponding to the plugin key of the widget (pivot-table, chart, etc)
• Either an id or value attribute

If an id attribute is specified, then the bookmark favorite will reference an existing bookmark, given by this id.

Here is an example of a bookmark favorite referencing a bookmark id:

{
  "allow": [
    /* array of patterns matching settings keys which value should be set to true */
  ],
  "deny": [
    /* array of patterns matching settings keys which value should be set to false */
  ],
  "map": {
    "bookmarks.favorites.pivot-table-18f": {
      "category": "data",
      "id": "18f",
      "name": "PnL per Desk",
      "type": "pivot-table"
    }
  }
}

If the value attribute is specified, then the bookmark favorite is defined as a new bookmark (though it will not appear in the bookmarks tree):

{
  "bookmarks.favorites.pivot-table-by-value": {
    "category": "data",
    "name": "PivotTable v2",
    "type": "pivot-table",
    "value": {
      "style": {},
      "showTitleBar": false,
      "containerKey": "pivot-table",
      "body": {
        "serverUrl": "",
        "mdx": "SELECT ...",
        "contextValues": {},
        "updateMode": "once",
        "configuration": {
        "...": "..."
      }
    }
  }
}

Adding new tiles which change the default configuration of widgets #

Note: this feature is targeting programmers and not end-users.

The bookmark favorites feature also allows users to change the default configuration of a widget.

It basically uses the same principle described in the previous section, but the key part is now, a bookmark can be described partially.

By partially, we mean that some attributes of a bookmark which are needed for ActiveUI to be able to render a widget, like the MDX or the server URL for a Pivot Table.

If some of these needed attributes are not present in the bookmark, then the user will be displayed the Server Chooser for this particular example.

This means that if you try to load a Pivot Table bookmark, which contains a valid configuration in its body, but without the MDX attribute, then it will behave just like the regular Pivot Table, but with your custom configuration.

To say it in other words, you can redefine at will your bookmark body field to change the configuration of your widgets.

Example 1: Add a modified Pivot Table tile from the UI #

In this example, we will be adding a new Pivot Table tile, but which will load a pivot table with the wizard hidden by default, and without line numbers.

• Open a regular pivot table
• Hide the wizard
• Go to state and change lineNumbers to false
• Click on the save as new bookmark icon
• Give it a relevant name

At this stage, the bookmark is fully defined. We are going to remove the mandatory attributes so that clicking the tile behaves exactly like the default Pivot Table, i.e. ask for the cube first:

• Remove the serverUrl and mdx attributes
• Submit to save
• Go to the bookmarks tree, right-click on your new bookmark, and add it to the favorites!

Eventually, if your goal is to completely override the default pivot table, you can right-click on the default pivot table, and select delete.

Final note: from the UI, the changes only apply to the current user. In order to propagate this to a bigger group of users, a developer can start easily with this method, then go to the content server, and move the created setting to the preferences file of a bigger group.

Example 2: Add a modified Pivot Table tile manually from the the Content Server #

First start off the example describing how to create a bookmark favorite by value (see Adding a new bookmark favorite tile)

In the bookmark value.body.configuration field, copy-paste the default pivot table configuration, that you can find here: Default Configurations

Change the min row size to 25: "minRowSize": 25.

Internationalization #

You can also use the titleCaptionPath and descriptionCaptionPath attributes to have your title and description internationalized correctly:

If you use these two caption paths, then the “name” attribute is no longer mandatory. Not defining a “name” attribute will generate a new random name for the widget every time it is created.

Here for example:

{
  ...
    "bookmarks.favorites.pivot-table-18f": {
      "category": "data",
      "descriptionCaptionPath": 'bookmarks.new.pivot-table.description'
      "id": "18f",
      "titleCaptionPath": 'bookmarks.new.pivot-table.title'
      "type": "pivot-table",
    }
  }
  ...
}

Removing tiles #

From the UI, a user can remove tiles he does not want to see, by right-clicking on them and selecting Hide default widget, or Delete favorite if the tile was added as a favorite by the user himself. Default widgets can be un-hidden by using the dock action Show all default widgets. However, deleting a user favorite is not a recoverable operation.

It is also possible to hide tiles that are regular widgets, like the Drillthrough or the PivotTable, by proceeding the same way.

In this case, a new setting key is written in the content server, with the following template: "bookmarks.favorites.container-key.hidden": true

A Content Server admin can delete this key, and the widget will show-up again in the user’s dock.

Let’s say that a bookmark favorite with key bookmarks.favorites.pivot-table-example was created in the default/preferences file (so everyone can see it), but you want to hide it from USER_A.

Then add the following setting "bookmarks.favorites.pivot-table-example.hidden": true in the USER_A/preferences file.