Add user-defined fields to the Output Generator dialog box

This procedure describes how to add user-defined fields to the Output Generator dialog box.

If your output processing conductor file requires inputs from the user—for example, to determine which cover page to use on the PDF file—you can customize the Generate Output dialog box so that DITA CMS users can specify this information when they generate output. For example, you could allow users to specify the following information:
  • Document ID
  • Delivery scope: Public, Partner only, Internal
  • Publication Date
  • etc.

The example below shows how these user-defined fields are displayed on the Generate Output dialog box:

Figure 1. Generate Output dialog box

User-defined fields are specified in the preprocessors.xml file. Each field is associated with a user parameter in the preprocessor definition. When the user selects an output type, the Output Generator looks up the preprocessor associated with this output type, retrieves the user-defined fields, if any, and displays them in the Output Generator dialog. The values entered by the user are then passed to the Ant conductor file when generating the output.

To add user-defined fields to the Output Generator dialog box:
Note: As an example, the procedure below shows how to create the user-defined fields for the sample dialog box in Figure 1.
  1. Open the preprocessors.xml file that contains the preprocessor (for example, %OutputGenDir%/conf/client/preprocessors.xml).
  2. Under the <system> element for the preprocessor, create a <user> element.

    For example, to add user-defined parameters for the acmexHtml output type, locate the acmexHTML preprocessor in the preprocessors.xml file and add a <user> element, as shown below:

    <preprocessor 
          name="acmexHTML" 
          class="com.ixiasoft.outputgenerator.preprocessor.AntProcessor">
       <parameters>
          <system>
             <parameter name="outputfile" value=".xhtml"/>  
             <parameter name="buildfile" value="/conductor-acme.xml" />  
             <parameter name="target" value="acmexHtmlwrapper" />
             <parameter name="clean" value="clean" /> 
          </system>  
          <user>
             <!-- Enter user parameters here -->
          </user>    
       </parameters>
    </preprocessor> 
  3. Under the <user> element, create a <parameter> element for the parameter you want to define.

    The <parameter> element has the following structure:

    <user>
       <parameter label="param_label" name="param_name" mandatory="true|false" 
                  type="param_type" format="param_format" tooltip="param_tooltip"/>
    </user>

    The following table describes the <parameter> attributes:

    Table 1. Parameter attributes
    Attribute/ Element Description Values
    label Label that is displayed in the Generate Output dialog box. Any sequence of characters.

    This attribute is optional. If the label is not specified, the value of the name attribute is displayed in the dialog box.

    name Name of the parameter that is passed to the Ant conductor file when the output is generated. Any sequence of characters, without spaces. The name must match the parameter defined in the Ant conductor file.
    mandatory Determines whether users must enter a value for this parameter when generating the output.
    • false: Users do not have to enter a value.
    • true: The parameter is mandatory. The Create button is disabled until the user specifies a value for all mandatory fields.
    type Type of the parameter value. Can be one of the following:
      list Options list with check boxes. Specify the options with the <value> element.
      choice Options list combo box. Specify the options with the <value> element.
      string Any string in a text field.
      date Date (default is current date). For dates, you also need to specify the format attribute.
      integer User must enter an integer.
      index-list Options list with check boxes, based on the content of the index. The name attribute must match an index in the Index Definition document. This can be useful to generate options dynamically, without having to hard code them in the preprocessors file.
      index-choice Options list combo box, based on the content of the index. The name attribute must match an index in the Index Definition document. This can be useful to generate options dynamically, without having to hard code them in the preprocessors file.
    format For date parameters, this attribute is mandatory and specifies the format of dates entered by users.

    For other parameters, this attribute is optional and validates that the value entered by users corresponds to a specific pattern.

    For dates, enter a format as follows:
    • format="yyyy-MM-dd": 2001-07-04
    • format="MMM d, yyyy": Jul 4, 2001
    • format="d MMM yyyy": 4 Jul 2001

    The value entered must correspond to the Java data format. See http://docs.oracle.com/javase/1.4.2/docs/api/java/ text/SimpleDateFormat.html for more information.

    For other parameters, enter a regular expression; for example, the following format would accept input such as 2.3.009:
    format="[0-9][.][0-9][.][0-9]{3}"
    tooltip Tool tip displayed when the user moves the mouse pointer over the field in the Output Generator dialog box. Any sequence of characters. This parameter is optional.
    <value> element

    For parameters of type list and choice, you also need to create a <value> element to specify the options in the Generate Output dialog box, as follows:

    <parameter label="Available to:" name="classification" mandatory="true" type="choice">
       <value name="Public" _default="true">Public</value>
       <value name="Partner">Partner Only</value>
       <value name="Internal>Acme Internal</value>
    </parameter>
    Where:
    • name: is the parameter that is passed to the Ant conductor file when the output is generated.
    • _default="true": designates the default selection. If you do not specify a default selection in a choice type, the first <value> element in the list is used as default.
    The string entered as the content of the <value> elements is displayed in the Generate Output dialog box.
    The following code shows the user parameter definition to display the sample Generate Output dialog box shown in Figure 1:
    <user>
       <parameter label="Document Identifier" name="doc.id" mandatory="true" 
                  type="string"/>
       <parameter label="Available to:" name="classification" mandatory="true" 
                  type="choice">
          <value name="Public" _default="true">Public</value>
          <value name="Partner">Partner Only</value>
          <value name="Internal">Acme Internal</value>
       </parameter>
       <parameter label="Publication Date" name="doc.pubdate" mandatory="true" 
                  type="date" format="YYYY-MM-DD"/>
    </user>    
  4. When you are done, save and close preprocessors.xml.
  5. Restart the Output Generator service to apply your changes.
    The Output Generator dialog box should now display the user parameters.
Additional examples

The following code shows examples for each type of parameter.

<user>
   <-- Example of a string parameter -->
   <parameter label="Sample text field" name="text.field" mandatory="false" 
              type="string"/>

   <-- Example of an integer parameter -->
   <parameter label="Sample integer field" name="integer.field" 
              mandatory="false" type="integer"/>

   <-- Example of text field with validation -->
   <parameter label="Sample text field with validation" name="text.field2" 
              mandatory="false" type="string" 
              format="[0-9]*[.][0-9]*[.][0-9]{3}" tooltip="2.3.009"/>

   <-- Example of date field -->   
   <parameter label="Sample date" name="date" mandatory="false" type="date" 
              format="yyyy-MM-dd" tooltip="Format is yyyy-mm-dd"/>

   <-- Example of sample list --> 
   <parameter label="Sample list" name="list" mandatory="false" type="list">
      <value name="item1">Item 1</value>
      <value name="item2">Item 2</value>
   </parameter>

   <-- Example of sample choice parameter --> 
   <parameter label="Sample choice" name="choice" mandatory="false" 
              type="choice">
      <value name="value1" _default="true">Value 1</value>
      <value name="value2">Value 2</value>
   </parameter>

   <-- Example of sample index-list parameter -->
   <parameter label="Sample index-list (using audience)" name="audience" 
              mandatory="false" type="index-list"/>

   <-- Example of sample index-choice parameter -->
   <parameter label="Sample index-choice (using platform)" name="platform" 
              mandatory="false" type="index-choice"/>
</user>