PRODUCTS

DOWNLOAD

BUY

LEARN

SUPPORT

COMPANY

Cart

< Previous | Next >

Custom Document Wizards

Stylus Studio's custom document wizard feature allows you to create and configure document wizards that invoke third-party file conversion and document generation tools, such as Thai Open Source's Trang. When run, a custom document wizard passes argument values provided by the user (the name of the file to be converted, for example) to the command line that invokes the third-party tool. The third-party tool generates an output file as specified in the custom document wizard's command line, and the file is then opened by Stylus Studio in the appropriate editor.

Example

An example of a custom document wizard is the DTD to XML Schema (Trang) document wizard shipped with Stylus Studio.

Figure 326. A Custom Document Wizard

This document wizard was created using the custom document wizard feature.

Registering a Custom Document Wizard

The process of registering a custom document wizard in Stylus Studio involves the following steps:

1. Make the necessary third-party software available to Stylus Studio. For example, any .jar or .exe files associated with the document conversion or generation tool must be accessible from the Stylus Studio installation.

2. Configure the custom document wizard on the Custom Document Wizards page of the Options dialog box. This step involves

a. Providing a name and, optionally, an icon, for the custom document wizard.

b. Setting the document type.

c. Specifying a command line template.

d. Defining any arguments required by the command line.

e. Optionally setting a trace feature that displays processing provided by the third-party tool.

More information for each of these steps is provided in the following section, Configuring a Custom Document Wizard.

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

Defining Arguments

How to Configure a Custom Document Wizard

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.

Figure 327. Custom Document Wizards Page

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

${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 328. 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 329. 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 330. 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 Example 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 73 summarizes valid values for the Type field and describes possible values for those types

Table 73. 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.

Default Value. The value used by Stylus Studio for optional arguments, unless another value is specified by the user when the custom document wizard is run. Default values for required arguments are ignored - Stylus Studio requires users to enter values for required arguments.

Optional. Whether or not the argument is optional. Valid values for this field are true or false.

How to define an argument

To define an argument:

1. Display the Custom Document Wizard Arguments dialog box. See How to display if you need help with this step.

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.

Figure 331. Custom Document Wizard Arguments Dialog Box

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

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:

1. Display the Custom Document Wizards page of the Options dialog box. See How to display if you need help with this step.

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.

3. Click the Arguments button and define the wizard's arguments on the Custom Document Wizard Arguments dialog box. See Defining Arguments if you need help with this step.

4. Select the custom document wizard's document type.

5. Specify the command line template. See Command line if you need help with this step.

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.

< Previous | Next >