DITA Storm Reference

Developer provides a number of extension points that allow you to extend the editor’s functionality, providing a better user experience and deeper integration into a Content Management System/Application. Extensions are registered with a JavaScript call before the instance of the editor is rendered. You can perform this by calling:

ditaStorm.registerExtension(...)

method and providing the necessary parameters. Depending on the type of extension parameters, this could be different. See the descriptions of particular extension points for parameter details.

Facilitating Conref/Href Lookup

Extend Developer by defining custom actions that are executed when a user edits the href/conref attributes and clicks the related browse button.

This can be achived by registering ‘ditastorm.conref’ extension

A JavaScript method must be provided to call when the corresponding button is clicked. This method accepts one parameter - a reference to a property form control, in which the value is set as a result (HRef on the picture above). Sample code:

<SCRIPT>
  function onBrowse(control) {
    var hrefValue = ...; // lookup the value
    control.value = hrefValue; // assign value back to the form
  }
</SCRIPT>
...
<SCRIPT>
  ditaStorm.registerExtension('ditastorm.conref',onBrowse);
  ditaStorm.render(...);
</SCRIPT>

Please remember, as with all extensions, your function will be executed in the context of the Developer frame, not in the page context. To refer to external resources (such as when opening a popup window or loading data from a server), you need to either provide a URL related to the Developer location or use the utility method to automatically calculate an absolute URL:

ditaStorm.getAbsoluteUrl(<base_url>,<relative_url>)

For example:

ditaStorm.getAbsoluteUrl(window.location.href,'../../editMyConref.php');

Pre-Requisite

To create a custom XML element, Developer must be installed and working.

Steps

1. Create new entry

   New elements along with all existing DITA XML elements are defined in DITAStorm/config/model.xml file. As part of this procedure you are able to identify child elements along with a list of available attributes. For more information on model.xml see corresponding section.

2. Register with other elements

   Identify other elements containing the new element and add it to the list of allowed elements in <group allows=‘...’>

3. Specify how the new element will be rendered.

   You have two options now:

   1. First, you can rely on Developer to generate a default (outline-linke) representation of the new element. To exercise this option, use genericRenderer attribute of <element...>:
      
      

      <element name='my' ... genericRenderer='true'>..

   2. The Second option is to use the XSL rendering engine. To exercise this option, modify DITAStorm/config/simple.xsl. As an alternative, create your own XSL document and define rendering for your elements. For details about available XSL rendering options see corresponding section.

4. Compile your changes.

   To make changes to model.xml and XSL you need to compile them. Developer uses compilation to optimize the editor’s performance and download time.

Result

When all necessary steps are performed you will be able to insert the newly created element into XML, edit its attributes and store it along with the XML document.

With Developer’s XML customization options, entire new XML structures can be built.

Developer is preconfigured to work with DITA XML, but is also capable of operating with any user-defined XML structure. It can be configured for customized DITA XML or something completely unrelated, such as XML for invoice handling.

Currently, Developer does not support the direct use of a DTD or Schema file to control the structure of edited XML documents. This is related to the performance and size restrictions of browser-based applications. Instead, Developer uses an XML configuration file similar to a Schema, but it contains both the XML structure description and additional information, such as user-defined actions and presentation details.

For your reference file DITAStorm/config/model.dtd contains a DTD definition of the structure of model.xml.

Reference: model

Root element for the entire Developer XML structure definition.

Syntax

<!ELEMENT model (element*,editor*)>

Example

<model> <element.../> ... <editor.../> ... </model>

Reference: element

Describes a single element in the set of all elements supported by the editor.

Syntax

<!ELEMENT element (group*,action*,default?)>

Properties

Example

<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>

Reference: default

Defines a fragment of XML that will be used to populate a newly created element. For example, for convenience UL should be created with inner LI.

Syntax

<!ELEMENT default (#PCDATA)>

Example

<element ...>
  ...
  <default>
    <![CDATA[
      <topic>
        <title/>
        <shortdesc/>
        <body>
          <p/>
        </body>
      </topic>
    ]]>
  </default>
</element>

Reference: editor

Describes element attributes and provides the editor with the necessary information to organize the editing process. Developer can reuse fields defined in other editors by using <fields.../> element.

Syntax

<!ELEMENT editor (fields|field)*>

Properties

Example

<editor name="created">
  <field attribute="date" title="Creation Date" type="date"/>
  ...
</editor>

Reference: fields

Imports fields defined in a different editor element with a specified name. This can be useful to organize commonly used attributes in groups for later reuse.

Syntax

<!ELEMENT fields EMPTY>

Properties

Example

<editor name="xref">
  <field attribute="href" title="Hyperlink URL" type="conref"/>
  ...
  <fields name="univ-atts"/>
</editor>

Reference: field

Defines a single attribute editing control. If the field is of the type ‘choice’ then ‘option’ child elements are available to define a list of possible attribute values.

Syntax

<!ELEMENT field (option*)>

Properties

Example

<editor...>
  <field attribute="href" title="Image URL" type="conref"/>
  <field attribute="alt" title="Alt Text" type="string"/>
  ...
</editor>

Reference: option

Describes one of the possible values of the attributes/fields defined with type ‘choice’.

Syntax

<!ELEMENT option EMPTY>

Properties

Example

<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>

This section describes the actions necessary to disable the editing of certain XML elements and attributes within Developer.

Making Elements Read-Only

There are three scenarios when an XML editor may need to prevent users from modifying certain elements of XML:

• Prevent editing of a certain attribute
• Prevent an element from being removed from its parent
• Prevent editing of an element and all child nodes contained in it

All three scenarios could be enforced for a certain class of elements, (see lock attribute in model.xml) as well as for specific elements within the provided XML.

To enforce one of these rules on specific elements within XML, the developer uses the special _lock attribute. Its value will identify how the element should be handled. List of available values:

<section product="UV Scanner" _lock="attribute:product">
  ...
</section>

<section _lock="content">
  ...
</section>

<section _lock="inparent">
  ...
</section>

<section _lock="inparent,attribute:product">
  ...
</section>

CSS Styling for Read-Only Elements

To indicate that a certain element and all of its child nodes can not be edited, Developer uses CSS style called readonly. In the initial configuration the background is light gray and letters are dark gray and italic:

.readonly { background-color: #F5F5F5; color: #A0A0A0; font-style: italic; }

User can customize styling by updating the definition in the CSS file styles.css located in the Developer directory.