In the new IBM Multi-Channel FeaturePack For IBM Web Experience Factory v8.0 we have taken the sample Application Page builder Application Page Sample Builder and have made some updates to it and added it as a supported builder. We incorporated some of the comments that were made and some other changes based on the samples that we included to enhance the patterns that this builder supported.

This builder provides new high-level builder support for constructing various types of pages in Web Experience Factory (WEF). This builder creates a new page in a model and automates several common page design patterns that can be applied to that page. The builder's inputs are designed to present a simple, easy-to-use interface for common scenarios, but with optional access to more advanced features when you need them. This builder supports both server-side and client-side behavior exposing only the features that are available for that processing model.

The primary use cases for this builder are in situations where today you might use the Data Page builder or the Page builder, to create pages. The Application Page builder makes it easy to encapsulate the other builders and enhance them with integration with themes, model containment, page navigation and standard page buttons. These changes allow the you to make it easier to work with these pages since the page encapsulate more of the pages behavior within a single builder.

Another area that we have enhanced based on our previous samples are the model wizards we created to help you use these builders for some common patterns. These wizards are designed to ease the creation of some multiple page scenarios that the Application Page builder is good at handling.

• Model Contained Tabbed View - This wizard builds a model using the new feature pack themes and Application Page builder to create a multi-page tabbed view. The tabs are populated with models added using model containers.
• Multi-Page Form (Server or Client-side) -This wizard builds a model using the new feature pack themes and Application Page builder to create a multi-page form. This form calls the server as the pages are navigated through, performing validation. After the data is input , a confirmation page lets the user submit data to the server. On completion an acknowledgment page is displayed.
• Multi-channel Starter -This wizard builds a model using the new feature pack themes to match the user interface of models created from other multichannel wizards. It will optionally add a service consumer. Customize the model later by adding Application Page builders or other higher-level builders to create pages.

These wizards use the Application Page builder to implement some common user interface patterns with minimal user interaction allowing the user to create sophisticated page flows. They simplify the creation of these patterns but are not the only use for this builder. Another design pattern that the Application Page builder can be used to implement is the merging different views of data on a single merged page there is a good example of this in the Application Page Sample Builder and you could also use this builder to create content that you can use in the dojo container builders. In the example model I am including with this article I use the Application Page builder in combination with the Client View & Form builder to create an application that allows a user to add a new user(using the Multi-Page Form wizard to create it), View the records (using the Client View & Form) and a details and update pages(using Application Page to create the tabbed page elements). This project also uses the Sample XML File Data Service Builder to provide the data, this data service is designed for rapid prototyping of your data and service operations.

Setting up for the Sample

So to start you should create a Web Experience Factory Project and include the Client-side Application feature set. Then download the Multi- Channel feature pack and import it into your project. This will add the Application Page builder to the project along with a bunch of cool responsive data layouts. You also need to download and import the Sample XML File Data Service builder from this sample Sample XML File Data Service Builder. You then need to make sure the project is built so that the data service builder will be setup to be used. Once you have completed this your project will contain two models and a profile set that is needed for this application.



The profile set is a superset of our standard multi-channel profile set that extends that to allow a profiling of Desktop and Tablet as a single setting in addition to the Desktop, Tablet, Smartphone or Mobile. The CustomerAccountsProvider model uses the XMLFileService builder and extends that service by adding a custom service operation that modifies the service to add a new operation that will add a new customer account and generate a customer id for the customer. The ManageCustomers model was created using the Multi-Page Form wizard using the Customer Account Provider, Selecting the addnewCustomer as the Data input operation. To control the layout of these fields on these pages I added Display Manager builder placing and grouping the fields as desired.



After testing this model I decided to add a way for the user to see a list of all the customers. To do this I added a client view and form builder and switched my program flow to display the list of items(theView) and add a button on the list view to add a customer using the previously created mulit-page form.

After testing the new application flow I decided to display the detail record on individual tabs that match the field layout . To do this I needed to create the individual Application Pages for each of the tabs and then add these pages to the tabs by adding a Page Navigation builder.


To take advantage of the built in functionality of the Client View & Form builder handling the navigation to the details page and fetching the correct record to display but to display the data on separate tabbed pages. I needed to modify the savedForms_DetailsPage to not display the fields but still be navigated to with the correctly fetched data. To do this I hid all the fields that are displayed on the details page and inserted detailstab1 into the body target of the page replacing the contents of the page. The deatailstabs pages were created using the Application Page builder with the contents based on the detail customer variable that was populated by the Client View & Form builder. The Page Navigation builder added and referenced these pages which added the tabs onto the details pages, and caused the tabs to be displayed on the detail page, One other note for this part of the model was that I wanted to have the back and edit buttons available on each tab and I wanted them to invoke the same operation on each tab. To do this I used the Advanced input for the page location in the Button builder that allowed me to target mutliple pages with the exact same button definition and action, i.e. in the case of the edit button the location used was (Page detailstab1, Page detailstab2, Page detailstab3) NameSearch update_button this has the builder target all three detail tabs and place the button on the update_button target. In this way I could have fewer builders and make sure they did the exact same action.



I then decided to have the update pages also work within the tabs. This actually complicates things a bit since there are now six Application pages and tabs that will be displayed on the details page, three details and three update pages and as the user navigates through these tabs and selects the edit button they would expect the tabs to remain consistent. If I am on the Address Info tab and hit edit I stay on the Address Info tab but now in edit mode. The page navigation builders have no idea that they are related and that this is the way they should behave, the two separate Page Navigation builders don't know the relationship between the tabs. So to support this I needed to help the tab code out, I did this by creating a new Java class and adding an LJO builder to allow me to invoke these function when navigating to these tabbed pages. I also needed to make sure when the tabbed pages were initially navigated to they were reset to the tabbed state I wanted them to reflect, The navigation tabs have code that remember the state of the tabs for standard behavior. But in this case I wanted more control over the tabbed state. Using the TabHelper code that was added with the Linked Java Object builder, provided operations that allowed me to use consistent buttons for processing within the tabs and these operations were targeted within the Page Navigation builder for standard tab navigation. But when the initial details page was displayed I wanted to reset the current tab back to the Basic Info tab so the users experience was consistent. To accomplish this I needed to override the method that was created by Client View & Form to navigate to the details page and have it reset the page navigations tab state info. The easiest way to do this was to locate the method in the Application Tree right click on it and choose the Override menu.



This adds a new Method builder to the model defaulting the method information to match the existing method code and mark this method to override the existing method. You then can edit this method and add what code you need. In this case I needed some code that sets the variables that are used by the page navigation builder to retain or in this case reset the tab state.
Override the function to make sure the variable for the tab is always set to the first tab
webAppAccess.getVariables().setObject("detailsnavSelectedAction","detailsnavTargetAction0");
webAppAccess.getVariables().setObject("detailsnavSelectedPageTitle","Basic Info");

After adding these builders and methods I ended up with an application that I could display the detail pages within tabs and switch into edit mode within the tab.



When in edit mode I allow the user to switch from tab to tab, but that can be an issue. If the user has not made any modifications I allow the user to freely navigate between the tabs. But if the user has changed a field on one tab and then flips to a different tab that change would be lost since the data was never updated and sent to the server. And even if it was able to be updated and saved the user is no longer looking at the data that had been updated, which could be problematic since they might have changed something and not realized they had modified it. So we decided to handle the updates on the current tab and restrict navigation. First we need to track that the data has been changed on the form so we can do something about it when the user try's to switch the tabs. I added Attribute Setter builders for the update pages that place onchange javascript code on all the editable fields using some javascript variables and functions that were added with a Javascript builder to track when a field value is changed and reset the changed state when canceling or starting a new edit session. Next we need to add the code that tracks the tab change in this case we decided to block the change of the tab and make the user update the fields before switching tabs. The Page navigation builders place an navItemRepeat tag on the pages that the tabs are related to and so we can target them with an Attribute Setter builder using an advanced page location input in this case it s (Page updatetab1, Page updatetab2, Page updatetab3) NameSearch updatenavItem_Repeat where we target updatenavItem_Repeat in all the update pages. In this case we prepend an onclick javascript code that calls the if(!canChangeTab()) return false;(the functionwas added with the javascript builder) . Notice that we return false if we are not allowed to switch tabs this is important if your Page Navigation builder uses the Submit and invoke action method. In this case the page navigation tabs are implemented using an tag and when you have an onclick event the only way to not allow the href of the tag to be navigated to is by returning false from the onclick event, thus stopping the navigation. So the user sees this behavior if they change a value and then switch tabs without updating anything.



There are other ways to handle this you could ask the user to do the update and then continue to the selected tab or just update when the tab is navigated too but for this example we decided on this behavior.

That pretty much describes the builders and behavior that we wanted to describe related to this sample, But there are many other ways we see to use the Application Page builder and some ways that you might devise that we never envisioned.

References

Application Page Sample Builder
Sample XML File Data Service Builder