Customizing XML Structure - model.xml
This file describes contents of XML structure definition file model.xml
DITA Storm editor is preconfigured to work with DITA XML, but also capable of operating with user-defined XML structure. It could be customized DITA XML or something completely unrelated as XML for invoice handling (see example here).
At this moment DITA Storm does not support direct use of DTD or Schema file to control structure of edited XML document. This has to do with performance and size restrictions of browser-based applications. Instead DITA Storm operates by using XML configuration file similar in nature to Schema but besides description of the XML structure it contains additional information such as user-defined actions and presentation details.
For step-by-step element creation/customizaiton instructions see this section.
For your reference file DITAStorm/config/model.dtd contains DTD defintion of the structure of model.xml.
model
Root element for entire DITA Storm XML structure definition.
<!ELEMENT model (element*,editor*)>
<model>
<element.../>
...
<editor.../>
...
</model>
element
Describes a single element in the set of all elements supported by the editor.
<!ELEMENT element (group*,action*,default?)>
Type
Attribute Name
Description
string
name
Name of the element. (E.g. 'section' or 'p')
string
title
Full name of the element (E.g.'Section' or 'Topic')
true | false
addToNewButton
Adds element to 'New' button in the editor allowing it to be root element of the edited content. (E.g. for Topic)
string
attributeEditor
Name of the attribute editor associated with this element. See 'editor' element. (E.g. 'topic' or 'univ-atts').
true | false
confirmDelete
Enables confirmation on deleting this element. Used primarily on high-level elements such as Section or Topic.
string
doctypePublicId
Will be used to generate public ID for the element if it gets exported on the top level. (E.g. '-//OASIS//DTD DITA Topic//EN' for Topic).
string
doctypeFile
Used to generate path to the file in DOCTYPE section of the output XML document. This element should only contain file name without the path. (E.g. 'topic.dtd' for DITA Topic).
true | false
toolbarOnly
Indication to only show element on the DITA Storm toolbar (E.g. for Bold or Italic).
string
toolbarHTML
HTML snippet to be used on the toolbar to render the element. Element will not be added to the toolbar if this attribute is not defined. (E.g. 'B' for bold).
true | false
applyToSelection
Indicates whenever to allow element to be 'applied' to the selection. (E.g. set to true for Bold or Note).
character
ctrlShortcut
If defined sepcifies keyboard key which can be used with Control (Ctrl) key to insert element into the content. (E.g. by default set to 'b' on Bold and to 'i' on Italic element).
true | false
enableUnwrap
Enables 'unwrap' functionality when element can be replaced by its content. (E.g. by default enabled for Note, Paragraph and Bold).
true | false
inline
A hint to the editor on how to better format output XML. Inline elements just flow with the text others (block) elements always represent rectangle. (E.g. inline elements are Bold and Quote, block elements are Note and Long Quote).
true | false
showPropsOnInsert
Makes editor to show property dialog when element just gets inserted (E.g. for XRef and Image DITA Elements).
true | false
genericRenderer
Makes editor to use 'generic' element renerer similar to the one in Outline mode. Setting this attribute to 'true' disables XSL styles defined for this element.
string
helpUrl
Location (URL) of the help page for this XML element.
true | false
hidden
Removes element from Insert menues of the editor but does not prohibit from actually creating or handling an element from XML source or original XML document.
string
lock
Attribute defining editor-wide lock (or readonly) behavior for all elements of this type. See this section for more information and available values.
<element name='topic'
title='Topic'
addToNewButton='true'
attributeEditor='topic'
doctypePublicId='-//OASIS//DTD DITA Topic//EN'
doctypeFile='topic.dtd'
confirmDelete='true'>
<group allows='title' card='1'/>
<group allows='shortdesc'/>
<group allows='prolog'/>
<group allows='body'/>
<group allows='related-links'/>
<group allows='topic,task,concept,reference' card='0..n'/>
<default><![CDATA[<topic><title/><shortdesc/><body><p/></body></topic>]]></default>
</element>
group
Represents group of childs of enclosing element. Group elements are ordered and can not contain repetitive elements.
<!ELEMENT group EMPTY>
Type
Attribute Name
Description
string
allows
A comma-separated list of child elements allowed by this element. The order of the elements is not significant. Order of the groups is. One of the elements could be "#text" which indicates that element could cnotain text. (E.g. for Title: '#text,b,u,i,tt,sup,sub...')
0..1 | 0..n | 1 | 1..n
card
Cardinality of the elements in the group. 0..1 - group can contain no or one of the elements defiend in 'allows' atttribute. 1 - group should contain only one element from the elements in the 'allows' attribute.
string
emptyText
Text which will be displayed if element contains no childs. For example 'empty title' when contents of Title element is empty.
true | false
preserveTextFormatting
Indicates that text formatting needs to be preserved. (E.g. in 'pre' and 'code' DITA elements).
Lets take for example following DTD definition of the Topic and see how it gets translated to model.xml
<!ELEMENT topic (title,body?,(topic|reference|concept|task)*)>
here is the equivalent defined in model.xml:
<element name='topic' ...>
<group allows='title' card='1'/>
<group allows='body' card='0..1'/>
<group allows='topic,reference,concept,task' card='0..n'/>
</element>
default
Defines fragment of XML which will be used to populate newly created element. For example for convenience UL should be created with inner LI.
<!ELEMENT default (#PCDATA)>
<element ...>
...
<default><![CDATA[<topic><title/><shortdesc/><body><p/></body></topic>]]></default>
</element>
editor
Describes element attributes and provides editor necessary information to organize editing process. Editor can reuse fields defined in other editor by using <fields.../> element.
<!ELEMENT editor (fields|field)*>
Type
Attribute Name
Description
string
name
Name of the attribute editor.
<editor name="created">
<field attribute="date" title="Creation Date" type="date"/>
...
</editor>
fields
Imports fields defined in a different editor element with specified name. This can be useful to organize commonly used attributes in the groups for later reuse.
<!ELEMENT fields EMPTY>
Type
Attribute Name
Description
string
name
Name of the attribute editor to be included at this position.
<editor name="xref">
<field attribute="href" title="Hyperlink URL" type="conref"/>
...
<fields name="univ-atts"/>
</editor>
field
Defines a single attribute editing control. If field is of type 'choice' then 'option' child elements are available to define list of possible attribute values.
<!ELEMENT field (option*)>
Type
Attribute Name
Description
string
attribute
Name of the attribute. (E.g: 'href')
string
title
Title of the attribute (E.g. 'Navigation Title' for 'navtitle' attribute).
'string' | conref | choice | date | separator
type
Type of the attribute
number
size
size of the attribute editing field (applicable for 'string' type)
<editor...>
<field attribute="href" title="Image URL" type="conref"/>
<field attribute="alt" title="Alt Text" type="string"/>
...
</editor>
option
Describes one of the possible values of attributes/fields defined with type 'choice'.
<!ELEMENT option EMPTY>
Type
Attribute Name
Description
string
title
Title of the dropdown value.
string
attribute
Actual attribute stored in the field.
<field attribute="align" title="Alignment" type="choice">
<option title="" value=""/>
<option title="Left" value="left"/>
<option title="Right" value="right"/>
<option title="Center" value="center"/>
</field>