JavaScript API

You can find more information about editor integration on 'Editor Integration' page. DITA Storm exposes following methods to the enclosing HTML page: Method Description 

enableDoctype(
  <dtd_base_location>
)
Enables generation of DOCTYPE header for XML documents. Takes one parameter - a path to the directory containing DITA DTD files. Example: 
<SCRIPT>
  // specify directory for DTD files:
  //   /content/dtd/topic.dtd
  //   /content/dtd/map.dtd
  //   ...
  ditaStorm.enableDoctype('/content/dtd');
</SCRIPT>
If this method is not called the editor will not generate DOCTYPE header or will keep header of the original XML document. 
registerExension(
  <extension_name>,
  ...
)
 Registers DITA Storm extension point. See Editor Customization section for details. 
enablePhpFileOperations(
    <ditastorm_home_path>
)
 Enables file Open/Save operations implemented in PHP. This option turns on built-in file handling routines supplied with the product. Accepts one parameter specifying web browser path to the DITA Storm home directory. For example: 
<SCRIPT>
  ditaStorm.enablePhpFileOperations(
      '../DitaStorm')
</SCRIPT>
This method should be called before the editor is rendered with render() method PHP implementation for file open/save operations comes with the editor out-of-the-box. Similar functionality can be implemented with other applicaiton/web servers. You can request free same implementations for JSP and other technologies. 
render(
    <ditastorm_home_path>,
    <width>,
    <height>,
    <css_styles>,
    <compliled_xsl_styles>
)
 This method renders DITA Storm into HTML page. It accepts following parameters:
  1. path to the location of the DITA Storm home directory
  2. editor width (pixels or percents)
  3. editor height (pixels or percents)
  4. stylesheet to be used (by default the editor is supplied with simple.css)
  5. compiled version of stylesheet to be used by the editor (by default the editor is supplied with simple.xsl.js)
Here is the example: 
<SCRIPT>
  ditaStorm.render(
      '../DITAStorm','100%','300',
      'simple.css','simple.xsl.js');
</SCRIPT>
please remember, as on any HTML page your element will take specified 100% of available vertical space only if outermost element expands to the entire page (height attribute set to 100%). For example to make HTML element (DITA Storm) to consume entire remaining space on the page use code similar to this: 
<body>
  <table ... height='100%'>
     <tr height='10%'>...</tr>
     <tr height='90%'>...[dita editor]...</tr>
  </table>
</body>
 
loadXmlFile(
    <xml_file_path>
)
 Loads XML file from specified URL. URL is provided as a first parameter of the funciton call. Example: 
<SCRIPT>
  ditaStorm.render(...);   
  ditaStorm.loadXmlFile('/content/default.xml');
</SCRIPT>
 
getXml()
 Retrieves current contents of the editor as XML string. For example: 
<SCRIPT>
  var xmlString = ditaStorm.getXml();
  alert('Content: '+xmlString);
</SCRIPT>
By default the editor will return indentation-formatted XML you can switch between compact and formatted output using ditaStorm.setOutputFormatted() method. This method will return null if valid XML text can not be returned (such as when editing raw XML produced an error). By this time user has already been notified about the error. 
getFormattedXml()
 Retrieves indentation-formatted contents of the editor as XML string. Contents returned by this method is similar to the raw content editable in 'XML' mode. 
<SCRIPT>
  var xmlString = ditaStorm.getFormattedXml();
  alert('Formatted content: '+xmlString);
</SCRIPT>
This method will return null if valid XML text can not be returned (such as when editing raw XML produced an error). By this time user has already been notified about the error. 
setOutputFormatted(
  <formatted>)
 Enables or disables output formatting. This method affects both getXml() and updateField(). By default DITA Storm will generate formatted XML. 
<SCRIPT>
  ditaStorm.setOutputFormatted(false);
 var xmlCompact = ditaStorm.getXml();

  ditaStorm.setOutputFormatted(true);
 var xmlFormatted = ditaStorm.getXml();
</SCRIPT>
                        
setXml(
  <xml_content_as_string>
)
 Sets contents of the editor accepting XML as a string. For example: 
<SCRIPT>
  ditaStorm.setXml('<topic><title/></topic>');
</SCRIPT>
 
attachField(
  <form_name>,
  <field_name>
)
 Attaches DITA Storm editor to the specified form field. Accepts two parameters - form and field name. 
<FORM name='myForm' ...>
<INPUT name='ditaField' type='hidden'
    value='<topic><title>Lorem</title></topic>'>
...
<SCRIPT>
  ditaStorm.attachField('myForm','ditaField');
</SCRIPT>
See Editor Integration for more information. 
updateField()
 Updates form field previously attached with attachField() method. Often called onSubmit when updated data is ready to be sent to the server. 
<SCRIPT>
  function verfyAndSubmit()
  {
    ...
    ditaStorm.updateField();
    myForm.submit();
  }
</SCRIPT>
By default the editor will return indentation-formatted XML you can switch between compact and formatted output using ditaStorm.setOutputFormatted() method. See Editor Integration for more information. 
isModified()
 Returns true if contents of the editor has been modified since last load file or load xml operation. 
<SCRIPT>
  function onUnload() 
  {
    if( ditaStorm.isModified() )
    {
       confirm('Do you want to save changes?');
    }
  }
</SCRIPT>
 
setModified(
  <modified_indicator>
)
 Explicitly sets current status of the 'modified' flag of the editor. Editor would automatically change it to 'true' when content gets changed or to 'false' when new file or XML gets loaded. 
<SCRIPT>
  function quickSave() 
  {
     // Save data
     ...
     // Set indication that data has been saved
    ditaStorm.setModified(false);
  }
</SCRIPT>
 
enableUnloadConfirmation(
)
 Convenience method assigning simple 'on page unload' handler asking user to confirm page navigation if editor's 'modified' flag is set to true. You can clear the flag with setModified() method call if required. 
<SCRIPT>
  ditaStorm.enableUnloadConfirmation();
  ditaStorm.render('../DITAStorm','100%','100%',
    'simple.css','simple.xsl.js');
</SCRIPT>
This method sets window's onbeforeunload event handler. If your application uses it for other purposes we suggest using isModified() method and explicitly asking user's confirmation instead.