ShowTable of Contents
This article, along with the attached sample, describes how to leverage Web Experience Factory data service operation results to construct a pie chart with the open source jqPlot package. This is the fourth in a series of articles with samples describing how to leverage jQuery and jQuery based widgets with Web Experience Factory.
- Please also read and try the first second and third jQuery with Web Experience Factory articles in this series, before continuing with this one on jqPlot.
This article is intended for developers who are looking for information on leveraging a jQuery based charting package with Web Experience Factory applications.
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 a 3rd party jQuery based chart package. . No endorsement of any specific 3rd party or open source charting package or 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 and/or charting framework 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.
Set up the Sample
- 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 and jqPlot based sample models into your project in a folder named WebContent/WEB-INF/models/samples/jquery/charts/jqPlot/
- jqueryJQPlotSample.model is a simple sample model using the Script Application builder described in the previous article, to create a jqPlot pie chart from the results of a data service operation.
- jqueryImportedJSAndPagejQPlot.model is the same sample, but built with the low level builders that exist in Web Experience Factory 8.0 (prior to the new Script Application sample builder).
- and associated HTML files into your project under WebContent/samples/jquery/charts/jqPlot/
- The following steps to obtain or reference a copy of jQuery core 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 reference to a copy of, jQuery core. This article and sample assumes that the target audience, being existing jQuery experts, will have knowledge of how/where to obtain a 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 in your project's WebContent/jquery folder.
Inspect and verify the copyright and license information for jqPlot (at jqPlot.com ) and verify that one of the licenses is acceptable to your organization and if so, obtain a copy and place it under your project's WebContent/jquery folder as jquery.jqplot.min.js along the jqPlot plugins subfolder and associated files, to pick up the pie chart renderer used by this sample.
Explore the Samples
The Easy Way
jqueryJQPlotSample.model shows the simpler means of constructing the sample described in this article, with the new "Script Application" builder doing most of the work
The Hard Way
jqueryImportedJSAndPagejqPlot.model is built the hard way, leveraging low level builders available with Web Experience Factory version 8.0 (and earlier), prior to the availability of the "Script Application" builder leveraged above and described in the previous article in this series. This model is provided mainly to show how you could build the same application with existing releases of Web Experience Factory and/or if you needed more detailed builder inputs from the low level builders than are provided in the Script Application builder itself. For instance with this low level builder based model, the "Enable All Operations" input to the "Service Consumer" builder is deselected and only individual operations needed for the application are pulled into this consumer model and thus REST enabled. To do the same with the above model, a developer could provide an intermediary provider model that consumed the same data service provider, but then exposed only a smaller fixed number of operations to consumer UI models like the one above.
- Builder calls 1 and 2 are Comments, containing a copyright and disclaimers for the sample
- Builder call 3 is an Imported Page builder which imports the associated HTML page from "samples/jquery/charts/jqplot/" from the project in designer and from the deployed application WAR on the server.
- Builder calls 5 - 9, add the script references to jQuery core and jqPlot to the page. Since this sample uses jqPlot and not jquery-UI, the latter is not referenced or included in the model.
- 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 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.
- Builder call 11 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".
The custom function "getAccountsDisplayCharts" does most of the initial work
- Make a jQuery based HTTP GET call, expecting JSON back, to the REST Enabled getAccounts 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 single function. Within that success function it:
- Transforms the results from the returned array of structures (with more fields than necessary) into the format that the jqPlot chart expects (an array of arrays of values) for the data series.
- NOTE: Each jQuery based charting package this author has seen has expected a slightly different format for the data series passed to it, so you will need to investigate the documentation and samples for the charts package that you ultimately choose to use (jqPlot or other) to determine what the format of the data it expects will be.
- Once the data is in the format the charting package expects, a call is made to construct the chart, passing the data series that you previously transformed.
- Note, in the API call below, the data series is again wrapped in an [array] as it is passed as an argument, as some jqPlot charts accept multiple series to display simultaneously. For this pie chart, we're passing a single series of data (as most pie charts use) in that generic "array of series" argument.
- Transform result data from the structure received from the REST based data service, to the structure expected by a 3rd party API.
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.
- Determining the appropriate 3rd party charting package that meets your project's and organization's needs (technically, supportability and legally)
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