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

${StylusDir}, which indicates that the path you are specifying is relative to the Stylus Studio installation directory.

${PATH}, which specifies the PATH environment variable.

${OutputFile}, which is used to specify the output generated by the document wizard. This macro is available in the Command field only.

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.

Figure 545. Specifying a Custom Document Wizard 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

Displayed in the Document Wizards dialog box along with the icon you specify for the custom document wizard.

Used in the title bar of the dialog box the user sees when running the custom document wizard.

Document type

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

Figure 546. Document Type Field

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

The tab in the Document Wizards dialog box on which the custom document wizard is displayed (XML Editor, XSLT Editor, or Java, for example)

The editor Stylus Studio uses to display the output generated by the document wizard

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:


${InputFile} ${OutputFile} ${LoggingOption} ${SomeArgument}

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

Display the Custom Document Wizard Arguments dialog box, in which you can specify the command line arguments and their properties. See Defining Arguments for more information.

Browse for and select a file you want to specify.

Insert the ${StylusDir} macro.

Insert argument variable macros for arguments you have already defined.

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

Browse for and select a file you want to specify.

Insert the ${StylusDir} macro.

Insert the ${PATH} macro.

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.

Figure 547. Custom Document Wizard Arguments Dialog Box

Stylus Studio uses the arguments you define here to

Compose the dialog box used to run the custom document wizard. That dialog box enables users to provide values for the arguments you define.

Create argument variable macros, which you can then use to compose the command line template. Stylus Studio displays the argument variable macro it creates in the Command field menu.


Note		Every variable used in the command line template must be defined in the Custom Document Wizard Arguments dialog box.

How to display

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

Click the Arguments button on the Custom Document Wizard page. Use this procedure if you want to define arguments before composing the command line template.

Select Edit Arguments from the Command field menu that is displayed when you click

. You can use this procedure if you want to define arguments while composing the command line.

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.


Note		Whether or not the argument order defined here has to match the argument order in the command line template will vary from one custom document wizard to the next - arguments for some applications can be order independent, for example. Generally speaking, it is good practice for the argument order in the Custom Document Wizard Arguments dialog box to match that in the command line template.

Argument attributes

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

Name. Stylus Studio uses the value you enter in the Name field to compose the argument variable macro. This name is not displayed to custom document wizard users. Required.

Description. The value you enter in the Description field appears in the custom document wizard dialog box that is displayed to users when they run the wizard. The description should provide users with adequate information about the argument's expected value. It can be useful to distinguish input and output arguments, for example. Required.

Flag. The flag associated with the argument (-v, or simply - or /, for example). When Stylus Studio composes the command line for the custom document wizard, it uses the flag value as a prefix to the argument value supplied by the user.


Note		The Flag field must be specified for Boolean arguments.

Type. The argument's data type. Table 189 summarizes valid values for the Type field and describes possible values for those types

Table 189. Type Field Values
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.