ShowTable of Contents
This article along the attached samples provide a simple introduction to using manually coded jQuery user interfaces with IBM Web Experience Factory REST Enabled data service operations from a service provider model. This is the second in a series of articles with samples describing how to leverage jQuery with Web Experience Factory.
This particular article is intended for experienced jQuery developers who are looking for information on leveraging that existing jQuery expertise with Web Experience Factory applications. As such, it does not go into where to get jQuery or where to start with jQuery development. There are many existing resources on the internet, including some mentioned in the references below, that provide such introductions to jQuery.
What about Dojo?
This community wiki article is intended to provide the reader with more information about how they may customize use of the Web Experience Factory product, via integration with 3rd party or open source user interface toolkits. No endorsement of any specific 3rd party or open source toolkit by IBM is intended by the text of this document and likewise no endorsement of Web Experience Factory by any mentioned 3rd party or open source toolkit is intended or implied. There is no guarantee implied in this article, by IBM or the author, as to the suitability or support-ability of integration with any particular 3rd party or open source user interface toolkit Any opinions expressed in this article are solely opinions of the author and do not necessarily represent the positions, strategies or opinions of IBM.
This article suggests ways to leverage particular open source software obtainable and/or reference-able on the internet from Web Experience Factory, but makes no claims as to the appropriateness of the licenses or copyrights of such open source software for any particular use. Please verify that the licenses and copyrights of all software obtained and leveraged in your applications allow such use and are acceptable to your organization prior to any such use.
Setup the Samples
- Create a Web Experience Factory project in the Eclipse based Designer. Follow the "Creating a Project" tutorial provided with the product, if this is your first introduction to the tool.
- Use the Eclipse project menu "Import" -> Web Experience Factory Archive menu action, to import the attached sample archive into your project.
- This will import two simple jQuery sample models into your project in a folder named WebContent/WEB-INF/models/samples/jquery/data_service/
- and associated HTML files into your project under WebContent/samples/jquery/data_service/
- The following steps to obtain or reference a copy of jQuery core and jQuery UI should have been done when you followed the first article in this series to create a simple page application with Web Experience Factory and jQuery, so if you're using the same project that you used for the previous article and sample you may skip down to the step specific to jQuery Validation below.
- Obtain a copy of, or URL references to a copy of, jQuery and jQuery-UI, including the CSS for jQuery-UI. This article and sample assumes that the target audience, being existing jQuery experts, will have knowledge of how/where to obtain the version of jQuery, jQuery-UI and related plugins.
- The samples were built with jQuery 1.10.x but may work as is with other recent versions of jQuery. Again, the primary point of the sample is to introduce which builders to use, if you choose to use jQuery not to recommend jQuery over any other UI mechanism or any specific version.
- As provided, the sample requires that you place a copy of jQuery core as jquery.min.js, jQuery-UI as jquery-ui.min.js and jQuery-UI CSS as jquery-ui.css in a folder called jquery within your WEF project's WebContent folder.
- Note - you should also copy the jQuery UI images subtree into this same location, if using a local copy of jquery-ui.css
- Both of the attached samples leverage a Web Experience Factory data service provider ( samples/xml_file_data_service/XmlOrdersProvider ) model (in this case leveraging an XML File based data service, for simplicity) . A more realistic application would leverage a data service provider with operations against an actual backend such as a database, web service, or 3rd party application. Please refer to the Web Experience Factory Wiki and product documentation for more information on building data service providers with Web Experience Factory.
- The first sample ( jqueryImportedJSAndPageOrdersServiceConsumer.model ) builds a list of Orders from a REST GET call against the getOrders operation, and sets up a click handler to launch the details of a given order (obtained via the getOrder operation) in a jQuery-UI "Dialog", then allowing Edit or Delete of that individual order.
Explore the Samples
- Open both the sample models and both of the HTML pages in the Eclipse based Web Experience Factory designer and explore the contents of the pages and the builder calls
- Builder calls 1 and 2 are Comments, containing a copyright and sample disclaimers
- Builder call 3 is an Action List called "main" which will be executed when the model is run via browser, which just dispatches to a page called "page1".
- Builder call 4 is an Imported Page builder which imports the associated HTML page from "samples/jquery/aSimplePage/" from the project in designer and from the deployed application WAR on the server.
- Builder calls 6, 7 and 8 add references to jQuery, jQuery-UI and jQuery-UI CSS to the page
- NOTE: As mentioned previously, Portal Pages should be pulling in jQuery core, jQuery-UI and related plugins when leveraging jQuery as portlets, each portlet should NOT try to load jQuery itself, so these last 3 builder calls should be disabled or deleted when running this or similar Web Experience Factory applications as portlets in a portal page which loads jQuery itself.
- For standalone (non-portlet) web applications, where the application itself (as opposed to a portal page) is pulling in jQuery, these 3 builder calls could be modified to point to where your organization loads jQuery and related stylesheets from.
- In the second sample only, builder call 9 adds a reference to the jQuery Validation plugin to the page. This builder call should also be disabled or deleted, if running as a portlet and the portal page is including the jQuery Validation plugin.
The setupOrderDetailsDialog queries for an element with the id "jQueryOrdersConsumerDetailsDialog" and applies a jQuery-UI Dialog widget to it, specifying various properties and defining buttons to submit the form within the dialog, delete the entry on the dialog and cancel (close) the dialog. It also applies a jQuery-UI Date Picker widget to elements with the CSS class "datepicker", specifying the date format to be used in this particular application.
The custom function "getOrders" does most of the initial work
- Find the HTML element with the id "jQueryOrdersConsumerList"
- Make a jQuery based HTTP GET call, expecting JSON back, to the REST Enabled getOrders URL
- On success (this simple sample doesn't yet address on error for these functions) call the inline anonymous function passing the JSON as the "data" argument. You may want to refactor the bulk of your success logic into a separate function, outside of the anonymous function that calls it from the getJSON results, as it can be harder to debug when working with anonymous inline functions. For demonstration purposes in this sample, it was easier to keep more of it together in this getOrders function. Within that success function it:
- Empties the HTML element that represents the list of orders (this function will also be called after a delete or future add/create of Orders)
- For each array item in the returned JSON results, it appends a list item including the ORDER_ID from the result row, and the item AMOUNT. Note, it also saves the ORDER_ID as an attribute, for use by the onclick handler (to more easily determine which row was clicked)
- NOTE - There are likely jQuery based plugins that make constructing lists easier, but for this simple introductory sample, we wanted you to see how it was taking data and creating HTML from it, to get a better idea of what's going on under the covers rather than jumping in with more jQuery black box type widgets that hide more of the work from you.
- Once the list its built is adds a "click" handler to every "li" (list element) in the orders list, which retrieves the order id from the attribute in that list item and then calls the jQuery based $.getJSON with the getOneOrder (get a single order by id) REST URL (in this case, most of the data was there from the getOrders call, but in an actual app, the get list operation may only return a subset of the data like a list of ids and names, so we wanted to show how to get a single order's details by id rather than just leverage that rows data from the original getOrders call.
The deleteOrderCloseDialog function leveraged in the above setup dialog function on click of the delete button, is also fairly simple and just leverages jQuery core to do a $.get HTTP GET call to the deleteOrder REST operation passing the specified order id as a parameter of the GET request. On completion of that call it closes the dialog and then calls getOrders again to repopulate the list, minus the deleted order.
The "updateOrderCloseDialog" function executes an HTTP GET request (via jQuery core $.get(...) to the "updateOrder" REST operation, passing the values from the form within the dialog. On completion of that update for simplicity we're just going to call getOrders again (in case your update happened to modify the contents of the overall list) and then close the dialog. If the update in your actual application does not affect the list contents, then it would be more efficient not to go through the entire getOrders process again at this point.
The main difference between the first and second models i the attached samples is that the second sets up and leverages the jQuery Validation plugin on the form within the dialog.
On click of the Submit button, it will only actually submit the form to the REST Update operation if the form is currently valid.
On click of Cancel or Delete buttons, it'll first clear the validation widget of any errors before closing the dialog so that those errors won't already exist the next time the dialog is opened for another order.
- Use "Imported Page" to import an html file from the project for use in the application.
- Use the "Style Sheet" builder to add a link reference to a stylesheet, to the application page.
- Load jQuery, jQuery-UI and any commonly used plugins in the Portal Page when building portlet applications rather than loading those artifacts from a portlet.
- Use "Service Consumer" to specify which data service provider model you want to leverage in a consumer UI model.
Exercises Left to the Reader (and/or future more detailed articles and samples)
- Error handling (eg, on failure of REST requests)
- Localization (eg, of UI labels)
- Optimization and refactoring for jQuery best practices
- Security aspects
- Unique id generation such that a single page app may be used as a portlet more than once in a single portal page without id collisions.
Since this article is targeted at developers that are already experts in some 3rd party or open source UI toolkit such as jQuery, iit is likely that you are already familiar with jQuery or the toolkit you're choosing to use instead of the rich web UI automation WEF provides out of the box. If you are not already an expert in some other UI framework, you may want to stick with what WEF provides and automated for you, based on HTML, HTMl5, CSS, Dojo etc. These references are provided solely as a reminder of some useful resources out there, and may not be a complete or accurate list of what you need to get started with and become an expert in any particular UI toolkit or framework.
- Web Experience Factory Community Blog - contains multiple blog postings describing what others have done to replace or extend the user interfaces generated out of the box by Web Experience Factory, with 3rd party toolkits