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
mapsheet,
sheet,
sheetbody and
block rendering behavior elements have an optional
defaulttextcontainer child element with a required
elementname attribute. This can be utilized for :
- Specified XML elements that cannot directly contain text, to indicate the direct XML child element that can contain text so that when a user starts typing in the first element, the child element is automatically created and the typed text is inserted in it.
- Specified XML elements that already contain text and you want the text that you type after pressing the enter key to go on a new line, so it will also be shown in the published output on a new line. It can be done by configuring the wrapping
elementname. Typically elementname used for this case is the <p>(paragraph) element, so that both text lines end up inside a <p> element.
Exception: the
block rendering behavior element with types
canbesplit-and-candirectlycontaintext and
canbesplit-and-cannotdirectlycontaintext will always split the current element, when the user types
enter. To insert a new line the user can try to type
shift+enter, and therefore
block has an optional
implicit attribute that can be set either to
block (the default) or to
line.
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.
-
Use the optional
defaulttextcontainer child element and required elementname attribute to specify the name of the XML child element that can be inserted when a user starts typing text in the element (if the element itself cannot contain text directly and the child element is allowed by the XML Schema).
-
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.
-
We use the optional
defaulttextcontainer here and configure the concept child element conbody as the concept element cannot directly contain text.
-
Here is an example:
<sheet xpath="self::concept">
<label>concept</label>
<defaulttextcontainer elementname="conbody" />
</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.
-
We use the optional
defaulttextcontainer here and configure the conbody child element p as the conbody element cannot directly contain text.
-
Here is an example:
<sheetbody xpath="self::conbody">
<label>concept body</label>
<defaulttextcontainer elementname="p" />
</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.
-
You can use the optional
defaulttextcontainer here, if needed.
-
Here is an example:
<block xpath="self::conbodydiv" type="cannotbesplit-and-cannotdirectlycontaintext">
<label>Section division</label>
<defaulttextcontainer elementname="section" />
<placeholdertext>type the content</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 name | Values |
|---|
bold | yes or no |
italic | yes or no |
underline | yes or no |
overline | yes or no |
linethrough | yes or no |
subscript | yes or no |
superscript | yes or no |
startdelimiter | A character or string to prepend to the beginning of the content of the element |
enddelimiter | A character or string to append to the end of the content of the element |
preformattedtext | yes or no |
backgroundcolor | One 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 name | Values |
|---|
bold | yes or no |
italic | yes or no |
underline | yes or no |
overline | yes or no |
linethrough | yes or no |
subscript | yes or no |
superscript | yes or no |
preformattedtext | yes or no |
backgroundcolor | One 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 . If the element name used in the xpath can appear under multiple parents, for example the "li" element can appear both underneath a "ol" or "ul" element, you should provide an extra filter, so xpath="self::li[parent::ol]".
- 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[parent::ol]" 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 name | Values |
|---|
borders | yes or no |
headerbackgroundcolor | One of the named color values (see below). |
rowbackgroundcolor | One of the named color values (see below). |
definitiontable has the following child elements:
| Child element | Required or optional? | Description |
|---|
header | Optional | Has required termheader and definitionsheader child elements, which in turn each have a required label element and an optional description or placeholder element. |
rows | Required | Has required term and definitions child elements, which in turn have an optional placeholdertext child element and an optional contextualmenuitems child element. |
placeholdertext | Optional | Use if you want to define a placeholder text to display when the element content is empty, for example, Enter table. |
contextualmenuitems | Optional | Specified 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 name | Values |
|---|
borders | yes or no |
headerbackgroundcolor | One of the named color values (see below). |
rowbackgroundcolor | One of the named color values (see below). |
readonlynarrowtable has the following child elements:
| Child element | Required or optional? | Description |
|---|
header | Optional | Has 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. |
rows | Required | Has 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