= Cinnamon client configuration
== Abstract
This documentation applies to Cinnamon Desktop Client plus (CDCplus) configuration which is maintained on the Cinnamon Server and deployed to the client.

== How CDCplus configuration works
=== Concept
Earlier Cinnamon Desktop Client versions maintained client configuration in a file named {{{CinnamonDesktopClient.custom.config.xml}}} that was stored locally with the client.

Since the introduction of CDCplus in 2018, the configuration is no longer maintained on the client, but on the server. All configuration is stored in the metadata of an object named {{{_client_configuration}}} inside the Cinnamon path {{{/system/config/client_configuration}}}.

This object can contain multiple sets of configuration that will be deployed depending on the user's group membership or superuser privileges. It is possible to assign individual configuration to a single user. In any case, there must be a default that is assigned to all users not matching any of the specific configuration sets.

CDCplus itself contains an //emergency configuration// that is loaded whenever no server-based configuration can be deployed for whatever reason. This can happen when a legacy system is accessed with CDCplus for the first time or when a superuser has somehow misconfigured the server-based configuration. The emergency configuration allows a superuser to fix the configuration and restore a working state for all users.

=== Assigning configuration to users
The metadata inside the {{{_client_configuration}}} can be accessed with the //Edit metadata// tab in CDCplus. The exact permissions on this object are subject to ACL configuration and assignment. Generally, only superusers or selected users who are responsible for configuration changes should be allowed to modify the configuration. To use the client, only read access to the object is required.

The metadata has the following, general structure:

{{{
<meta>
  <metaset type="client_configuration" id="52146">
    <cinnamon_client>
      <match>
        <default />
      </match>
      ... configuration ...
    </cinnamon_client>
    <cinnamon_client>
      <match>
        <superuser />
      </match>
      ... configuration ...
    </cinnamon_client>
    <cinnamon_client>
      <match>
        <group sysname="test" />
      </match>
      ... configuration ...
    </cinnamon_client>
    ... further group based matches ...
    <cinnamon_client>
      <match>
        <user name="john.doe" />
      </match>
      ... configuration ...
    </cinnamon_client>
    ... further user based matches ...
}}}

The following rules apply:

* There **must** be **one** //default// match.
* There **may** be **one** //superuser// match.
* There **may** be any number of //group// matches.
* There **may** be any number of //user// matches.

Matches are applied in the following order:

* If no configuration object can be retrieved, or if the configuration object is invalid, emergency configuration is returned.
* Next, user matches are tried.
* Next, the superuser match is tried.
* Next, group matches are tried.
* If no match was found, default is tried.
* If no default is found, emergency config is returned.

== Structure of the cinnamon_client element
=== Root structure
The {{{cinnamon_client}}} element has the following structure:

{{{
<cinnamon_client>
  <match>
    ... match definition ...
  </match>
  <global_settings>
    ... some basic client settings ...
  </global_settings>
  <classes>
    ... all libraries and classes that are used 
    inside the client, and their configuration ...
  </classes>
  <menu>
    ... context menu structure, referencing classes 
    that were defined inside the classes element ...
  </menu>
</cinnamon_client>
}}}

=== Structure of the global_settings element
The {{{global_settings}}} element has the following structure:

{{{
<global_settings>
  <culture_name>en-US</culture_name>
  <log value="false" />
  <branching allow="false" />
</global_settings>
}}}

* {{{culture_name}}} defines the client satellite libraries to load. The content of the element must be one of the valid satellite library language codes. The default is {{{en-US}}} (if no {{{culture_name}}} element is provided). Currently, apart from English, only German ({{{de-DE}}}) is fully supported. There is limited language support in French and Dutch, which can be completed, or other languages can be added, if needed. If no {{{culture_name}}} element is present, the user's language setting configured in the user account is used.  

* {{{log}}} may have the values {{{true}}} or {{{false}}} in the {{{value}}} element. {{{true}}} causes a log to be written into the temp folder, named {{{Praties_<timestamp>.log}}}

* {{{branching}}} may have the values {{{true}}} or {{{false}}} in the {{{allow}}} element. {{{false}}} disables operations that will cause a branch on client side.

 > **NOTE:** This does not disable branching on server level. Also, branching can be enabled or disabled, depending on the configuration deployed to the client, and thus by user role.  

=== Structure of the classes element
The {{{classes}}} element has the following structure:

{{{
<classes>
  <default_window assembly="CinnamonEnterpriseClient" type="EnterpriseClientMainWindow">
    <path>/</path>
  </default_window>
  <content_awareness>
    <content id="dita">
      <implementation assembly="ContentAwareness" type="XmlContent" />
      <format_filter>dita</format_filter>
      <format_filter>ditamap</format_filter>
      <custom>
        <children>
          <xPath>//@href</xPath>
          <xPath>//@conref</xPath>
        </children>
      </custom>
    </content>
  </content_awareness>
  <session_extensions>
    <session_extension key="icon_service" assembly="CinnamonEnterpriseClient" type="DefaultIconService" />
    <session_extension key="cec.basichookcontainer" assembly="CinnamonEnterpriseClient" type="BasicHookContainer" />
  </session_extensions>
  <session_window assembly="CinnamonEnterpriseClient" type="EnterpriseClientMainWindow">
    ... session Window configuration ...
  </session_window>  
  <tab_controls>
    ... tab controls configuration ...
  </tab_controls>
  <functions>
    ... context functions configuration ...
  </functions>
</classes>
}}}

==== The default_window element
The {{{default_window}}} element allows the definition of one window to be opened opened whenever a session is created. Different user groups can have different default windows.

> **NOTE:** Future CDCplus versions will allow to define multiple windows. Since opening a window requires several calls to Cinnamon to retrieve the data to display, and thus takes a few seconds, not too many windows should be configured.

The {{{path}}} element's content defines the Cinnamon path to the folder to be shown. Example: {{{/Documentation}}}.

==== The content_awareness element
The {{{content_awareness}}} element contains configuration of content awareness modules. Content awareness modules are classes that can handle certain data and can be assigned to one or more formats.

Only formats that can contain either references to other objects (like XML or SGML), or that are subject to client-based custom processing on inbound and outbound operations need a content awareness module. Most formats, like pictures and PDF, do not normally need explicit support.

> **NOTE:** The documentation for content awareness will follow. The existing configuration as shown in the example describes referencing in DITA and should not be changed, unless a future DITA release has a different data model, or unless custom behaviour should be achieved.

It is possible (and encouraged) to develop new content awareness modules that support other referencing file formats. For example, Microsoft Office adaptors that support image and hyperlink references are possible.

==== The session_extensions element
The {{{session_extensions}}} element contains the definitions of session extensions. A session extension is a class that's instantiated when a session is created. The instance is attached to the session and is available anywhere inside  the client.

Session extensions can be used to provide functionality that should be globally available to standard and custom functionality.

Two session extensions are defined by default:

* The default icon service which deploys icons inside object lists and elsewhere. Implementing a custom icon service allows displaying individual icons by any available parameters of an object, for example lifecycle state, content format or object type.
* A basic hook container provides methods that are called on the client before and after lifecycle change. Other hooks can be added. The basic hook container has empty methods. To implement custom functionality, a custom hook container must be programmed and linked in the configuration.

Other session extensions can be added as required.

==== The tab_controls element
The {{{tab_controls}}} element contains the definitions of all tab controls that are available in the upper and lower right portion of the CDCplus main window. In a typical client configuration, there are 20 or more tab controls defined.

Not all tab controls are shown on every selection, since many of the tab controls are bound to specific situations, object types, formats or other parameters. There are, for example, specific tab controls for creating search definitions or managing translation tasks.

As with functions, session extensions, content awareness modules and other entities, tab controls are bound into the client just by configuration. It is therefore possible to program your own tab controls and add them to the client.

A minimal {{{tab_control}}} element looks like this:
{{{
<tab_control assembly="Praties" type="PermissionFolderControl" display="list" />
}}}

The {{{assembly}}} and {{{type}}} attributes define from which program library the tab control must be loaded and what its name is. The {{{display}}} attribute determines whether the tab control will show:

* in the upper right area (value: {{{tree}}})
* in the lower right area (value: {{{list}}})
* in both areas (value: {{{all}}})

The {{{tab_control}}} element shown above binds the control exposing the permissions on a folder into the client. Whether the tab control is shown or not depends on the return value of a method inside the tab control. That means, the tab control decides itself by the rules the programmer provided, whether to show up or not. In this case, the rule is to show whenever a folder is selected, and to hide when the selection is an object.

The above example is a tab control that has no configurable parameters and therefore, the {{{tab_control}}} element has no configuration inside. Most tab controls are configurable. 

===== Configuration of tab controls
* [wiki:Public/Docs/CinnamonClientRelationsTabControl Relations tab control]
* [wiki:Public/Docs/CinnamonClientContentsTabControls Contents tab controls]


==== The functions element
The {{{functions}}} element contains the definitions of all context functions that are available for objects, folders, lists of objects and / or folders, and the session. 

Basically, the configuration works much like the configuration of the tab controls. The {{{functions}}} element contains a list of {{{function}}} elements, where each one configures a context function that's available in the program.

Functions can be triggered by the following:

* The context menu that must be configured in the menu section of the configuration.
* Key events, as configured in the tab controls.
* Buttons in a button bar at the top of the window.
* Drag & drop events, asc configured in the tab controls (drag & drop is not yet functional).

The following example shows two function declarations, one without and one with parameters:

{{{
<function assembly="Praties" type="CancelCheckoutObjectFunction" />
<function assembly="Praties" type="CheckinObjectFunction">
  <custom>
    <default_versioning_behaviour checked_out_file="write" other_file="write" />
  </custom>
</function>
}}}

=== Structure of the menu element
Declaring a function in the {{{functions}}} element does not, by itself, add the function to a menu, nor link it with any other type of control. These connections must be made separately.

The {{{menu}}} element describes all context menus available.

The Cinnamon client has four different context domains:

* single objects
* single folders
* the session
* lists of objects and / or folders

All four domains have independent menu definitions. Since some functions provide functionality for more than one domain, it is common to reference the same function in more than one menu.

A menu declaration looks like this:

{{{
<menu>
  <object_context_menu>
    <menu_item assembly="Praties" type="CheckoutObjectFunction" />
    <menu_item assembly="Praties" type="CheckinObjectFunction" />
    <menu_item assembly="Praties" type="CancelCheckoutObjectFunction" />
    <separator />
    <menu_item assembly="Praties" type="OpenObjectFunction" />
    <menu_item assembly="Praties" type="CopyNameToClipboardObjectFunction" />
    <menu_item assembly="CinnamonEnterpriseClient" type="CreateNewVersionFunction" />
    <menu_item assembly="Praties" type="AppendContentObjectFunction" />
    <separator />
    <menu_item assembly="Praties" type="ExportObjectFunction" />
    ...
  </object_context_menu>
  <folder_context_menu>
    <menu_item assembly="Praties" type="CreateObjectWithoutContentFolderFunction" />
    ...
  </folder_context_menu>
  <list_context_menu>
    <menu_item assembly="Praties" type="CancelCheckoutListFunction" />
    ...
  </list_context_menu>
  <session_context_menu>
    <menu_item assembly="Praties" type="NewFolderSessionFunction" />
  </session_context_menu>
</menu>
}}}

The four domains are defined in the {{{<domain>_context_menu}}} elements. Menu items are declared in the order they should have in the menu. It is possible to add separators as required.

> **NOTE:** The functions that are declared do not necessarily all appear in the menu on every selection. The functions have methods informing the client (based on the current selection) whether they should be displayed or not, and whether they should be active or inactive ("greyed out"). This behaviour is normally not subject to configuration, since functions are made for a specific purpose and context, and refuse to be used outside of their specification. For example, a "cancel checkout" function makes no sense on objects that are not checked out, and is therefore not active.