by Adam Kewley
Over the last couple of years I’ve had the need to create a Dojo Form Dialog in WEF that interacts with the end user. The dialog is expected to update itself without refreshing the entire page. By utilizing custom refresh features within WEF we can construct such a dialog that will behave more like a popup window. The sample can be downloaded here.
For this sample we had the following requirements:
- Create a wizard-like dialog that included multiple steps that a user could follow to complete a form.
- Allow the user to navigate back and forth between the steps.
- Use an existing dialog and avoid full page refreshes.
- Utilize a small framework that could be utilized in real-world applications.
We’ll first dissect the model by looking at the dialog itself. Out of the box WEF ships with a robust Dojo Form Dialog builder that automates the generation of input forms. The builder also includes OK / Cancel buttons to process such a dialog. This is suitable for a good deal of applications, but you’ll need to build your own if you wish to fully customize the dialog itself. For this reason we will instead opt to write our own Dialog in HTML. This turns out to be a pretty easy undertaking provided the developer has a basic understanding of Dojo.
The first requirement is to add a Dojo Enable builder. This builder will tell a given Page in WEF to import Dojo artifacts. The “Requires Package List” input will contain all of the dojo imports that are needed for the particular page. For the moment this input includes the dijit.Dialog feature.
The next portion is the main model page. The page1 page contains the content for the dialog and the navigational pieces. You’ll notice that the page html is split into two main sections. The main form for the model is named “mainForm”. This is where your general model or portlet content would reside. It’s important to note that the html for the dojo dialog is external to the main form. Our field experience has lead us to determine that the best location for a custom dojo dialog is outside of a form tag within a portlet. For that reason I’ve always put custom Dojo dialogs external to the main form. Each dojo dialog in a portlet or model should reside outside of the main form and include its own form if the dialog is interactive. For message dialogs you can skip the additional form.
In addition to the form there are a couple of other elements that should be noted. The DialogContent span tag is a wrapping tag that encapsulates a couple of additional span tags. This tag is targeted by the navigation buttons (back,next, finish) in the Post-Action behavior portion of the builder. More on this later..
The insertedPage tag is where the main contents for the dialog will appear. The inserted page builder is using a variable to determine which page to insert into the dialog. This variable is driven by the wizard framework in the LJO attached to the model. The dialog itself is contained within a Div wrapper with a given ID and dojoType. The next piece of our demo is the navigation framework. The framework is a collection of builders, java code and an Xml variable which handles navigation and validation within the form itself. The navigation variable contains the individual wizard steps using the following xml syntax:
This variable can be upgraded to include additional features necessary for building a more complex dialog as well. The currentStep variable within the model contains a copy of the currently selected step element that is in use. The navigation builders rely on this variable for the step instance data.
The next builder of interest is the Inserted Page builder. This builder inserts an arbitrary page into the the dialog portion of the main page. This is driven by the Page node of the currentStep variable.
Each step has an individual page, UI and datapage variable. It’s important to note that while you could probably get away with using a single xml datapage variable for all of the steps, it was far easier to divide each wizard step up into individual xml variables. This prevented us from having to use multiple datapage builders to hide the majority of the input form and only show the portions needed for a particular wizard step. At the end of the dialog process the xml variables are combined together into a target variable. The information is presented in a summary datapage for viewing.
The heart of the Dialog magic lies within the navigation builders. Smart Refresh is the default rendering behavior for WEF. This feature dynamically updates the page for you without incurring a full browser page reload. Unfortunately if we used this default feature, the dialog would close every time we processed a back / next step within the dialog. WEF provides additional mechanisms for handling the post-action behavior of html action builders (button, link, image button etc..)
We will be using the custom refresh location feature, that is provided by WEF, to get around the page refresh issue. This can be found in the Post Action Behavior section.
In the figure above you can see we are setting the post-action behavior to Refresh specified page location after running action. This tells WEF to only update a small portion of the page instead of the majority of the page. The DialogContent tag is a separate span tag that wraps the inserted page within the Dojo Dialog itself. You’ll also notice that this works cross forms. The button lies in the mainForm and the result is updating content within a separate form. The refresh specified page location option is a pretty nifty feature.
The finish button simply utilizes the default smart refresh behavior since we may need to update the main page after exiting the dialog.
The next portion is the DojoDialogLJO class. This class contains the logic for switching dialog steps as well as handling validation and processing of inputs.
The back / next / finish buttons require additional visibility logic depending on the wizard step. This is defined in the navigational XML variable.
- Hide the contents inside of the dialog. For slow dialogs this prevents the user from seeing the previous state (if one exists) before the dialog itself returns to a reset state.
- Displays the dialog before the request is sent to the server
- Sends a request to the server to reset the dialog visually and re-load step1 inside the dialog
- Once the request completes the non-hidden step is rendered in the dialog and shown to the user.
For simplicity sake we chose to show the dialog before the request is sent to the server. While it is possible to get the dialog to show only after the page is loaded, it takes a bit more effort and would further complicate the demo. This route was chosen for a clean and simple transition.
In demonstration you’ll notice that the dialog can navigate forward and backwards through the wizard, as well as display datapage validation errors on the first step. The navigational behavior is handled by the processStep methods within the LJO. On the summary page the separate xml variables from the datapage input forms are combined into a summary xml variable. Additional java logic is required due to how the inputs are rendered on the page.
This section includes a few notes, caveats, customization suggestions and other bits that may be useful to the end user.
#1 As mentioned before, the dialog does not need to be a multi-stepped dialog with a wizard framework. You can simply use a single button and re-process the current page if you’re looking for a simple datapage form with validation on it.
#6 It is easily possible to update the main page once the dialog closes. The finish button will re-render the main page, so any updated content should be reflected in the current page.
About the Author: Adam Kewley has been working with Web Experience Factory (WEF) for 12 years. He began his career working with the WEF development team itself. Over time he moved from software QA to Development, L3 support lead (assisting the IBM customer support team), and finally on to consulting. Adam is currently employed at Davalen as the WEF lead. He is a resident of southern New Hampshire.
This article is from our monthly resource e-Newsletter. Did you miss it in your inbox? Visit our eNewsletter archives for past editions or if you want to receive our monthly newsletter automatically, simply write to Ruth O’Keefe and request to be added to our E-Newsletter list. You can also view the Master Series Archives.