Wizard Framework

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Web Client Extension

This page explains how the wizard framework works, what configuration options are available and how you implement your own wizards.

Table of Contents

• 1 Configuration
  
  
  
  • 1.1 wizard element
  
  
  • 1.2 step element
  
  
  • 1.3 page element
  
  
  • 1.4 condition element
  
  


• 2 Wizard Manager


• 3 JSPs


• 4 Wizard Beans


• 5 Actions


• 6 Future Enhancements

Configuration

Configuration for wizards belong within a <wizards> element, an individual wizard is represented by the <wizard> element. The 'default' wizards are defined in the global config section i.e. there is no evaluator or condition. This can be found in web-client-config-wizards.xml.

These may be overridden using a more specific config section, for example, a wizard definition could be overridden for a   particular type of node. As usual, any customisations should be applied to web-client-config-custom.xml as explained in the Web Client Configuration Guide. Combining of configuration is NOT supported for wizard definitions. This means the whole wizard definition has to be copied to the custom file and adjusted appropriately. We may support the combining of wizard definitions in a future release.

A simple two step wizard definition is shown below:

<wizard name='runAction' 
        managed-bean='RunActionWizard'
        title-id='run_action_title' 
        subtitle-id='run_action_subtitle'
        description-id='run_action_desc'
        icon='/images/icons/new_rule_large.gif'
        error-message-id='error_run_action_wizard'
        actions-config-id='more_actions_menu'>
            
   <step name='actions' 
         title-id='actions' 
         description-id='run_action_step1_desc'>
      <page path='/jsp/actions/actions.jsp' 
            title-id='run_action_step1_title'
            description-id='run_action_step1_desc'
            instruction-id='default_instruction' />
   </step>
   <step name='summary' 
         title-id='summary' 
         description-id='summary_step_description'>
      <page path='/jsp/wizard/summary.jsp'
            title-id='summary' 
            description-id='summary_desc' 
            instruction-id='run_action_finish_instruction' />
   </step>
</wizard>

wizard element

name: The unique name (id) of the wizard

managed-bean: The name of the JSF managed bean to be used as the backing bean for the wizard

icon: The path to the icon displayed in the header area of the wizard

title-id: The id of a string to be used as the title of the wizard

subtitle-id: The id of a string to be used as the subtitle of the wizard

description-id: The id of a string to be used as the description of the wizard

error-message-id: The id of a string to be used in the case of an error

There are a few other attributes available, title, subtitle and description. You can use these in place of title-id, subtitle-id and description-id if you want to use a literal string instead of an I18N string.

step element

name: The unique name (within the wizard) of the step

title-id: The id of a string to be used as the title of the step (appears in the list of steps on the left hand side)

description-id: The id of a string to be used as the description of the step (the tooltip for the step on the left hand side)

Again, title and description are available for specifying literal strings.

page element

path: The path to the JSP to use for the step of the wizard

title-id: The id of a string to be used as the title of the page (appears on the first line of the inner panel)

description-id: The id of a string to be used as the description of the page (appears on the second line of the inner panel)

instruction-id: The id of a string to be used as the instruction text for the page (appears on the last line of the inner panel)

Again, title, description and instruction are available for specifying literal strings.

condition element

A page can also be wrapped with a condition element as shown below:

<condition if='#{CreateSpaceWizard.createFrom == 'scratch'}'>
   <page path='/jsp/spaces/create-space-wizard/from-scratch.jsp' 
         title-id='create_space_step2_title' 
         description-id='create_space_step2_desc' 
         instruction-id='default_instruction' />
</condition>

if: A value binding expression that must resolve to true or false

A <step> can have any number of <condition> elements. The first condition to return true is selected as the active page. A <page> without a <condition> will be treated as the default page if none of the conditions within the <step> match.

Wizard Manager

The Wizard Manager is at the center of the wizard framework.

When the Alfresco navigation handler gets a request to open a wizard it examines the current page. If it detects that it is a wizard the state of the wizard is retrieved and stored on the view stack. If the current page is not a wizard the current page is added to the view stack.

It then looks up the configuration for the wizard, if it is found the setCurrentWizard() method on WizardManager is called, passing it the configuration object for the wizard. The WizardManager then proceeds to instantiate the managed-bean, set up any parameters passed into the wizard via the setupParameters() action listener method and processes the list of steps the wizard has, including determing what the current page is.

The navigation handler then navigates to the wizard container page. The wizard container page also uses the #{WizardManager...} syntax to resolve the title, description and icon for the header area, the list of steps on the left and the page to show for the current step of the wizard.

When a user presses the next or back button the WizardManager increases or decreases the current step counter and determines from the wizard config what page should be shown.

When the container page renders the buttons the next and finish buttons disabled state is controlled via the getNextButtonDisabled() and getFinishButtonDisabled() methods. These methods can be used to enable or disable the buttons appropriately i.e. if the wizard has enough state to complete successfully.

When a 'wizard:close' request is received the navigation handler examines the view stack to see what the item at the top of the stack is. If it is a wizard the state object is retrieved from the stack and restored, the wizard container page is then navigated to. If the top of the stack is a normal page, the page is retrieved and navigated to. The exception is if the close request is overridden i.e. 'wizard:close:browse', in this scenario the view stack is emptied and the overridden outcome processed.

JSPs

The JSP referred to in the path attribute for a <page> should only contain the HTML and JSF components to define the 'body' of the page. This gets included into the wizard container page, this is defined in the <wizard-container> element in web-client-config-wizards.xml.

<wizard-container>/jsp/wizard/container.jsp</wizard-container>

An example of a simple wizard JSP is shown below, this is the page that represents the text editing step in the Create Content Wizard.

<h:inputTextarea id='textArea' rows='24' cols='112' value='#{WizardManager.bean.content}' />

That's as simple as they come!

In the more complex examples you'll see the use of a JSF component represented with <f:verbatim>. Due to an issue with the JSF specification HTML not wrapped within the verbatim component will not render at the correct time. As a result the JSP will be incorrectly formatted. You must therefore you ensure you use this component in any dialog JSPs you implement. This issue should be resolved in the next version of the JSF specification.

You'll notice in the example above the use of the #{WizardManager.bean.content} value binding expression. WizardManager is a session wide managed bean that holds the state of the wizard being viewed. 'bean' is a property of the WizardManager that exposes the managed-bean the wizard uses (as configured via the managed-bean attribute above) and 'content' is a property of that managed bean.

Using this syntax does not tie you to any particular bean, but more importantly, this means you can re-use the wizard JSP in any number of wizards.

Wizard Beans

The managed bean referenced in the managed-bean attribute must implement the IWizardBean interface. The interface definition is shown below:

public interface IWizardBean extends IDialogBean
{
   public String getNextButtonLabel();
   public String getBackButtonLabel();
   public boolean getNextButtonDisabled();
   // since 1.4
   public String next();
   public String back();
   public String getStepTitle();
   public String getStepDescription()
}

You'll notice the interface extends IDialogBean from the Dialog Framework.

There is a base class for all wizard managed beans (org.alfresco.web.bean.wizard.BaseWizardBean). The base class extends the base class used for dialogs and provides the default implementation for the IWizard interface.

As BaseWizardBean extends BaseDialogBean most of the processing is performed in exactly the same way. The only difference is the default return values for some methods.

The cancel() method returns an outcome of wizard:close, the getCancelButtonLabel() method returns 'cancel', the getFinishButtonLabel() method returns 'Finish', the getNextButtonLabel() method returns 'Next', the getBackButtonLabel() method returns 'Back' and the getNextButtonDisabled() method returns false. Finally, the default outcome returned from finish() is wizard:close.

The next() and back() methods allow the bean implementation to be notified when the user presses the Next or Back button. This can be used to perform processing as the user progresses through the wizard, for example populating lists based on selections made on previous steps. The StartWorkflowWizard bean has an example of this.

The getStepTitle() and getStepDescription() allow the bean implementation to override the step title and description provided by configuration. This in essence allows the bean to provide titles and descriptions that are not known until runtime, for example if the step title needs to include some context gathered during the wizard execution.

The only other method BaseWizardBean provides is the buildSummary() method, this is used by subclasses to help build the HTML summary table for use on the last page of all wizards.

Actions

As the IWizardBean interface extends the IDialogBean interface 3 action related methods are exposed, getActionsContext(), getActionsConfigId() and getMoreActionsConfigId().

Actions are currently not supported for wizards, so implementing these methods in a wizard will have no effect.

Future Enhancements

Although the next() and back() methods are called by the WizardManager they can not currently alter the wizard in terms of navigation. In the future the String returned from the methods will allow navigation to other named steps in the wizard. For example, if the wizard needs to skip a step due to a certain option being selected.

It will also be possible to stop the wizard from progressing to the next step if certain conditions are not met, this being determined by the execution of a yet to be determined method on the IWizardBean interface.

Furthermore, in it's current state the wizard framework only supports linear steps. Each step can have a number of choices (using the condition element) but each route through the wizard must have the same number of steps. A future release will add support for ad-hoc page flows by utlising the [Workflow] framework added in the 1.4 release.

If a wizard requires more flexibility it will be able to define a process definition. The configuration for a wizard will support a <page-flow> (or similar) element that will point to the process definition to use. The bean representing the wizard will be passed to the process instance thus allowing the name of the next step to show to be determined purely by the workflow engine. The WizardManager will then use the outcome from the task (the name of a step) to determine which page to show.