In Part One I covered the generic code elements required on the XPage before we get as far as creating the data for the chart and the chart itself. Now we get into the interesting stuff.

Creating a Series

The first part of the chart is the series. What I’m looking to produce is an array of JSON objects as a variable, one per portion of the pie, holding the value along with all the other parameters I want to use for my pie. If you view the source of Chart 1, you will see the full variable. The output is in this format:

var series1=[{y: 3, text: “ABC DEVELOPMENT”,legend: “ABC DEVELOPMENT”, tooltip: “ABC DEVELOPMENT (3)”},{y: 5, text: “ABC SUPPORT”,legend: “ABC SUPPORT”, tooltip: “ABC SUPPORT (5)”}];

I’m producing my output in two steps. The first step is a Computed Field control called seriesA to create a list of JSON objects in a string. The second step is a Computed Field control that creates client-side javascript on the XPage to add the “var series=1[“ and “]”. This makes it easier to read for those trying to follow the tutorial, but in practice I think it would also make it easier for a developer supporting the XPage.

The code for Computed Field seriesA is:


This creates a NotesViewNavigator and uses a while loop to pull content from the view entries to create a comma-delimited list of JSON objects, each corresponding to one portion of the pie. So the first one will be:

{y: 3, text: “ABC DEVELOPMENT”,legend: “ABC DEVELOPMENT”, tooltip: “ABC DEVELOPMENT (3)”},

Within the while loop there is an if statement ensuring I’m only creating a JSON object if the value I’m pulling in – viewEnt.getColumnValues()[5] – is greater than zero. If the value is zero, then it would not show in the pie but would show in the legend, which I don’t want.

Because the output adds a comma after each JSON object, the final line removes that final comma from the end of the string.

It doesn’t matter whether you loop through NotesViewEntries or use NotesViewDocuments or use an @DbLookup or @DbColumn to pull in JSON objects from a column. All these would allow you to get a handle on the documents, and so compose the JSON output needed.

Each JSON object has a number of parameters, as shown in the screen shot. Using an HTML table store only allows the “y” parameter to be set, which is rather limiting. Using JSON objects offers much greater flexibility. A custom label can be added, which is shown against that portion of the pie. The label parameter is included here only for information of what can be done. In my sample pie chart I suppress it by setting the “labels” parameter of the pie chart itself to false. I have done that because I could not generate short labels and the pie has a lot of portions. If you change the labels parameter on the pie chart to true in the sample, you will see what I mean. The colour can be defined – by default the colours are handled by the theme and it could be tricky to define colours in the series unless you know the number of objects to be put into the series. As with any colours, this can accept a colour name, a hex value or an rgb value. A legend label for this portion of the pie can be defined. If this parameter is omitted, the text parameter is used instead on the legend. And a tooltip can be defined. This will be shown when you hover on that portion of the pie. In this example of a pie chart of open calls, I’m also including the number of open calls in the tooltip.

So this creates the text list of JSON objects which will be put into series1. For step 2 I use a Computed Field control that writes client-side javascript onto the XPage. If you’ve never done this before, it’s the same as putting pass-thru HTML on a web form.

Client-Side Javascript

The important step is that Content Type is set to HTML (this is the escape=”false”). The output of the Computed Field seriesA just had the JSON objects as a string, so the javascript needs to wrap it in “[]” to convert the string to an array of objects. And the whole thing is stored in javascript variable series1. I’m also adding javascript variables for two other series that I’ll be using in the column and bar charts. I will cover those in the next part of the tutorial.

You will notice this doesn’t use repeat controls. In theory, it should be possible to do that, wrapping the repeat within Computed Text controls opening and closing the client-side javascript. If people feel that would be useful, I will add a version of the pie chart using a repeat control for the series.

Generating the Pie Chart

Chris Connor has shown how to create a pie chart via HTML markup. In this example I will be creating the pie chart via javascript and adding it via the XSP.addOnLoad function. The first part of generating the pie chart is to add onto the XPage two panels in which the pie chart and its legend will be inserted via javascript.

Chart and Legend Panels

The rest of the code is put in an Output Script control (xp:ScriptBlock). This comprises a variable called makeCharts that contains a function. The final line of the code calls “XSP.addOnLoad(makeCharts)”. If you’ve not used this before, the addOnLoad function is in the XSPClientDojo.js file which can be found in your Datadominojsdojo-1.3.2ibmxspwidgetlayout folder. As its name suggests this is an XPages function that runs javascript code on load of the XPage, so will run the makeCharts function.

makeCharts part 1

The first part of the makeCharts function (shown above) creates a variable for the chart. In line 115 the “#{id:simplechart}” runs server-side javascript to calculate the full id of the panel where we want to place the chart. I could have used a div (not xp:div) with a simple id. But using an xp:panel with an id of “simplechart” and “#{id:simplechart}” means that if the code is used in a custom control repeated multiple times on an XPage, we never get a conflict for the id. The next line sets the theme for the chart. Line 125 calls the addPlot function which defines the chart type, in this case “Pie”, and all parameters. The first parameter is the name, usually “default” unless you have more than one plot type on the chart. (I haven’t experimented with this, so I’m not sure how to add a series to a particular plot type, but you will notice that with the animations we also define the name the animation relates to.)

As you can see in the screenshot above, I’ve included the parameters available for the pie chart. You will see I have set the labels parameter to false. This means that even though I have defined the text parameter in my series, it is ignored and no labels are produced. As I mentioned above, this can be useful if your labels are quite lengthy or you have a lot of portions on your pie. Font and fontColor then relate to the font settings of the labels. For those who have not used it before, fontColor gives an example of how to set an rgb value for a colour in HTML. The final numbered line adds the series. Obviously for the pie chart there is only one series defined.

After defining the chart type and adding the series, I then add the animations. You should only use one of Magnify, MoveSlice and Shake because the animation is very similar: they all animate the slice selected. Magnify and MoveSlice are very similar, both have parameters for duration, the amount to expand the slice by (“scale”) and the amount to move the slice from the centre (“shift”). MoveSlice has an additional parameter to define the style for animation, by default dojo.fx.easing.backOut. For alternatives see dojo.fx.easing. (The javascript files installed as part of the Notes Client and Domino installs are compressed, but if you want a more readable version of dojo files I would recommend Dojomino – the new Filter option in Designer 8.5 makes this even more usable – or downloading the files from the dojo site.) Shake allows you define the animation style with the easing parameter, but also allows you to define the extent to which the pie portion is shaken in axes x and y.

The next animation is the Highlight animation (line 149). Again this has a duration parameter but also a highlight colour. If omitted the default is the negative of the current colour, but you can specify a specific highlight colour, as I have.

The final animation is to generate the tooltip. You need to ensure dojoTheme is set to True on the XPage or custom control for tooltips to show. The tooltip displays the tooltip parameter of the series, if available, otherwise the text parameter. You can override the text parameter, and I will show that in action in the next part when I show the bar and column charts, because those charts only accept a series of numbers and not a series of objects.

Render and Legend

The only thing remaining to create the chart is the call the render function.

As with the chart, the next step is to add the legend. Again this is defined as a variable containing the parameters and the panel id where we want to place the legend. The legend has two parameters, the first of which defines the chart the legend applies to. For a pie chart this creates a legend entry for each JSON object in the series, using for each object in the series either the legend parameter, if it exists, or the text parameter. The second parameter defines the display format, horizontal as true or false (the default is true if the parameter is omitted). If you look at the dojoxchartingwidgetLegend.js javascript file you will see the legend is created as an HTML table. As a result the default option of horizontal may work well if you have only a small number of elements in your legend, otherwise you will want to set horizontal to false, as I have. The challenge with creating your own legend outside of dojo is getting the icon that the legend title relates to from the _makeIcon function. For a pie chart, if you’re specifying the colours, this could be done more easily. Otherwise it would be easier to create your own extension of dojoxchartingwidgetLegend.js (e.g. amending the refresh function to start a new row every n entries). This could easily be manually copied onto a Domino server, the challenge would be how to deploy it from an nsf via an agent.

You can see the finished pie chart here, and download the sample database here. In the next part I’ll move onto creating the bar and column charts and the peculiarities affecting them.


6 thoughts on “Dojox Charting Tutorial – Part Two: Creating Series and Generating the Pie Chart”

  1. we have a survey application which now has only ‘reporting functiondality’ to spreadsheets (excel). I hope these blog posts of yours may contribute to a more dynamic reporting method…

  2. NotesApprentice

    I’m using the scriptBlock as you have, but I am getting the error message “The markup tag xp:scriptBlock can only contain controls and mark up tags”. Any idea what I am doing wrong? I am only using code for one chart, and not the rest. Here is my code:

    <xp.scriptBlock id= “scriptBlock1”>

    <xp:this.value><![CDATA[makeCharts = function(){

    var chart1 = new dojox.charting.Chart2D(“#{id:myPie}”);


    chart1.addPlot(“default”, {type: “Pie”, radius: 150, fontColor: “rgb(255, 0, 0)”, labels: false});

    chart1.addSeries(“Series 1”, series1);


    var legendTwo = new dojox.charting.widget.Legend({

    chart: chart1, horizontal: false






  3. NotesApprentice

    I also have another question. How does the charting code know where to get series 1 from? Is it better to put script1 into a viewScope variable, and then from inside the makeChart function, call the viewScope variable? I managed to work past my last issue (getting an error message from the scriptBlock) I have no idea what was wrong, but it is fixed now. I am still not getting any chart to show. I believe that it might be because series1 is not called by a getcomponent().getValue() function. What do you think?

  4. series1 is a Client-Side Javascript variable, see the section on Creating The Series or the Dojo Toolkit examples. Have a look at the sample application. Combined with the tutorials here and on Dojo Toolkit website that should give you enough information to understand how they work.

    1. Thanks for your comment. The rest of the line is just combining literal strings and column values, so nothing overly complex. The full line is:

      output += "{y: " + viewEnt.getColumnValues()[5] + ", text: "" + viewEnt.getColumnValues()[1] + "",legend: "" + viewEnt.getColumnValues()[1] + "", tooltip: "" + viewEnt.getColumnValues()[1] + " (" + viewEnt.getColumnValues()[5] + ")"},";

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.