Documentation Center

Collective Spaces - BehaviorConfig.xml

The Collective Spaces user interfaces ship with default rendering and menu behavior for the DITA XML elements, defined in the DITA OASIS and SDL DTDs and schemas. You can customize Collective Spaces by editing the configuration file BehaviorConfig.xml, which is applied on top of the default behavior. In BehaviorConfig.xml, you define how DITA XML elements should be rendered for an XML document, which contextual menu items to show and which menu items to show in the Custom top menu tab.

About BehaviorConfig.xml

You can find BehaviorConfig.xml on the file system of the Content Manager server in the following folder:

Web\InfoShareCS\custom\

This configuration file only affects the Collective Spaces user interfaces.

Out of the box, it only contains a root element and a reference to its schema file, BehaviorConfig.xsd, which you can use to validate the file as you edit it. Never change BehaviorConfig.xsd itself.

Configuration types

BehaviorConfig.xml can contain the following types of configuration:
Rendering configuration
The rendering configuration can:
  • change the out-of-the-box rendering of existing DITA XML elements
  • add rendering for specialized DITA XML elements specified in a custom DITA DTD or schema
If you want to have different behavior for the same XML element depending on the schema being used, you can limit parts of the configuration to a certain schema or schemas.
Context menu configuration
The context menu configuration specifies which context menu items to show when you are positioned in the configured DITA XML element.
Top menu configuration
The top menu configuration specifies which additional custom menu items to show in top menu bar. You cannot change any of the existing top menu items. You can either:
  • Build your own additional custom menu structure, by using a menuconfiguration element.
  • Let the system generate an extra Custom top menu tab, which will show all the menuitem elements alphabetically
If a user is at a certain insertion point, and if selecting a menu item at that insertion point would result in invalid XML, the menu item will automatically be disabled.
Sidebar configuration
The sidebar configuration specifies an additional sidebar to show in the menu on the right. You cannot change any of the existing sidebars. You can:
  • Build your own additional sidebar by using a sidebarconfiguration element.
  • Specify the position of your custom sidebar on the sidebar menu panel.
Conref configuration
The conref configuration specifies which specialized XML elements a user is able to conref. Note that the out-of-the-box elements can always be conrefed, but that an element in an XML document can only be conrefed if it has its id attribute set. You can:
  • Define the list of elements the user can conref by using a conrefconfiguration element.

Overview of the XML elements in BehaviorConfig.xml

behaviorconfig
This is the root element of the file.
behaviorscopegroup
Use this element to group together behaviorgroup elements. You can then use a scopetoschemas child element to ensure that the behaviors defined in those behaviorgroup child elements are only applied if the schema of the loaded XML document is one of the schemas listed under scopetoschemas.
behaviorscopegroup also has an optional name attribute in case you want to give the group a logical name.
scopetoschemas (optional)
The list of schemas to which the behaviors defined in this behaviorscopegroup should be restricted. If you omit this element, the behaviors are applied to all schemas, so for every opened XML document.
schema
This element specifies, in its location attribute, the file location of a schema to which the behaviors defined in this behaviorscopegroup are applied. Set the value to the file location of the schema relative to the DocTypes\ folder; that is, the value should match one of the schema location attributes configured in the SchemaLocationConfig.xml file.
behaviorgroup
This element groups one or more rendering behavior elements, contextual menu items or (top) menu items together.
behaviorgroup has an optional name attribute in case you want to give the group a logical name.
Rendering behavior elements
Use the following elements to specify how to render a DITA XML element that matches the XPath specified in its xpath attribute:
  • mapsheet
  • structureviewitem
  • sheet
  • sheetbody
  • title
  • block
  • inline
  • highlighting
  • list
  • image
  • blockgenericicon
  • inlinegenericicon
  • definitiontable
  • readonlynarrowtable
contextualmenuitems
Use this element to specify which contextual menu items to show when the user is positioned in an element matching the xpath attribute.
menuitems
Use this element to specify which menu items to show in the top menu. When you set an id attribute value for a menuitem element, the same value can be set in the ref attribute of the menuitemref element inside the menuconfiguration element to reference the menu item and build a custom menu structure.
menuconfiguration (optional)
Use this element to specify which menu items to show in the top menu. Every extramenu child element in the menuconfiguration is rendered as an extra tab in the top menu bar with the given label. When you set an (optional) xpath attribute value on the extramenu element, the extra tab is only shown when you are positioned in a document that matches the xpath. The extramenu element groups one or more of the menu structure elements.
Menu structure elements
Use the following elements in the menuconfiguration extramenu elements to specify how the custom menus will look:
  • The menuitemref ref attribute value should match with the value of an id attribute of a menuitem element defined in one of the behavior elements. It renders as a menu item with the label of the referenced menuitem element.
  • The menuseparator renders as a horizontal or vertical separator between menu items.
  • The menuexpandgroup groups one or more of the menu structure elements. It renders as a drop-down or expand menu with the given label and its child elements as sub-menu items.
Sidebar attributes
Use the following attributes for the sidebarconfigurationextrasidebar to specify the looks of your custom sidebar:
  • The url attribute to specify the application URL. This URL will be used to render the custom application in the iFrame. This is a mandatory attribute.
  • The position attribute to specify the position of the custom sidebar on the sidebar menu panel. Value 1 means first from the top.
  • The icon attribute to specify the sidebar icon that will be visible next to the label. Use one of the FontAwesome icons.
  • The size attribute to specify the width of the sidebar while the tab is opened. You can choose from s, m(default), or l which translate to small, medium, and large.
In the out-of-the-box BehaviorConfig.xml we provide an example that is commented out. If you uncomment this example, you should see an extra Custom Sidebar in Draft Space that uses a Tridion Docs API endpoint to show which JSON content gets sent from Draft Space.
Conref configuration
Use the following elements in the conrefconfiguration to specify the list of elements the user is able to conref:
  • The element has 2 attributes:
    • The required name attribute contains the name of the XML element in the XML document that the user can conref.
    • The optional baseelement attribute is rarely needed. It's value should only be set to topic when the configured XML element is specialized from the DITA topic element or any of its specializations.