DITA Proposed Feature # NN

Allow window specifications for display of online content to be defined in the ditamap.

Longer description

When a Help system is invoked from an application, it is desirable to specify the size, position and behaviour of the window displaying the Help content. Some Help Application Programming Interfaces (APIs) provide for a window name to be passed in the Help call. In some cases, the definition for the window of the called window definition will be embedded in the Help system. In other cases, the complete window definition information will be passed in the Help call itself.

To cater for Help systems with embedded window information, it is important to define that information in the ditamap being processed, so that the processor can incorporate the definitions in the generated output file.

This proposal suggests adding a ua-window element, valid within the map element. The ua-window element would contain optional attributes of id, name, top, left, height, width, on-top, features, relative, and full-screen. None, one or many ua-window elements would be permitted within the parent element. The relative attribute is a Boolean flag used to indicate whether the window dimensions are relative to the calling window, or are absolute positions.

Example of markup:
<map title="Widget Help">
<ua-window id="fg23" name="csh" top="10" left="20" height="400" width="500" 
   features="status=yes,toolbar=no,menubar=no,location=no" relative="true",
   full-screen="no" />
 <topicref href="file_ops.dita" type="concept">
   <topicref href="saving.dita" type="task" />
   <topicref href="deleting.dita" type="task" />
   <topicref href="editing.dita" type="task">
     <topicmeta>
       <help help-id="5432" help-string="idh_fileedit" help-window="ua"  />
     <topicmeta>
   </topicref>
</topicref>
</map>

Scope

The ua-window element cannot be easily specialised from an existing element.

Use Case

A Help author is creating a Help system for a software application, which will provide field-level user assistance. The developers are implementing a Help API, which takes parameters of help file name, opening mode, (optional) topic number and (optional) window descriptor. The window descriptor is used to define the dimensions and other characateristics of the window into which a Help topic will display. The Help author wants to control the window descriptor, rather than the developer, as the window characteristics are dependent upon the nature of the topic content. The Help author therefore must create and store keyed window definitions at the publication (ditamap) level, and pass the window descriptor (keys) to the developer for integration with the application code.

Technical Requirements

If implemented as a specialisation, new DTD/Schema files and alterations to the topic shells would be required. Toolkit implementations need to modify the map2hhp and similar collection (book) level transforms. A related new ua-context element with a ua-window attribute would be required. The features attribute is modelled on the JavaScript window.Open method parameters.

Costs

Publishing tool changes could be implemented as XSL-T additions, at a relatively low (and one-off) cost. Authoring tool changes would only be required to provide an interface for the defining window descriptors and characteristics, at a relatively low cost.

Benefits

Post-processing of Help outputs generated from DITA source would no longer be required, and window metadata could be maintained within the DITA source rather than outside it.

Time Required

Unknown.