Add user parameters to the Output Generator dialog

This procedure describes how to add user parameters to the Generate Output dialog.

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:

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, IXIASOFT CCMS Output Generator looks up the preprocessor associated with this output type, retrieves the user parameters, if any, and displays them in the Generate Output 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 Generate Output dialog :

Note: As an example, the procedure below shows how to create the user parameters 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 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> 

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. 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.
   	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. 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 Generate Output dialog.	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, 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.

   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 CCMS Output Generator service to apply your changes.
   The Generate Output dialog box now displays the user parameters.

<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>