Collective Spaces - BehaviorConfig.xml - Examples & How To
Creating a custom configuration for Collective Spaces is not an easy task. We will show here how the different behavior elements are rendered, and we will give some pointers that can help you create this configuration.
Before doing any configuration in the BehaviorConfig.xml, first see how your content will show up using the out-of-the-box configuration which is always applied, if your custom DITA specialized XML Schema is compiled. You should only make changes to this file on a development or test environment, never on production. Preferably, use an XML editor to update this file as it will provide help on which elements you can use where, because the BehaviorConfig.xsd, which defines the structure of the XML, is referenced from the behaviorconfig element.
Rendering Behavior elements
To get a better understanding of the rendering behavior elements you can use in your configuration, the examples below show how every element is actually rendered.
| Element name | A .. element configured as .. | is rendered as .. |
|---|---|---|
mapsheet | A mapsheet element, which is typically used for map elements and their specializations, configured as | Note that the DITA |
sheet | A sheet element, which is typically used for topic elements and their specializations, configured as | Note that the |
sheetbody | A sheetbody element, which is typically used for body elements or their specializations, configured as | Note that a |
title | A title element, which is typically used for title elements on any level, configured as | Note that the text "Inside the box" is shown as a title, in a bigger font. |
block | A block element, which is typically used for paragraph-like elements, configured as
Choose the correct value for the type attribute based on:
In this example, we set the | Note that depending on the |
inline | An inline element, which is typically used for phrase elements (ph) or their specializations, configured as | Note that the sentence just continues around the |
highlighting | A highlighting element, which is typically used for inline highlighting elements, configured as | |
list | A list element, which is typically used for list elements and their items, configured as | |
image | An image element, which is typically used for image elements or their specializations, configured as | |
blockgenericicon | A blockgenericicon element, which is typically used to show a placeholder on its own line to give the user an indication that there is XML contents there without showing the entire contents, configured as | |
inlinegenericicon | A inlinegenericicon element, which is typically used to show an inline placeholder to give the user an indication that there is XML content there without showing the entire contents, configured as | Is rendered the same as the blockgenericicon, but can appear in line with the text. |
definitiontable | A definitiontable element, which is typically used for definitiontable elements or their specializations, configured as | |
structureviewitem | A structureviewitem element can be used to show specializations of topicref elements in the Outline view. A configuration like | Note that the DITA |
Tips on configuration order, priority and clearsamexpathbehavior in the BehaviorConfig.xml
priority attribute, and the order of the rules in the BehaviorConfig.xml configuration file. The following applies:
- The more specific the XPath expression value is, the more precedence it will take. For example a rule, having
xpath="self::p[parent::section][parent::body]"will take precedence over a rule havingxpath="self::p". - A configuration rule in theBehaviorConfig.xml will override the out-of-the-box rule that has the same
xpath. However, an out-of-the-box rule having a more specificxpathstill takes precedence over a configured rule with a less specific XPath. - A configuration rule that has a higher
priorityattribute value will take precedence over a lowerpriorityrule, even when its XPath is less specific. Use apriorityvalue higher than 2 to make sure that your configuration takes precedence over every out-of-the-box defined behavior having a more specific XPath expression. You can also usepriorityvalues lower than 0, to let the out-of-the-box configuration always take precedence over your rules. Note that thepriorityattribute is optional, so first look at the result without having this attribute set. - If there are multiple rules in the configuration file having the same XPath and without having a
priorityattribute, the last rule in the file takes precedence. - If multiple rules apply, by default the behavior is merged: For example if the out-of-the-box specifies that the element should be rendered bold, and your configured rule says it should be rendered as italic (without specifying anything for the bold property), the element would be rendered as bold+italic. To avoid merging, you can set the
clearsamexpathbehaviortoyeson the rule taking precedence, and then only the properties explicitly set on that rule will be taken into account.
You can use the location attribute in the schema element, if the scopetoschemas child element of the behaviorscopegroup element is set, to make sure certain configuration rules are only applied when a user opens an XML document that adheres to a certain DTD or XML Schema. Make sure to put the common rules on top of the configuration file and the schema-dependent ones at the bottom, as the last rule in the file "wins" (if xpath and priority are the same).
Building up a configuration
api2ref DTD, that contains a copy of the SDL apiref DTD that is supplied out of the box. In this api2ref DTD, all elements having api in their name have been renamed to api2 (for example: api2ref, api2function, api2description) . When you define a menuitem, make sure to put elements that need to be inserted in the inserttemplate on one line, to avoid extra whitespace characters.
| Configuration | Description |
|---|---|
| No compiled schema yet | When you didn't configure your schema on the server, or did not compile it using the IshDeploy Set-ISHFontoSchemaExperience command, the apiref2 XML document is rendered as follows: |
| No configuration yet | When you don't have any configuration in BehaviorConfig.xml for api2ref yet, the following default configuration is used: The apiref2 XML document is rendered as: Note that the XML document is not rendered in the sheet view at all. |
| First configuration with basic rendering |
When using the following configuration:
the api2ref XML document is rendered as: Note that the |
| Configuration with somewhat improved rendering |
When using the following configuration:
the api2ref XML document is rendered as: Note that more elements are already shown properly, although we did not configure them. Since we have the regular |
| Configuration with improved rendering and some menu's |
When using the following configuration:
the api2ref XML document is rendered as: Note that the In the configuration, we use the |