You want to create or perform an operation on object(s) by collecting information step by step.

Wizards are popup windows that are used to guide you step by step through the process of creating an object, or performing an operation on an object. A wizard is a user interface consisting of a sequence of steps that lead the user through a specific task one step at a time, the user clicks next to move through the steps. It might not be necessary to complete all the steps present in a wizard. Once the required information is provided, you can click FINISH / OK button to submit the data to the server. A wizard can consist of one or many steps which must be completed in a certain order.

A clerk is a user interface consisting of a tab control that has two or more tabs. Data can be entered and the user can complete tabs in any order. A user may freely move from one tab to another, even if the current tab is not complete. A clerk is not meant to guide users sequentially through a task, and is typically used for frequent and easily accomplished tasks.

The layout for single step wizards and multi step wizards will be different. The single step wizard will not have “Step icons”, “Step links” and “Back / Next navigation buttons”.

Use a Wizard or Clerk component.

To achieve this objective, you need to have an understanding of the following:

Each step of the wizard and the wizard itself needs an action declaration for the associated page. Actions are grouped together using object types. These object types are declared inside of the <listofactions> tag contained in any one of the *actions.xml files. For more details on how actions work please see Action Framework for Windchill Client Architecture.

Windchill will expect all jsp pages related to this object type to be located in <Windchill>\codebase\netmarkets\jsp\<objecttype>. For the below specified example the location will be <Windchill>\codebase\netmarkets\jsp\changeTask\.

The “create” action is defined for the wizard page. By default, the name attribute of the action points to the main jsp page for your wizard relative to codebase/netmarkets/jsp, unless a url attribute is specified on the command tag. Therefore, for the action below Windchill will now expect “create.jsp” to be located in <Windchill>\codebase\netmarkets\jsp\changeTask\ folder. Since this action is for the wizard, it is necessary to specify windowType as “popup” inside the <command> tag. See Action Framework for Windchill Client Architecture for more details on the windowType attribute.

The “affectedAndResultingItemsStep” action is defined for the wizard step. The corresponding jsp should be located at <Windchill>\codebase\netmarkets\jsp\changeTask\affectedAndResultingItemsStep.jsp. Since this action is for the wizard step, it is necessary to specify windowType as “wizard_step”.

The command class is the java class that should be called to process the wizard data. Typically, this will extend CreateObjectFormProcessor.

Note that it is not necessary to specify a “method” attribute in the command tag if the form processor class extends DefaultObjectFormProcessor or CreateObjectFormProcessor.

Note that the “windowType” attribute of the command subtag for steps should always be set to “wizard_step.”

Optional action tag attributes are shown in the table below.

Here is an example action for launching a creation wizard for “MyPart” objects:

The validateCreateLocation() javascript method shown in the action above is applicable to create wizards that can be launched from a folder browser. See “Solution Elements” in Solution for more information.

Refer to Adding Actions and Hooking Them Up in the UI for more information on actions and the command tag attributes.

In addition to creating the wizard action, you will need to create text for the action name, wizard window title, action tooltip, etc. This is described in Adding Actions and Hooking Them Up in the UI.

Create a new jsp page inside customization/module1/main/src_web/netmarkets/jsp/ folder and name it as create.jsp. For more information, see the section Modular Structure for Customization in Building Wizards to Create a Single Object.

Wizard steps that are not preloaded should include the following directives at the top of the jsp page:

Most wizard steps will also use tags in the components.tld tag library and so will also need to include that as follows:

Define the wizard using the <wizard> tag. All the steps for this wizard will be defined inside <wizard> tag using <wizardStep> tag.

If a step is preloaded, none of these are required, but it is safe to include them. A non-preloaded-step:

Defining a clerk is exactly same as defining a wizard, the only difference in the case of a clerk is that you define the type as "clerk".

After defining the wizard type as "clerk", the wizard will be displayed as per the Clerk UI standards. Step indicators will not appear and step titles will be displayed as tabs. The Next and Previous buttons will not be displayed for Clerk. The user can navigate from any step to any step without entering the required fields. The validation for required fields will be done when the user clicks on the "OK" button. The user will be shown a message about required fields and will be taken to the appropriate steps, where required fields are not populated.

The Clerk Component has a provision through which application developers can call their specific validation logic.

For example: An application developer can write following code in jsp file to call javascript() on “OK” Button.

You can specify localized strings / properties in a <resourceBundle>.rbInfo file.

The format of each entry should be <objectType>.<action>.<property>.<type> = <value>. For example, you can specify the height and width of the popup window in which the wizard will be displayed, using the following property: changeTask.create.moreurlinfo.value=width=800,height=700

This can be any JSP page, and can contain any other component(s) as well as plain HTML contents.

You do not have to create new steps if already existing steps will work. See Customizing Reusable Wizard Steps for steps available to reuse.

This section contains the following topics:

You can change / specify different types of buttons that are present at the bottom of the wizard (i.e. the navigation area). The Wizard framework provides a default button model, which consists of buttons like NEXT, PREVIOUS, OK, APPLY and CANCEL. However, the Wizard framework also provides you the ability to specify your own set of buttons with user-defined functionality.

In <your_wizard_page>.jsp

You need to provide corresponding entry in actionmodels.xml file:

Every button in the actionmodel should have a corresponding entry for its action in actions.xml file. If there is a separate java class written to render that particular button, than you can specify the name of that class and its method (which contains the rendering code) using the “class” and “method” attributes of <command> tag. For example:

You can specify a form processor controller, which would be executed when the wizard is completed and the user clicks on OK, FINISH or APPLY button to submit it. The form processor controller gets the data specified in all the wizard steps, from Wizard framework, and processes it. After processing the data, a form processor controller returns an object of FormResult, along with the status. Based on the status (SUCCESS / FAILURE), which is returned, the wizard framework will decide further action. For example:

In <your_wizard_page>.jsp

You can implement server side validations using specific java classes and configuring the wizard to execute them before / after processing a wizard step. You can achieve this by using “beforeVK” and “afterVK” attributes of <action> tag. You need to provide a key as the value for these attributes. The corresponding key should be declared in any <*-service>.properties file specifying the java class which will perform the validations and return the result. For example:

OR

By default, all of the wizard steps are downloaded at wizard execution time.

You can configure the wizard such that the content of any wizard step is not loaded when the wizard is first initialized and loaded. You can load the contents of a wizard step when you try to visit that step. You may need this feature when the step is dependant on information gathered from a previous step.

You can use “preloadWizardPage” attribute of <action> tag to achieve this. By default, the value of this attribute is “true”. For example:.

You can mark a wizard step as “required”. By doing so, the wizard cannot be submitted unless and until this required step is visited at least once. So the submit buttons (like OK, FINISH or APPLY) would be enabled only after all the required steps are completed / visited at least once. For example:

You can also mark a wizard step as “required” at runtime. You need to use a javascript function called “setStepRequired” which is defined in main.js file. You need to pass the “id” of the step. The default id of the step is in the format “<type>.<action>”. Use the value of the “id” attribute if it is defined explicitly while defining wizard step action. For example:

There are two ways to hide a wizard step. First, you can hide a wizard step initially when the wizard is launched. Secondly, you can hide the wizard step at run time depending on certain criteria or certain user actions. In both the cases, it is mandatory to register the wizard step while defining the wizard.

In <your_wizard_page>.jsp

To implement first way of hiding a step, you can make use of the “hidden” attribute of <action> tag. For example:

In <*-actions>.xml

To hide a wizard step at runtime, you need to use a javascript function called “removeStep” which is defined in main.js file. You need to pass the “id” of the step that needs to be removed. The default id of the step is in the format “<type>.<action>”. Use the value of the “id” attribute if it is defined explicitly while defining wizard step action. For example:

In <your_wizardstep_page>.jsp

You can show up the hidden wizard step at runtime using the javascript function called “insertStep” which is defined in main.js file. You need to pass the “id” of the step that needs to be inserted. The default id of the step is in the format “<type>.<action>”. Use the value of the “id” attribute if it is defined explicitly while defining wizard step action. It is mandatory to register the wizard step while defining the wizard.

For example:

In <your_wizard_page>.jsp

In <*-actions>.xml

In <your_wizardstep_page>.jsp

The intended behavior for whether the steps in a multi-step wizard will be clickable is determined by a number of factors, including whether a step has been visited and/or completed, and whether a step is marked as required or not. The following list summarizes the intended behavior:

You can configure a user-defined javascript function, which will be called when the wizard is submitted. You need to write you own submit functionality in some javascript function and than pass the name of that function as an argument to “setUserSubmitFunction” (provided by wizard framework). By doing so, you are preventing the wizard framework to call the default submit function. Based on the return value (true / false), the wizard framework will decide further action. For example:

You can configure a user-defined javascript function, which will be called when a wizard step is loaded but before it is displayed. You need to write you own functionality in some javascript function and specify the name of function as the value for the attribute "beforeJS" while defining the action for that particular step. This particular step will only be displayed if the specified function returns "true", else the wizard will move to the previous step. For example:

In <*-actions>.xml

In any JSP page or Javascript file accessible to wizard

You can configure a user-defined javascript function, which will be called when a wizard step is completed but before next step is loaded. You need to write you own functionality in some javascript function and specify the name of function as the value for the attribute "afterJS" while defining the action for that particular step. The next step will only be displayed if the specified function returns "true".

For example:

In <*-actions>.xml

In any JSP page or Javascript file accessible to wizard

You can suppress form submission on enter key.

You can change the default focus element in the wizard. Generally the infrastructure will try to make the default focus element the first required field that is editable (input, select, or textarea tag). This is very tricky and so the infrastructure may not get it right in all cases.

If a different element is desired for the first focused element, or this behavior is not working properly in your wizard then you can create some javascript code to get your desired behavior.

//First, Remove the current focus listener to avoid any race conditions. For Example:

Validation of the data entered by users is done after each step and in some cases after each input field is completed. It may be done on the client via javascript and/or on the MethodServer via a Java class that extends UIComponentValidator.

The system automatically validates that all required attribute values are provided if the input fields are generated by the standard renderers. The renderers add a “class="required"” attribute to the input field and the wizard javascript checks to make sure that each field with such an attribute has a value. You can do other client validation in a javascript method by specifying the method as the value of the afterJS attribute of the step action. See Adding Custom Code to all Windchill Client Architecture Pages for information on how to package your custom javascript.

Validation of data values against constraints defined for the attributes in the Type and Attribute Management utility must be done in the MethodServer. This is done by implementing the validateFormSubmission() method on a subclass of DefaultUIComponentValidator. You then specify the name of the selector key for a service.properties entry pointing to your DefaultUIComponentValidator in the afterVK attribute of your step action. The validateFormSubmission() method of your validator class will be automatically called by the framework when the user clicks the Next or OK button on a step. It is also called when the value of any attribute in the driver attributes panel is changed.

Default server-side validators are available for the Set Context, driver attributes table, and Set Attributes wizard steps. The selector keys and validator class paths are specified in the following entries in components.service.properties.xconf:

If the out-of-the-box validator classes meet your needs you can use them by specifying the selector strings shown in the entries above as the values of the afterVK attributes of your wizard step actions. If you need to do additional validation, you can write your own validators, typically subclassing the standard validators. Note that all the form data can be accessed from the UIValidationCriteria parameter passed to the validator by calling UIValidationCriteria.getFormData(). The validateFormSubmission() method should return a UIValidationResult with a status of UIValidationStatus.PERMITTED if all the form data is valid or a status of UIValidationStatus.DENIED if one or more attribute values are not valid. In the latter case, the user will be returned to the wizard step just completed to correct the invalid values. Feedback messages to be displayed to the user should be added to the UIValidationResult using the UIValidationResult.addFeedbackMsg() method.

Windchill Wizard framework takes help from Windchill Action framework to pick up the localized wizard title either from the related .rbInfo or from a action_<locale>.properties file. It uses the <objectType> and <action> to fetch the required value. The problem arises when you try to use “url” attribute of “command” tag (while defining the wizard action). If the value of the “url” attribute points to a jsp page whose name matches with some another action, the wizard framework will receive localized title corresponding to that action.

Consider the following scenario:

In the above specified case, the wizard title for the action “createMultiPart” will be picked up from the property “part.createPartWizard.title.value” and not from the property “part.CreateMultiPart.title.value”.

The workaround for this scenario is to use the “title” attribute of the wizard tag. If this attribute is specified, the wizard framework will not try to look in to any rbInfo or properties file. However, be sure that you provide a localized string as a title to wizard tag. For example:

Clerks will execute only required fields validation for all the clerk steps. All the other validations mentioned below should be provided by the respective clerk developers:

In case of clerk, while navigating between steps any java code such as a validator may not get the required fields so developers need to take care and apply logic accordingly.( E.g. While creating a new document first step has required field type (means type of document), since in clerk user is free to navigate between other tabs while clicking on other tabs,user might not have selected required filed type in first step. In that case server validator can’t get value of type attribute.)