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 containing 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 name will be embedded in the Help system. In other cases, the complete window definition information may be passed in the Help call itself.

To cater for Help systems with embedded window information, it is important for that information to be defined 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

TBA

Technical Requirements

If implemented as a specialisation, new DTD/Schema files and alterations to the topic shells. 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

Toolkit changes could be implemented as XSLT additions, at a relatively low (and one-off) 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

TBA