Skip to main content
Previous section

Zen Wizards

This chapter describes the Studio wizards that Zen provides:

There is also a Studio tutorial that uses Zen wizards to create the user interface for a simple application. See the chapter “Building a Simple Application with Studio” in the book Using Studio.

New Zen Application Wizard

Note:

For background information, see the chapter “Zen Application Concepts.” For a sample wizard session, see the “Creating a Zen Application” exercise in the chapter “Zen Tutorial.”

You can use the New Zen Application Wizard as follows:

  1. Start Studio.

  2. Choose File > New or Ctrl-N or the images/gzen_studio_new.png icon.

  3. Click the Zen tab.

  4. Click the New Zen Application icon.

  5. Click OK to display the Zen Application Wizard dialog.

  6. Enter data in the following fields:

    • Package Name — Package that contain the new application class.

    • Class Name — Class name of the new application class.

    • Application Name — Logical name of the application.

    • Description — Any text that you want to use to describe the application.

  7. Click Finish to close the dialog and display your new Zen application class in Studio.

  8. Modify the Zen application class as desired.

    To supply style definitions that apply to all pages in this application, use the Zen Style Wizard to edit XData Style or set the CSSINCLUDES class parameter.

  9. Choose Build > Compile or Ctrl-F7 or the images/gzen_studio_compile.png icon.

New Zen Component Wizard

Note:

For background information, see the “Custom Components” chapter in the book Developing Zen Applications

You can use the New Zen Component Wizard as follows:

  1. Start Studio.

  2. Choose File > New or Ctrl-N or the images/gzen_studio_new.png icon.

  3. Click the Zen tab.

  4. Click the New Zen Component icon.

  5. Click OK to display he Zen Component Wizard dialog.

  6. Enter data in the following fields:

    • Package Name — Package that contain the new component class.

      Important:

      InterSystems strongly recommends that you do not create any classes in a package called ZEN.Component using any combination of uppercase and lowercase characters. Creating a package called ZEN.Component breaks the Zen framework for generating client-side code.

    • Class Name — Class name of the new component class.

    • Type — Choose a parent class for the component:

      • component. See “Creating Custom Components” in the “Custom Components” chapter of Developing Zen Applications.

      • composite. See “Composite Components” in the “Custom Components” chapter of Developing Zen Applications.

      • control. See the “Zen Controls” chapter in Using Zen Components and the “Custom Components” chapter in Developing Zen Applications.

      • svgComponent. See “Creating Custom Meters” in the “Custom Components” chapter of Developing Zen Applications.

    • XML Namespace — If the component is a composite, you must reference this namespace when you place the component on a Zen page, using the syntax <namespace:componentName>. For details, see the section “XML Namespace for Custom Component Classes” in the “Custom Components” chapter of Developing Zen Applications.

    • Description — Any text that you want to use to describe the component.

  7. Click Finish to close the dialog and display your new Zen component class in Studio.

  8. Modify the Zen component class as desired:

    • Be sure to implement the %DrawHTML method. The wizard provides a template for this method in the class.

    • If you want to supply style definitions for the custom component, consult the section “Custom Style” in the “Custom Components” chapter of Developing Zen Applications. You can use the Zen Style Wizard to add style definitions.

  9. Choose Build > Compile or Ctrl-F7 or the images/gzen_studio_compile.png icon.

New Zen Page Wizard

Note:

For background information, see the chapter “Zen Application Concepts”. For a sample wizard session, see the “Creating a Zen Page” exercise in the chapter “Zen Tutorial.”

You can use the New Zen Page Wizard as follows:

  1. Start Studio.

  2. Choose File > New or Ctrl-N or the images/gzen_studio_new.png icon.

  3. Click the Zen tab.

  4. Click the New Zen Page icon.

  5. Click OK to display the Zen Page Wizard dialog.

  6. Enter data in the following fields:

    • Package Name — Package that contain the new page class.

    • Class Name — Class name of the new page class.

    • Application — Package and class name of the application that this page belongs to.

    • Page Name — Logical name of this page within its application.

    • Domain — Domain this page uses for localization of caption text.

    • Description — Any text that you want to use to describe the page.

    • Page type — Choose one of the following:

      • Page — Normal page class.

      • Subclass of Template Page — Subclass of a template page class. Choose this option to display the Super class assisted text control. Once the control is visible, click the text field to display an alphabetical list of first level packages. Double-click to select a package from the list. The list refreshes to show classes available for the selected package. You can also type a package name ending with a period (".") into the field, and follow with a carriage return, and the list refreshes to show available classes.

  7. Click Next.

  8. Choose an initial page layout:

    • Column 2 — Two columns, plus space for a title along the top

    • Title Page — Space for a title along the top

    • Default — No predefined layout

  9. Click Finish to close the dialog and display your new Zen page class in Studio.

  10. Modify the Zen page class as desired:

  11. Choose Build > Compile or Ctrl-F7 or the images/gzen_studio_compile.png icon.

  12. Choose View > Web Page or the images/gzen_studio_webpage.png icon to display the page in the browser.

New Zen Report Wizard

Note:

For background information and a sample wizard session, see the “Building a Zen Report” chapter in Zen Reports.

You can use the New Zen Report Wizard as follows:

  1. Start Studio.

  2. Choose File > New or Ctrl-N or the images/gzen_studio_new.png icon.

  3. Select the Zen tab.

  4. Click the New Zen Report icon.

  5. Click OK to display yhe Zen Report Wizard dialog.

  6. Enter data in the following fields:

    • Package Name — Package that contains the report class.

    • Class Name — Report class name.

    • Application — Package and class name of the application that this report belongs to. The default value is %ZEN.Report.defaultApplication.

    • Report Name — Logical name of this report within its application. Supplies the value of the name attribute of the generated <report> element in the XData ReportDefinition and XData ReportDisplay blocks.

    • Description — Any text that you want to use to describe the report.

  7. Click Next. The wizard prompts for an SQL query to provide data for the report.

  8. You can type an SQL query into the text box.

    Note:

    If you leave the box blank, you can and add a query during later editing, or use other methods to acquire data as described in the “Building the <report> or <group> Query” section.

  9. Click Finish to close the dialog and display your new Zen report class in Studio.

  10. Find the following text in the XData ReportDefinition block:

    <!-- add definition of the report here. -->
    Copy code to clipboard

    Delete this comment. Add a <group> element between <report> and the closing </report> element.

    Note:

    For background information, see the “Gathering Report Data” chapter in Using Zen Reports.

  11. The <report> element in the XData ReportDisplay block contains a series of optional page formatting elements, followed by the required <body> element.

    Note:

    For additional information, see the “Formatting Report Data” chapter in Using Zen Reports.

  12. Set the DEFAULTMODE class parameter value to indicate the report output format.

  13. Modify the Zen report class as desired.

  14. Choose Build > Compile or Ctrl-F7 or the images/gzen_studio_compile.png icon.

  15. Choose View > Web Page or the images/gzen_studio_webpage.png icon to display the report in the browser.

Studio Assist

Note:

For background information and a sample wizard session, see the sections “Hello World” and “Creating a Zen Page” in the chapter “Zen Tutorial.”

You can use Studio Assist (word completion as you type) within Zen classes as follows:

  1. Start Studio.

  2. Open a Zen page or report class.

  3. Position the cursor in one of the following elements and click to move the insertion point there:

  4. Begin typing. At the first meaningful character, Studio provides a context-sensitive list of appropriate XML elements and attributes. This list includes the built-in Zen components as well as any custom or composite components that you have defined.

  5. To choose an item from this list, click on it and press Enter.

  6. Studio completes the word and adds it to the code.

Zen Chart Wizard

Note:

Every chart is an SVG component as described in the “Zen and SVG” chapter of Using Zen Components. This means that charts follow the layout and style conventions for SVG components, with the additional characteristics described in the “Zen Charts” chapter of Using Zen Components. Most importantly, a Zen chart must appear within an <svgFrame> container. Remember this when adding a chart to XData Contents.

You can use the Zen Chart Wizard as follows:

  1. Start Studio.

  2. Open the class.

  3. Place the cursor inside XData Contents and click to move the insertion point there.

  4. Choose Tools > Templates > Templates or press CTRL-T to display the list of Zen templates.

  5. Select the Zen Chart Wizard.

  6. Click OK to display the Zen Chart Wizard dialog.

  7. The Type field presents a list of chart types. Each has documentation in the “Zen Charts” chapter of Using Zen Components:

  8. Choose a chart type.

  9. Click Next to display the Zen Chart Wizard a split screen:

    • At left is an illustration of how the current attributes affect chart style.

    • At right is a list of attributes. Above this list, you can click Chart, X Axis, or Y Axis to view the attributes for these different aspects of the chart.

  10. To provide a value for any attribute, click in the field beside it to display a popup button images/gzen_wizard_popup_icon.png in the field. Click on the popup button. The Zen Value Editor dialog pops up. The entry field in this dialog is sensitive to the data type of the property. For example:

    • If the type is boolean, the dialog provides a check box.

    • If one value must be selected from a set, the dialog displays radio buttons.

    • If the type is a CSS style definition, the CSS Declaration Editor pops up. To use this editor, see the instructions in the “Zen Style Wizard” section beginning at step 10.

    • If the type is a JavaScript expression, a text area offers room to type the entry.

    In all cases, a brief description of the property appears on the dialog, below the entry field. For details, and for descriptions of how the individual properties work together, you can find documentation in the “Zen Charts” chapter of Using Zen Components.

    Click OK to save your changes and return to the Zen Chart Wizard. The list of chart attributes now contains your entry. You may repeat this step as often as needed to supply attributes for this chart.

  11. To accept the result of all your changes to this chart definition, click Finish. The Zen Chart Wizard dialog closes and the completed chart definition appears in the XData Contents block of your Zen page class.

Zen TablePane Wizard

Note:

For background information, see the chapter “Zen Tables.”

You can use the Zen TablePane Wizard as follows:

  1. Start Studio.

  2. Open the class.

  3. Place the cursor inside XData Contents and click to move the insertion point there.

  4. Choose Tools > Templates > Templates or press CTRL-T to display the list of Zen templates.

  5. Select the Zen TablePane Wizard.

  6. Click OK to display the Zen TablePane Wizard dialog.

  7. The two radio buttons let you select a data source for the table pane:

    • Select Table, to specify the name of an SQL table. To display Caché objects, enter a class name, such as Sample.Person.

    • Select Class query to specify the name of a class and the name of a query in the class.

  8. Click Next to display the Zen TablePane Wizard in a split screen:

    • At left is an area labeled Columns. Enter the names of columns in the data source, one at a time, pressing Enter between entries. When you have entered names of all the columns you want in the table, press Tab or click outside the Columns box. This triggers a refresh and data load to the grid below

    • At right is an area labeled tablePane Attributes which list attributes of the <tablePane>. You can use the Value column to edit attribute values. See the following step for details about how to edit attribute values.

    • Below these two areas is an area that displays a preview of the table.

  9. To provide a value for any attribute, click in the field beside it to display a popup button images/gzen_wizard_popup_icon.png in the field. Click on the popup button. The Zen Value Editor dialog pops up. The entry field in this dialog is sensitive to the data type of the property. For example:

    • If the type is boolean, the dialog provides a check box.

    • If one value must be selected from a set, the dialog displays radio buttons.

    • If the type is a CSS style definition, the CSS Declaration Editor pops up. To use this editor, see the instructions in the “Zen Style Wizard” section beginning at step 10.

    • If the type is a JavaScript expression, a text area offers room to type the entry.

    In all cases, a brief description of the property appears on the dialog, below the entry field.

  10. To accept the result of all your changes to this table definition, click Finish. The Zen TablePane Wizard dialog closes and the completed table definition appears in the XData Contents block of your Zen page class.

Zen Element Wizard

Note:

For background information, see the chapter “Zen Layout.”

You can use the Zen Element Wizard as follows:

  1. Start Studio.

  2. Open the class.

  3. Place the cursor inside XData Contents and click to move the insertion point there.

  4. Choose Tools > Templates > Templates or press CTRL-T to display the list of Zen templates.

  5. Select the Zen Element Wizard.

  6. Click OK to display the Zen Element Wizard dialog.

  7. In the Element field, click the down-arrow to display a drop-down list of Zen components. This list includes the built-in Zen components as well as any custom or composite components that you have defined. Components in this list are sorted alphabetically by package name, so the order is:

    • Auxiliary components, such as <column> for <tablePane>

    • Built-in Zen components, such as <tablePane>

    • User-defined components, such as composites or custom components

  8. Click on a component name.

  9. Click Next. The Zen Element Wizard displays an alphabetical list of the properties of the component that you selected.

  10. To provide a value for any property, click the Edit button beside its name. The Zen Value Editor dialog pops up. The entry field in this dialog is sensitive to the data type of the property. For example:

    • If the type is boolean, the dialog provides a check box.

    • If one value must be selected from a set, the dialog displays radio buttons.

    • If the type is a CSS style definition, the CSS Declaration Editor pops up. To use this editor, see the instructions in the “Zen Style Wizard” section beginning at step 10.

    • If the type is a JavaScript expression, a text area offers room to type the entry.

    In all cases, a brief description of the property appears on the dialog, below the entry field. If you need more detail, you can find documentation in the corresponding chapters of this book:

    Or in the book Using Zen Components:

    Or in the book Developing Zen Applications:

  11. Make changes as desired and click OK to save your changes and return to the Zen Element Wizard. The list of properties now contains your entry. You may repeat the previous step and this one as often as needed to supply values for properties of this component.

  12. To accept the result of all your changes to this component definition, click Finish. The Zen Element Wizard dialog closes and the completed component definition appears in the XData Contents block of your Zen page class.

Zen Method Wizard

Note:

For background information and a sample wizard session, see “Step 3: Client-side Method” and “Step 5: Server-side Method” in the “Creating a Zen Page” exercise in the chapter “Zen Tutorial.”

You can use the Zen Method Wizard as follows:

  1. Start Studio.

  2. Open a Zen page class.

  3. Position the cursor at the end of the class, but before the final curly bracket character. Click to move the insertion point above the curly bracket.

  4. Choose Tools > Templates > Templates or press CTRL-T to display the list of Zen templates.

  5. Select the Zen Method Wizard.

  6. Click OK to display the Zen Method Wizard dialog.

  7. Choose a method Scope, either instance or class.

  8. Choose a Location where the method executes, and enter a Method Name.

    By convention, method execution and names are related as follows.

    Location Choice Method Type Naming Convention
    runs on the client Client-only myMethod
    runs on the server Zen method MyMethod
    is only available on the server Server-only utility %MyMethod
    is a server-side callback for a component Server-only callback MyMethod

    For details, see the “Zen Naming Conventions” section in the chapter “Zen Tutorial.”

  9. If you choose the option is a server-side callback for a component in the step 8, the Zen Method Wizard dialog adds a Server-side callback field. This field offers a drop-down list of attributes whose value is the name of a server-side callback method. These include attributes such as <form> OnSubmitForm or <html> OnDrawContent. Choose a component and attribute from this list.

    The Server-side callback entry adds a comment to your method body, reminding you which component and attribute you intend to associate with this callback method. You must still add the relevant attribute to the component definition in XData Contents, but the reminder can be useful as you work with the class.

  10. In the Description field, enter any text that you want to use to describe the method.

  11. Leave the Try/Catch check box selected if you want the wizard to write a try/catch error processing template into your method. For details, see the “Error Processing” chapter in the book Using Caché ObjectScript.

    In a client-side method the template looks like this:

    ClientMethod mMethod() [Language = javascript]
    {
      try {
        alert('Client Method');
        // TODO: implement
      }
      catch (ex) {
        zenExceptionHandler(ex,arguments);
      }
    }
    Copy code to clipboard

    In a server-side method the template looks like this

    Method MyMethod() [ZenMethod]
    {
      Try {
        // TODO: implement
        &js<alert('Server Method');>
      }
      Catch(ex) {
        &js<alert('Error:\n#($ZCVT(ex.DisplayString(),"O","JS"))#');>
      }
      Quit
    }
    Copy code to clipboard

    To skip this feature, clear the Try/Catch check box.

  12. Click Finish to close the dialog and display your new method definition within the Zen page class in Studio.

  13. Implement the method as desired.

Zen Style Wizard

Note:

For background information, see the chapter “Zen Style.”

You can use the Zen Style Wizard as follows:

  1. Start Studio.

  2. Open the class whose XData Style block you want to edit.

  3. Within the XData Style block, place the cursor between <style> and </style>. Click to move the insertion point there.

  4. Choose Tools > Templates > Templates or press CTRL-T to display the list of Zen templates.

  5. Select the Zen Style Wizard.

  6. Click OK. A list of predefined styles appears. This list is organized alphabetically by component name. The “Overriding Built-in Styles” section in the chapter “Zen Style” explains that some of the component names may be unfamiliar. These are the parent classes for components that you actually place on the Zen page. For example, to edit styles for tablePane (the child) you must select styles from the list provided for simpleTablePane (the parent).

  7. Scroll down the list to see the styles that it offers.

  8. Select the radio button next to the name of the CSS style you want to edit.

  9. Click Next. The Zen Style Wizard echoes your selection and provides a sample of its current appearance.

  10. Click Edit to display the CSS Declaration Editor. You can add, remove, or edit statements as many times as needed to define the CSS rule.

  11. To add a CSS name-value pair:

    • Click on the item --New-- in the CSS Declarations text box.

    • Click the down-arrow on the Property box to display an alphabetized list of CSS argument names (background-color, font-weight, width, etc). Click on a name to choose it.

    • Either type a CSS value in the Value field or click the Edit button to display the CSS Value Editor.

    • The CSS Value Editor is sensitive to the values that can be entered for the CSS argument you chose. If there is a fixed list of options, you can choose them from a drop-down list. If there is the option of typing in a value other than the fixed list, you can do that too.

    • If you choose a compound CSS style argument such as border-top, the editor prompts you for each choice independently, for example:

      • width — thin, medium, thick, 1px, 2px, 3px, 4px, inherit

      • style — none, hidden, dotted, dashed, solid, double, groove, ridge, inset, outset, inherit

      • color — A drop-down list of standard CSS color names including black, blue, red, darkred, etc. Alternatively you can click the Browse button to display a detailed color choice dialog where you can make a visual color selection. When you click on a color sample in this dialog and click OK, Zen provides this color to your CSS statement as an HTML color value.

      The result is then something like this: border-top: 1px solid #70DFF0;

    • Click OK to save your changes and return to the CSS Declaration Editor. The CSS Declarations text box now contains the new name-value pair, as well as any others you have previously added.

  12. To remove a CSS name-value pair:

    • Click on the corresponding line in the CSS Declarations text box.

    • Click the Remove button to the right of the Property box.

    • Click OK to save your changes and return to the CSS Declaration Editor. The CSS Declarations text box no longer displays the name-value pair that you removed.

  13. To edit a CSS name-value pair:

    • Click on the corresponding line in the CSS Declarations text box.

    • Either type a CSS value in the Value field or click the Edit button to display the CSS Value Editor.

    • Use the CSS Value Editor to choose and enter values as in step 11.

    • Click OK to save your changes and return to the CSS Declaration Editor. The CSS Declarations text box now contains the modified version of the name-value pair, as well as any others you have previously added.

  14. When you are satisfied with your modifications in the CSS Declaration Editor dialog, click OK. The Zen Style Wizard echoes your choices and displays a sample of the resulting style. After examining this sample you may do one of the following:

    • To resume changes to this style definition, return to step 10.

    • To accept the result of all your changes to this style definition, click Finish. The Zen Style Wizard dialog closes and the completed style definition appears in the XData Style block of your class.