Dojo Charting in XPages

Andrew Champion

Speaker Introduction
Andrew Champion
Based in the North of UK
Certified Lotus Notes Developer since 1997
Developing XPages Applications since 2009
Lead Developer, FoCul Ltd. www.focul.net
Solutions for Engineering & Manufacturing Industries
Blogs at www.andrewchampion.me.uk
But not nearly enough

Session Introduction
You are familiar with
Notes and Domino
Developing and deploying XPages applications
Server Side and Client Side JavaScript in XPages

Creating Dojo Charts in XPages

Build on great work by
Paul Withers
http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Dojox_Charting_for_XPages
http://www.intec.co.uk/blog/

So, What Do We Hope To Achieve?

Why are we here today?
We are going to learn how to plug great looking charts into XPages applications
Plenty of complete working code
Step by step demos working through a sample application
Why are we using the dojo framework?

Customers like charts and managers love dashboards

Lets give them what they want!

The demo application

http://www.andrewchampion.me.uk/downloads/dojo-charting/

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

Dojo and XPages

Dojo is an open source JavaScript framework

Collection of cross-browser compatible functions and widgets
Designed to aid rapid development of dynamic web interfaces
Intrinsically linked with the XPages runtime
Much of the standard XPages functionality extends the standard Dojo Toolkit
Extension library Dojo controls make it easier to implement some more frequently used modules

XPages Version

Dojo Version

Domino 8.5.0 (server only)

Dojo 1.1.1

Notes/Domino 8.5.1

Dojo 1.3.2

Notes/Domino 8.5.2

Dojo 1.4.1

Notes/Domino 8.5.3

Dojo 1.6.1

Notes / Domino 9 Social Edition

Dojo 1.8.1

Current Dojo version 1.8.3

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

dojox.charting Library
The Dojo Toolkit is divided into several main packages
dojo: The core covers a wide range of funtionality such as AJAX and DOM manipulation, events
and internationalisation libraries.
dijit: Built fully on top of the dojo core and contains an extensive set of user interface controls
(widgets) such as text boxes and modal dialogs
dojox: Historically an area for development of additional dojo functionality. Built upon both the
dojo core and dijit packages.
Modules and sub-packages have a status of Mature, Experimental, Maintained, Deprecated
or Abandoned
dojox.charting is Mature
util: Various tools that support the rest of the toolkit such as being able to build, test and
document code.

dojox.charting module provides a way to quickly and easily add great looking
charts to web pages. All that is needed is...
A copy of dojo (provided by XPages)
Some JavaScript skills (provided by you!)

dojox.charting Library
Then you can create charts such as these* ....

*not today(!) were starting out with some simple examples to get you started.

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

Our Sample Application

Were going to use a sample application to provide the data for our dojo charts
Football Widgets R Us
Set up by a group of famous ex players who have developed training products called Football
Widgets that are sold to the leading European clubs
8 Products, 10 Sales Reps, 24 Customers
10,000 orders in the last 12 months

There is a very demanding Managing Director who wants to visually inspect the
number of orders, the best selling products and the performance of the sales
reps.

The Managing Director

A Request From the Managing Director

I want to easily see which of my

products is selling the best.
I WANT a pie chart.

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

What are the Steps Involved in Creating a Dojo Chart?

1. Set the dojoParseOnLoad and dojoTheme properties of your XPage (or

Custom Control) to true
2. Include the required dojo module(s) on your XPage (or Custom Control)
3. Create a <xp:div> (or <xp:panel>) placeholder for the chart
4. Make the chart data series available to client side JavaScript
5. Create a the chart using client side JavaScript
Charts can be created programmaticaly or declaritively
This session is focusing on the programmatic method

A First Simple Pie Chart Step 1 of 5

1. Set the dojoParseOnLoad and dojoTheme properties of your XPage (or
Custom Control) to true
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" dojoTheme="true" dojoParseOnLoad="true">

A First Simple Pie Chart Step 2 of 5

Include the required dojo module in your XPage (or Custom Control)
<xp:this.resources>
<xp:dojoModule name="dojox.charting.Chart2D"></xp:dojoModule>
</xp:this.resources>

A First Simple Pie Chart Step 3 of 5

Create a <xp:div> (or <xp:panel>) placeholder for the chart
<xp:div id="pieChart" style="width: 450px; height: 450px;"></xp:div>
Remember the id of the div or panel component we will need to reference it at step 5

A First Simple Pie Chart Step 4 of 5

Make the chart data series available to client side JavaScript
The data needs to be in a JavaScript array of JSON values
{y: 1978, text: "Blue Widget"}
{y: 1669, text: "Brown Widget"}
{y: 2017, text: "Green Widget"}
{y: 334, text: "Orange Widget"}
{y: 1051, text: "Pink Widget"}
{y: 1545, text: "Purple Widget"}
{y: 339, text: "Red Widget"}
{y: 1067, text: "Yellow Widget"}
In our example we will use Server Side JavaScript in a <xp:scriptBlock> to extract the data from a
Notes view and generate a Client Side JavaScript variable in the above format.

A First Simple Pie Chart Step 5 of 5

1. Create a the chart using client side JavaScript
makeCharts = function() {
//Create a new 2D Chart
var pieChart = new dojox.charting.Chart2D("#{id:pieChart}");

// Add the only/default plot for the pie chart

pieChart.addPlot("default", {type: "Pie, radius: 150, fontColor: "black", labelOffset: "-40"});
// Add the data series
pieChart.addSeries("Number of Orders", jsonData);
// Render the chart!
pieChart.render();

};
XSP.addOnLoad(makeCharts);

Demo Time

Thats all very interesting but I just

want to see MY pie chart!

A First Simple Pie Chart Re-cap

Set the dojoParseOnLoad and dojoTheme properties of your XPage (or Custom
Control) to true
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" dojoTheme="true" dojoParseOnLoad="true">

Add the required dojo module(s)

<xp:this.resources>
<xp:dojoModule name="dojox.charting.Chart2D"></xp:dojoModule>
<xp:dojoModule name="dojox.charting.widget.Legend"></xp:dojoModule>
<xp:dojoModule name="dojox.charting.action2d.Tooltip"></xp:dojoModule>
<xp:dojoModule name="dojox.charting.action2d.Highlight"></xp:dojoModule>
<xp:dojoModule name="dojox.charting.action2d.MoveSlice"></xp:dojoModule>
</xp:this.resources>

Create a <xp:div> (or <xp:panel>) placeholder for the chart

<xp:div id="pieChart" style="width: 450px; height: 450px;"></xp:div>

A First Simple Pie Chart Re-cap

Provide a JavaScript array of JSON data in the format
{y: 1978, text: "Blue Widget",legend: "Blue Widget", tooltip: "Blue Widget (1978)"}
{y: 1669, text: "Brown Widget",legend: "Brown Widget", tooltip: "Brown Widget (1669)"}
{y: 2017, text: "Green Widget",legend: "Green Widget", tooltip: "Green Widget (2017)"}
{y: 334, text: "Orange Widget",legend: "Orange Widget", tooltip: "Orange Widget (334)"}
{y: 1051, text: "Pink Widget",legend: "Pink Widget", tooltip: "Pink Widget (1051)"}
{y: 1545, text: "Purple Widget",legend: "Purple Widget", tooltip: "Purple Widget (1545)"}
{y: 339, text: "Red Widget",legend: "Red Widget", tooltip: "Red Widget (339)"}
{y: 1067, text: "Yellow Widget",legend: "Yellow Widget", tooltip: "Yellow Widget (1067)"}

A First Simple Pie Chart Re-cap

makeCharts = function() {
var pieChart = new dojox.charting.Chart2D("#{id:pieChart}");

//Create the chart

pieChart.addPlot("default", {type: "Pie", radius: 150, fontColor: "black", labels: false}); //Add the plot
pieChart.addSeries("Number of Orders", jsonData); //Add the data series

var chartTooltip = new dc.action2d.Tooltip(pieChart, "default"); //Add a tooltip

var chartHighlight = new dc.action2d.Highlight(pieChart, "default"); //Add animation
var chartMoveSlice = new dojox.charting.action2d.MoveSlice(pieChart, "default", {scale: 1.2, shift: 20});
dojo.require("dojox.charting.themes." + theme); //Set the theme
var dojoTheme = dojo.getObject("dojox.charting.themes." + theme);

pieChart.setTheme(dojoTheme);
pieChart.render();

//Render the chart

var pieChartLegend = new dojox.charting.widget.Legend({chart: pieChart, horizontal: false},"#{id:chartLegend}");

};
XSP.addOnLoad(makeCharts);

//Add a legend

Another Request From The Managing Director

Now I want a bar chart to show how my

Sales Reps are performing

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

A Simple Bar Chart

We follow the same steps as creating the pie chart BUT...
There is a slight difference in how we provide the data for a bar chart
We need to provide an array of data values
[71,349,1982,973,317,1003,1996,1027,1981,301]
And an array of JSON objects for the labels and tooltips
{value: 1, text: "Cristiano Ronaldo", tooltip: "71"}
{value: 2, text: "Diego Maradona", tooltip: "349"}
{value: 3, text: "Eusebio", tooltip: "1982"}
{value: 4, text: "Franz Beckenbauer", tooltip: "973"}
{value: 5, text: "George Best", tooltip: "317"}
{value: 6, text: "Johann Cruyff", tooltip: "1003"}
{value: 7, text: "Lionel Messi", tooltip: "1996"}
{value: 8, text: "Michael Platini", tooltip: "1027"}
{value: 9, text: "Pele", tooltip: "1981"}
{value: 10, text: "Zinedine Zidane", tooltip: "301"}

Demo Time

Just get on with it!

AND I want to be able to click on a bar
and see the underlying data.

A First Simple Bar Chart Re-cap

Follow the same steps as creating a pie chart
Provide the data in a slightly different format an array for the data and an
array for the labels
Adding an onClick event to our chart using connectToPlot
barChart.connectToPlot("default", this,
function(evt) {
if(evt.type != 'onclick') {return;}
window.open("OrdersBySalesRep.xsp?filter=" +
encodeURIComponent(jsonLabels[evt.index].text),"_self");
}
);

Demo Time

Thats not bad but NOW I want to see

how many of each product my Sales
Reps have sold

Stacked Bar and Area Chart Re-cap

Stacked Bar Chart
Follow the same steps as creating a bar chart
Provide an data array for each bar (8 in our example)
Changed our data arrays from a simple value array to an array of JSON objects for the Tooltips

Area Chart
Can be created almost identically to a bar chart some different settings such as markers

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

Creating a Dashboard
Wouldnt it be nice if we could set up a dashboard page with different charts?
Create a re-usable custom control
Custom properties for
Chart type
Data series and label array(s)
Boolean values to indicate if we want a legend, tooltip or animation
Click through Xpage to underlying data

There is an openNTF project YouAtNotes xCharting by Julian Buss

http://www.openntf.org/internal/home.nsf/project.xsp?action=openDocument&name=You
AtNotes%20xCharting
http://www.juliusbuss.de/

Creating a Dashboard with a Re-usable Custom Control

Chart Custom
Control

Chart Custom
Control

Dashboard XPage

Chart Custom
Control

Each incidence of the Chart

Custom Control has custom
properties set to specify
Chart type
Data series
Data labels
Include Tooltips etc

Creating a Dashboard with a Re-usable Custom Control

Demo Time

Now I want to look at a

lot of charts on one page.
I WANT A DASHBOARD

Dashboard Data Persistence with a Managed Bean

Examples so far work fine but can be a little slow
Especially the stacked bar charts where we are traversing the view several times

Use java classes to extract the data and store this in a managed bean

Depending on use case the bean can be bound to application or session scope
Data does not have to be recalculated every time the dashboard is opened
Methods to refresh the data and rebuild the dashboard
Other useful methods will be to sort the data (largest first) and return a subset , e.g. top 10

Lets have a quick look at a demo from a real world application

So, What Have We Done Today?

Created our first simple pie chart using the 5 step process

1. Set up the XPage for dojo with dojoParseOnLoad = true dojoTheme = true
2. Include the required dojo modules
3. Add an empty div container for the chart
4. Provide the data for the chart in an array of JSON values (we used SSJS)
5. Create the chart using CSJS

Enhanced the chart with

A legend, tooltips, highlighting and moving the pie slice

Created a simple bar chart

With a click through event to the underlying data

Created stacked bar chart with multiple data series

Built a dashboard using a reusable chart custom control
Looked at how we can take this a step further using a managed bean to persist
our data
With methods to rebuild, sort the data and return a subset of data

Agenda

Overview of Dojo and XPages

Introduction to the dojox.charting Library
An Overview of Our Sample Application
A First Simple Example Pie Chart

Specifying the data series

Changing the theme
Adding legends
Tooltips and animation

Further Example Charts

Example bar, stacked bar and area charts
Click through event to the underlying data

Creating a Dashboard
With a reusable custom control

Q&A

Useful Resources
Dojo website
http://dojotoolkit.org/
With a very good reference guide

IBM Notes and Domino Application development wiki

http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Dojox_Charting_for_XPages
By Paul Withers and includes links to a series of dojo charting related articles

OpenNTF YouAtNotes xCharting

http://www.openntf.org/internal/home.nsf/project.xsp?action=openDocument&name=YouAtNo
tes%20xCharting
By Julian Buss and includes a demo site

My (relatively new) blog and demo application download

http://www.andrewchampion.me.uk
http://www.andrewchampion.me.uk/downloads/dojo-charting/
http://www.focul.net