A simple procedure allows you to integrate Developer into a Web application or Content Management System by either attaching the editor to the text field of your HTML form, or loading DITA documents directly via an HTTP request. Basic required steps:
Include Developer libraries.
<LINK href="DITAStorm/styles.css" rel="stylesheet" type="text/css"/> <SCRIPT src="DITAStorm/DITAStorm.js" type="text/javascript"></SCRIPT>
Render Developer. At the selected location of the HTML page place the following code:
<SCRIPT> ditaStorm.render( 'DITAStorm','100%','300','simple.css','simple.xsl.js'); </SCRIPT>
Function render<path>,<width>,<height>,<css_file>,<compiled_xsl_file>) accepts the following parameters:
editor height (pixels or percents)
Load DITA document. Either directly from the server:
DITA<SCRIPT> ditaStorm.loadXmlFile('/cm/content/product.xml'); </SCRIPT>
or from the pre-populated text field:
<INPUT name='ditaField' type='hidden' value='<topic><title>Lorem Ipsum</title><body><p>...</p></body> </topic>'>
<SCRIPT> ditaStorm.attachField('myForm','ditaField'); </SCRIPT>
Retrieve modified DITA content. Either use the call JavaScript method:
<SCRIPT> // Use getXml() or getFormattedXml() to retrieve content
var xmlString = ditaStorm.getXml();
alert('Content: '+xmlString);
</SCRIPT>
or if you previously attached Developer to the form field, you can store the value back to the field:
<SCRIPT> ditaStorm.updateField(); </SCRIPT>
This example uses an HTML form with a text field and modifies it using Developer. Original HTML form:
<HTML>
<HEAD>
<SCRIPT>
function verifyAndSubmit() { ... }
</SCRIPT>
</HEAD>
<BODY onLoad='init()'>
<FORM name='myForm' onSubmit='verifyAndSubmit()'>
<INPUT name='ditaField' type='text'
value='<topic><title>Lorem Ipsum</title><body> <p>Morbi et lacus nec.</p></body></topic>'>
...
</FORM>
</BODY>
</HTML>
This HTML can be easily modified to enable DITA editing with Developer:
<HTML>
<HEAD>
<LINK href="DITAStorm/styles.css" rel="stylesheet" type="text/css"/>
<SCRIPT src="DITAStorm/DITAStorm.js" type="text/javascript"></SCRIPT> <SCRIPT>
function verifyAndSubmit() { // store XML back to the field and proceed with regular
// form submission
ditaStorm.updateField(); ... }
</SCRIPT>
</HEAD>
<BODY>
<FORM name='myForm' onSubmit='verifyAndSubmit()'>
<INPUT name='ditaField' type='hidden'
value='<topic><title>Lorem</title><body><p>...</p></body> </topic>'>
<SCRIPT> // Render editor and get value from the field
ditaStorm.render('DITAStorm','100%','300','simple.css', 'simple.xsl.js');
ditaStorm.attachField('myForm','ditaField');
</SCRIPT>
</FORM>
</BODY>
</HTML>
Developer can load XML content directly from a server via an HTTP request. JavaScript function loadXmlFile() retrieves the XML over HTTP and loads it into the editor. Sample code:
<HTML>
<HEAD>
<LINK href="/cm/lib/DITAStorm/styles.css" rel="stylesheet" type="text/css"/>
<SCRIPT src="/cm/lib/DITAStorm/DITAStorm.js" type="text/javascript"></SCRIPT>
</HEAD>
<BODY>
<SCRIPT>
ditaStorm.render( '/cm/lib/DITAStorm','100%','300','simple.css', 'simple.xsl.js');
ditaStorm.loadXmlFile('/cm/content/product.xml');
</SCRIPT>
</BODY>
</HTML>
loadXmlFile function can also be called at any time during the lifetime of Developer control on the Web page.
You can retrieve currently edited DITA XML as text via a JavaScript call using getXml() function. For example:
<SCRIPT> var xmlString = ditaStorm.getXml(); alert('Content: '+xmlString); </SCRIPT>
This example contains a simple prototype of a Web application utilizing Developer to provide in-place editing for a set of topics. The entire application is very simple, containing one PHP file (index.php - 3Kb) and Developer. DITA topics are stored in a file system.
File index.php contains both XML-to-HTML conversion and Developer rendering logic, switching between view and edit mode depending on the context:
Download InlineEditingPHP.zip »
Make sure PHP is configured to support XSL Unpack contents of the archive into a Web server directory. Then open index.php file in your browser.
This is an example of a very simple (4 JSP files) Content Management System. This package does not contain in-place editing functionality, but allows users to browse directories and modify .dita files using Developer.
You can unpack contents into any J2EE Web application. Before using, update utils.jsp, which includes an absolute path to the directory containing the DITA files (`content' directory like the one in the package):
public String contentRespositoryPath = "E:/Projects/.../WebContent/content";
Developer exposes the following methods to enclose the HTML page:
| Method | Description |
|---|---|
| enableDoctype(<dtd_base_location>) |
Enables generation of DOCTYPE header for XML documents. Takes one parameter - 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 the original XML document header. |
| registerExension(<extension_name>,...) |
Registers Developer extension point. See the 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 a Web browser path to the Developer home directory. For example: <SCRIPT> ditaStorm.enablePhpFileOperations( '../DitaStorm') </SCRIPT> PHP implementation for file open/save operations comes with the editor out-of-the-box. Similar functionality can be implemented with other application/Web servers. You can request the same implementations for JSP and other technologies. |
| render(<ditastorm_home_path>,<width>,<height>,<css_styles>,<compliled_xsl_styles>) |
This method renders Developer into an HTML page. It accepts the following parameters:
Here is the example: <SCRIPT> ditaStorm.render( '../DITAStorm','100%','300', 'simple.css','simple.xsl.js'); </SCRIPT> |
| loadXmlFile(<xml_file_path>) |
Loads an XML file from a specified URL, provided as a first parameter of the function call. Example: <SCRIPT>
ditaStorm.render(...);
ditaStorm.loadXmlFile('/content/default.xml');
</SCRIPT>
|
| getXml() |
Retrieves current contents of the editor as an XML string. For example: <SCRIPT>
var xmlString = ditaStorm.getXml();
alert('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 the user has already been notified about the error. |
| getFormattedXml() |
DITA IdentingRetrieves indentation-formatted contents of the editor as an XML string. Contents returned by this method are 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 the user has already been notified about the error. |
| setOutputFormatted(<formatted>) |
Enables or disables output formatting. This method affects both getXml() and updateField(). By default Developer 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 Developer 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>
|
| 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>
|
| isModified() |
Returns true if contents of the editor have been modified since the 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&rsquo' flag of the editor. Developer will automatically change it to 'true' when content is changed or to 'false' when a new file or XML is 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 the user to confirm page navigation if the editor's 'modified' flag is set to true. If required, you can clear the flag with setModified() method call. <SCRIPT>
ditaStorm.enableUnloadConfirmation();
ditaStorm.render('../DITAStorm','100%','100%', 'simple.css','simple.xsl.js');
</SCRIPT>
|