Add user parameters to the Output Generator dialog box

This procedure describes how to add user parameters 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 for the PDF file—you can customize the Generate Output dialog box so that 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 parameters are displayed on the Generate Output dialog box:

User parameters are specified in the preprocessors.xml file. Each field in the Generate Output dialog 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 parameters, 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 parameters to the Output Generator dialog box:

Note: As an example, the procedure below shows how to create the user parameters for the sample dialog box in Figure 1.

Open the preprocessors.xml file that contains the preprocessor (for example, %OutputGenDir%/conf/client/preprocessors.xml).

Under the <system> element for the preprocessor, create a <user> element.

For example, to add user parameters for the acme.dita2xHtml output type, locate the acme.dita2xHTML preprocessor in the preprocessors.xml file and add a <user> element, as shown below:

<preprocessor 
      name="acme.dita2xHTML" 
      class="com.ixiasoft.outputgenerator.preprocessor.AntProcessor">
   <parameters>
      <system>
         <parameter name="buildfile" value="/conductor-acme.xml" />  
         <parameter name="target" value="acme.dita2xHtmlwrapper" />
         <parameter name="clean" value="job_postprocess" /> 
      </system>  
      <user>
         <!-- Enter user parameters here -->
      </user>    
   </parameters>
</preprocessor>

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. This parameter will be accessed in the Ant conductor file as follows: `outgen.job.userparam.name`
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 parameters.
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 parameter.
	`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. Note: This parameter type is no longer in use. It was created to support conditional processing before ditavals became standard. Ditavals replace the need for this parameter type.
	`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. Note: This parameter type is no longer in use. It was created to support conditional processing before ditavals became standard. You can use a ditaval instead of this parameter type.
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. 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 value of 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>

When you are done, save and close preprocessors.xml.
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>   
</user>