Documentation Center

Rendering behavior elements in BehaviorConfig.xml

The rendering behavior elements specify how specific DITA XML elements should be rendered.

Most rendering behavior elements have the following child elements:
  • a required label child element
  • an optional description child element

See Examples & How to for examples on how the different behavior elements get rendered.

All rendering behavior elements have the following attributes:
  • a required xpath attribute
  • an optional priority attribute

Use the priority attribute if you want to overwrite the out-of-the-box configuration for some elements in some specific exceptional cases. By default, the configuration in this file overwrites any out-of-the-box configuration that has the same xpath attribute value. However, in some cases, you will want your configuration to overwrite a more specific xpath. For example, imagine that the configured custom XPath is xpath="self::p" and the out-of-the-box XPath is xpath="self::p[parent::li]". Then the extra filter criteria of the out-of-the-box XPath makes that XPath more specific. In such a scenario, set a priority attribute value higher than 3 to overwrite the more specific out-of-the-box rule, because the higher the priority, the more importance it will get. Conversely, set priority to a value lower than zero if you want your configuration to be applied only if there is no other configuration defined for the XPath expression.

By default, your custom configuration is merged with the out-of-the-box configuration if the same XPath is used in both configurations. For example, if the out-of-the-box XPath xpath="self::b" is configured to show as bold and your custom configuration uses <highlighting xpath="self::b" italic="yes">, then the b element will render as bold+italic in Collective Spaces. You can override this default merging behavior, and instead suppress the out-of-the-box configuration entirely, by specifying the optional clearsamexpathbehavior attribute and setting it to the value yes. In our example, this would render the b element as italic only.

The rendering behavior elements are:
mapsheet
Use for elements you want to render as a sheet of paper. Typically, map or specializations of map are rendered as mapsheet.
Here is an example:
<mapsheet xpath="self::bookmap">
  <label>bookmap</label>
</mapsheet>
structureviewitem
Use for elements you want to show in the hierarchical Outline view. Only use for specializations of topicref that don't show up correctly with the out-of-the-box configuration.
This element has a required icon attribute, set to either folder-open-o or file-text-o.
It might also be necessary to add a priority attribute, set to a value higher than 2.
Here is an example:
<structureviewitem xpath="self::chapter" icon="folder-open-o" priority="3"/>
sheet
Use for elements that you want to render as a sheet of paper. Typically, topic or specializations of topic are rendered as sheet.
Here is an example:
<sheet xpath="self::concept">
  <label>concept</label>
</sheet>
sheetbody
Use for elements that you want to render as a structure without a label. Typically, body or specializations of body are rendered as sheetbody.
Here is an example:
<sheetbody xpath="self::conbody">
  <label>concept body</label>
</sheetbody>
title
Use for elements that represent titles on all levels.
This element requires a fontvariation attribute, set to one of document-title, section-title or figure-title.
Use the optional placeholdertext child element if you want to define a placeholder text to display when the element content is empty, for example, Enter title.
Here is an example:
<title xpath="self::title[parent::concept]" fontvariation="document-title">
  <label>title</label>
  <placeholdertext>Type the title here</placeholdertext>
</title>
<title xpath="self::title[parent::section]" fontvariation="section-title">
  <label>title</label>
  <placeholdertext>Type the title here</placeholdertext>
</title>
block
Blocks can only contain inline content. As such, they are an end point of the vertical flow of a document.
There are different kinds of blocks, depending on their type attribute. Choose the correct value for the attribute based on:
  • whether or not you want to be able to split or create the same element by pressing Enter.
  • whether you want the element itself to be able to contain text, or only child elements.
This element requires a type attribute. The value is one of the following:
  • canbesplit-and-candirectlycontaintext
  • canbesplit-and-cannotdirectlycontaintext
  • cannotbesplit-and-candirectlycontaintext
  • cannotbesplit-and-cannotdirectlycontaintext
Use the optional placeholdertext child element if you want to define a placeholder text to display when the element content is empty, for example, Enter text.
Here is an example:
<block xpath="self::p[parent::reqcond]" type="canbesplit-and-candirectlycontaintext">
  <label>Paragraph</label>
  <placeholdertext>type the required condition to perform this task</placeholdertext>
</block>
inline
Use for elements that need to be shown inline and that have a semantic meaning. Typically used for specializations of the ph element.
This element has the following optional attributes:
Attribute nameValues
boldyes or no
italicyes or no
underlineyes or no
overlineyes or no
linethroughyes or no
subscriptyes or no
superscriptyes or no
startdelimiterA character or string to prepend to the beginning of the content of the element
enddelimiterA character or string to append to the end of the content of the element
preformattedtextyes or no
backgroundcolorOne of the named color values (see below).
Here is an example:
<inline xpath="self::tm" enddelimiter="™" backgroundcolor="green">
  <label>Trademark</label>
</inline>
<inline xpath="self::tm[@tmtype='reg']" enddelimiter="®">
  <label>Registered trademark</label>
</inline>
highlighting
Use for elements that apply typographic formatting to content without suggesting any meaning. Typically only used for emphasis.
This element has the following optional attributes:
Attribute nameValues
boldyes or no
italicyes or no
underlineyes or no
overlineyes or no
linethroughyes or no
subscriptyes or no
superscriptyes or no
preformattedtextyes or no
backgroundcolorOne of the named color values (see below).
Here is an example:
<highlighting xpath="self::b" bold="yes">
  <label>Bold</label>
</highlighting>
list
Use for elements that describe an unordered or ordered list of items.
This element requires an items child element that describes the list items.
The list element requires an items child element, which describes the list items. items has the following attributes:
  • a required xpath attribute
  • a required type attribute, with possible values number, bullet or none
  • a required elementname attribute
  • an optional paragraphelementname attribute that you can set if you always want to have a specific element inside the list items (always a p element for example). Currently, the only element name that is supported in paragraphelementname is the p element.
Both the list element and items child element can have a contextualmenuitems child element.
Here is an example:
<list xpath="self::ol">
  <label>Unordered list</label>
  <items xpath="self::li" type="number" 
     elementname="li" paragraphelementname="p">
    <label>Item</label>
  </items>
</list>
image
Use for elements specialized from image.
Here is an example:
<image xpath="self::image">
  <label>Image</label>
  <description>Image</description>
</image>
blockgenericicon
Use to show a block icon placeholder with the name of the element. This is useful when you want to give the user an indication that something is there without showing the entire content, so that the user does not accidentally delete it by deleting one of the enclosing elements.
blockgenericicon has two optional attributes:
  • icon, set to the name of one of the icons defined in Font Awesome 4.7 (see https://fontawesome.com/v4.7.0/icons/). If omitted, this defaults to the value cog.
  • tooltipquery, set to an XPath expression that defines what to show when you hover over the icon in Fonto. If omitted, this defaults to the value ./string().
Here is an example:
<blockgenericicon xpath="self::data" icon="address-card-o">
  <label>Data</label>
</blockgenericicon>
inlinegenericicon
Use to show an inline icon placeholder with the name of the element. This is useful when you want to give the user an indication that something is there without showing the entire content, so that the user does not accidentally delete it by deleting one of the enclosing elements.
inlinegenericicon has two optional attributes:
  • icon, set to the name of one of the icons defined in Font Awesome 4.7 (see https://fontawesome.com/v4.7.0/icons/). If omitted, this defaults to the value cog.
  • tooltipquery, set to an XPath expression that defines what to show when you hover over the icon in Fonto. If omitted, this defaults to the value ./string().
Here is an example:
<inlinegenericicon xpath="self::data-about" icon="info">
  <label>Data About</label>
</inlinegenericicon>
definitiontable
Shows a table with two columns: one for the term and one for its definition.
definitiontable has the following optional attributes:
Attribute nameValues
bordersyes or no
headerbackgroundcolorOne of the named color values (see below).
rowbackgroundcolorOne of the named color values (see below).
definitiontable has the following child elements:
Child elementRequired or optional?Description
headerOptionalHas required termheader and definitionsheader child elements, which in turn each have a required label element and an optional description or placeholder element.
rowsRequired

Has required term and definitions child elements, which in turn have an optional placeholdertext child element and an optional contextualmenuitems child element.

placeholdertextOptionalUse if you want to define a placeholder text to display when the element content is empty, for example, Enter table.
contextualmenuitemsOptionalSpecified contextual menu items.
Here is an example:
<definitiontable xpath="self::dl" borders="yes" 
    headerbackgroundcolor="dark-grey" 
    rowbackgroundcolor="white">
  <label>Definition Table</label>
  <header elementname="dlhead">
    <label>Header</label>
    <termheader elementname="dthd">
      <label>Term</label>
    </termheader>
    <definitionsheader elementname="ddhd">
      <label>Definitions</label>
    </definitionsheader>
  </header>
  <rows elementname="dlentry">
    <label>Row</label>
    <term elementname="dt">
      <label>Term</label>
      <placeholdertext>Type the term 
         here</placeholdertext>
    </term>
    <definitions elementname="dd">
      <label>Definitions</label>
      <placeholdertext>Type the term 
         definitions here</placeholdertext>
    </definitions>
  </rows>
</definitiontable>
readonlynarrowtable
Used for a very basic table of which the structure and element content cannot be changed.
readonlynarrowtable has the following optional attributes:
Attribute nameValues
bordersyes or no
headerbackgroundcolorOne of the named color values (see below).
rowbackgroundcolorOne of the named color values (see below).
readonlynarrowtable has the following child elements:
Child elementRequired or optional?Description
headerOptionalHas a required label, (potentially) multiple cell child elements, and a required elementname attribute. The cell element has a required label element, an optional description or placeholder element, a required elementname, as well as an optional maxoccurs and showifempty attributes. The maxoccurs can be used in case a certain cell element occurs more than once in a row, and the showifempty, if set to yes, can be used to show all of the cells that are empty, including the ones specified in the maxoccurs.
rowsRequiredHas a required label, (potentially) multiple cell child elements, and a required elementname attribute, and an optional showlabelincell attribute. The showlabelincell attribute can be used to show the label of the cell before the cell content inside the table. The cell element has a required label element, an optional description or placeholder element, a required elementname, an optional maxoccurs and showifempty attributes. The maxoccurs can be used in case a certain cell element occurs more than once in a row, and the showifempty, if set to yes, can be used to show all of the cells that are empty, including the ones specified in the maxoccurs.
Here is an example:
<readonlynarrowtable xpath="self::specialtable" borders="yes" headerbackgroundcolor="grey" rowbackgroundcolor="white">
    <label>Special Table</label>
    <header elementname="header">
        <label>Header</label>
        <cell elementname="col1">
            <label>Column1</label>
            <placeholdertext>Please fill in a label for this column</placeholdertext>
        </cell>
        <cell elementname="col2">
            <label>Column2</label>
            <placeholdertext>Please fill in a label for this column</placeholdertext>
        </cell>
        <cell elementname="morecols" maxoccurs="3">
            <label>Extra Columns</label>
            <placeholdertext>Please fill in a label for this column</placeholdertext>
        </cell>
    </header>    
    <rows elementname="row" showlabelincell="yes">
        <label>Row</label>
        <cell elementname="col1">
            <label>Column1</label>
            <placeholdertext>Please fill in a value for this column</placeholdertext>
        </cell>
        <cell elementname="col2">
            <label>Column2</label>
            <placeholdertext>Please fill in a value for this column</placeholdertext>
        </cell>
        <cell elementname="morecols" maxoccurs="3">
            <label>Extra Columns</label>
            <placeholdertext>Please fill in a value for this column</placeholdertext>
        </cell>
    </rows>
</readonlynarrowtable>
The named color values are:
  • red
  • pink
  • purple
  • deep-purple
  • indigo
  • blue
  • light-blue
  • cyan
  • teal
  • green
  • light-green
  • lime
  • yellow
  • amber
  • orange
  • deep-orange
  • brown
  • grey
  • blue-grey
  • black
  • white