Configuring a Custom Document Wizard

This section provides information and procedures for configuring a custom document wizard. It covers the following topics:

The Custom Document Wizards Page

You use the Custom Document Wizards page of the Options dialog box to work with custom document wizards in Stylus Studio.

This section describes how to display the Custom Document Wizards page and information about its fields.

How to display
To display the Custom Document Wizards page:
1. In the Stylus Studio menu bar, select Tools > Options.

The Options dialog box appears.

2. If necessary, expand Application Settings and click Custom Document Wizards.

The Custom Document Wizards page appears.

About macros

Stylus Studio provides macros for some fields to help speed creation of custom document wizards. Available macros vary based on the field for which they are being used. To display macros available for a given field, click .

Predefined macros include

In addition, Stylus Studio creates argument variable macros for any arguments you define and displays them with other Command field macros.

Name

When you click the New button ( )to create a new custom document wizard, Stylus Studio displays an entry field for the name.

You should replace the default name (DocumentWizard1, for example) with the name you want to associate with the custom document wizard. The name you enter is

Document type

The Document type field displays a drop-down list of available document types when you click it:

The document type is the type of output generated by the custom document wizard (XML Schema, XQuery, and so on). The value you select determines

Icon bitmap

You use the Icon bitmap field to specify the path for the icon you want to represent the custom document wizard. This icon, along with the name you give the custom document wizard, is displayed in the Document Wizards dialog box. Click to browse for the file you want to specify or to insert the ${StylusDir} macro.

If you leave the Icon bitmap field blank, Stylus Studio uses the following default icon for the custom document wizard:

Command line

You use the Command line field to specify a command line template. Stylus Studio uses this template to compose the command line that invokes the custom document wizard. Variables, such as ${InputFile}, are used in place of actual arguments. Users specify argument values when they run the custom document wizard.

Consider the following example:

java -cp my.jar com.exln.stylus.Import ${QuoteChar} ${InputFile} ${OutputFile}

This command line template allows Stylus Studio to start the specified Java class with a command line that includes the QuoteChar, InputFile, and OutputFile arguments.

Argument variables can appear anywhere in the command. They must be in the form ${name}. For example:

You must specify the ${OutputFile} argument variable in every command line template. Stylus Studio always generates the name of the file it opens as the value for the ${OutputFile} argument variable.

As with the Icon bitmap field, you can click to display a menu that provides shortcuts that help you specify the command line template. This menu lets you

Initial directory

You use the Initial directory field to specify the directory you want Stylus Studio to use as the current directory when the custom document wizard is run. Click to browse for the file you want to specify or to insert the ${StylusDir} macro.

Path

You use the Path field to define paths to any files required by the custom document wizard. You do not have to define any paths that are already defined in your PATH environment variable. Separate multiple paths with a semicolon.

Click to display a menu that provides shortcuts that help you specify the PATH field. From this menu you can

Trace execution

If the custom document wizard you are configuring outputs processing information (error messages, stack traces, and so on), you can use the Trace execution feature to display this information in the Output Window of the Stylus Studio editor used to display the custom document wizard's generated document.

Defining Arguments

You must define any arguments required by the custom document wizard using the Custom Document Wizard Arguments dialog box.

Stylus Studio uses the arguments you define here to

How to display

There are two ways to display the Custom Document Wizard Arguments dialog box:

OutputFIle argument

Stylus Studio creates an OutputFile argument for each custom document wizard. You cannot delete this argument. You can change its order, if necessary, as described in the following section.

Argument order

By default, the arguments you define in the Custom Document Wizard Arguments dialog box are displayed to users in the order in which they are created. Arguments are displayed in a simple two-column grid, with the argument description in the first column, and an entry field for the argument value in the other. (See Figure 543 for an illustration of a custom document wizard dialog box.)

Also by default, the OutputFile argument appears first.

You can change the argument order by
1. Selecting the argument whose order you want to change.
2. Clicking the up or down arrow to the right of the argument list box as needed.

Argument attributes

You can specify the following attributes for each argument you define:

Type
Description
boolean
The value for a Boolean argument must be true or false. If the value is true, Stylus Studio inserts the value of the associated Flag attribute in the command line. No value other than the Flag value appears in the command line for Boolean arguments. If the value is false, the associated Flag value does not appear in the command line.
If you set Type to boolean, you must specify the argument's Flag attribute.
InputFile
The value for an InputFile argument is a URL that the custom document wizard user enters or selects by clicking the Browse button. If the format of the URL is for a protocol other than the file protocol, Stylus Studio copies the file into a temporary local file and uses the name of the temporary local file in the command line. You can specify multiple arguments whose data type is InputFile.
OutputFile
The custom document wizard user does not specify a value for the OutputFile argument. Exactly one argument must be of the OutputFile type. Stylus Studio generates a value for the OutputFile argument and inserts it in the command line.
string
The value for a string argument can be anything specified by the custom document wizard user. Stylus Studio encloses the string values in quotation marks when composing the command line.
Table 189. Type Field Values

How to define an argument
To define an argument:
2. Click the New button ( ).

A new argument is displayed in the Custom Document Wizard Arguments dialog box, with a default name and other default values.

3. Complete the argument attributes as described in earlier in this section. Remember that Description values appear in the custom document wizard dialog box when the user runs the wizard.
4. To define another argument, click the New button again.
5. If necessary, use the Up and Down arrows to change the argument order. Remember that the order in which arguments are displayed here is the order in which they appear in the custom document wizard dialog box when the user runs the wizard.
6. Click OK.

How to Configure a Custom Document Wizard

Before performing this procedure, you should be familiar with the information in The Custom Document Wizards Page and Defining Arguments.

To configure a custom document wizard:
2. Click the New button and enter a name for the custom document wizard. Remember that this value is used as the title for the dialog box displayed to the user when they run the wizard, as well as for the label associated with the custom document wizard icon displayed in the Document Wizards dialog box.
4. Select the custom document wizard's document type.
6. Optionally, specify an initial directory and path.
7. Click Trace execution if you want to display processing information generated by the custom document wizard in the Output Window of the Stylus Studio editor window associated with the custom document wizard's Document type.
8. Click OK.
 
Free Stylus Studio XML Training:
W3C Member