Special Note: Andrew Leggett, Senior Application Consultant, is the guest author of this post. Andrew Leggett can be reached at aleggett@adcaustin.com.
WebClient makes it easy to generate your Plex panel designs as HTML and Javascript so they can be used within a web browser; but with the use of custom templates, you can also present your data in a variety of ways that go beyond the standard Plex controls.
This guide will take a standard Plex grid and show you how to apply a custom control template to display the data as a pie chart. This example can be applied to any grid with numeric data columns; it requires no changes to the action diagram, and only takes a few minutes to get results.
Before
à
After
I’ll start by describing the steps that you will need to follow; then I will go into more detail to explain how this works.
1. Select a grid to work with.
For this example I’ve taken a simple EditSuit.Grid function, and I want to present the data in the ‘Market Price’ column as values in a pie chart. This is how it displays in a browser with the standard WebClient templates:
2. Create the template file.
Create a new file in your custom template folder in your Eclipse workspace and name it ‘DojoSimplePieChartGrid.ctrl’. Open the file, then copy and paste the following text. Save the file.
/(!JSInit:once)
dojo.require(“dojox.charting.Chart2D”);
dojo.require(“dojox.charting.themes.PlotKit.blue”);
dojo.require(“dojox.charting.themes.PlotKit.cyan”);
dojo.require(“dojox.charting.themes.PlotKit.green”);
dojo.require(“dojox.charting.themes.PlotKit.orange”);
dojo.require(“dojox.charting.themes.PlotKit.purple”);
dojo.require(“dojox.charting.themes.PlotKit.red”);
/(!JSInit)
/(!JSInit)
var pieSeriesData = new Array() ;
var pieChart;
function setPieChartValues()
{
var pieValueColumn = /(!Param:ValueColumn) ; // The column in the Plex grid that contains the value. Set by the ‘ValueColumn=n’ control name parameter.
/(Embed:js:cdata)
var cell = /(!This:!jsonRows) ;
for (var row=0; row<cell.length; row++)
{
pieSeriesData[row] = Number(cell[row][pieValueColumn]);
}
/(Embed)
}
function changePieColor(color)
{
pieChart.setTheme(dojox.charting.themes.PlotKit[color]);
pieChart.render();
}
/(!JSInit)
/(!JSOnLoad)
var pieRegionWidth = /(!Size:x); // The width of the Plex Grid control
var pieRegionHeight = /(!Size:y); // The height of the Plex Grid control
var pieRadius;
// Make the radius a little smaller than the shortest side
if (pieRegionWidth < pieRegionHeight)
{
pieRadius = (pieRegionWidth/2) – 10 ;
}
else
{
pieRadius = (pieRegionHeight/2) – 10 ;
}
pieChart = new dojox.charting.Chart2D(“/(!NameID)”);
pieChart.addPlot(“default”, {type: “Pie”, fontColor: “white”, labelOffset: pieRadius/2, radius: pieRadius });
setPieChartValues() ;
pieChart.addSeries(“/(!NameID)_series”, pieSeriesData);
changePieColor(“/(!Param:DefaultColor)”);
/(!JSOnLoad)
<div id=”/(!NameID)” style=”/(!DefaultCSS:nc:withPos=/(!Param:default))”></div>
<script type=”text/javascript”>
/(!ContextMenu)
</script>
3. Override the control template.
Open up your Plex panel, select the grid control, then paste the following text into the ‘Control Name’ property:
ProductPieChart:MainArea:template=DojoSimplePieChartGrid:ValueColumn=3:DefaultColor=blue:default
Note the ValueColumn=3 parameter; this refers to the grid column that will be used for the pie chart values, but be aware that this template expects the column numbers to start at zero, and Plex starts with one, so this value is actually the Plex column number – 1. In my example column 3 refers to the ‘Market Price’ column. Another parameter you can modify is the DefaultColor=blue parameter. You can use values blue, cyan, green, orange, purple or red, but they are case-sensitive so they should be entered as lower-case.
4. Generate, build and publish.
Generate your function, and build it in Eclipse. The template generator will output a diagnostic message but don’t worry about this; it is just telling you that it hasn’t attached the grid fields to the panel template.
Publish the application to the Web Server. When you access your function in the browser, you should see something like this:
Note that the pie chart has the same position and size as the original grid. Also, the buttons function as before, so the ‘Refresh’ button will reload the ‘grid’ and effectively recalculate the chart if your data has changed.
Technical details of how this example was created
This example draws a pie chart using the dojo libraries; however the process of creating new control templates can be applied to other web controls. Additional information can be found at http://www.adcaustintech.com/documents/Downloads/WebClient1-4SP1LatestPatches/TemplateCmds.pdf.
1. Locate some suitable Javascript code
The first step is to start with some Javascript that does what you require. The dojo toolkit provides a large collection of Javascript and Ajax controls that can be used to enhance your web application. The Dojo Campus feature explorer is a great place to start, as it shows you a working example of each feature, along with sample HTML and Javascript to make it work. This can be located at http://dojocampus.org/explorer/. The Javascript used in the template for this example was adapted from the sample at: http://dojocampus.org/explorer/#Dojox_Charting_2D_Simple%20Pie%20Chart.
2. Create the Control Template
To override the way that your controls will display in the browser, you will need to create a control template with the suffix ‘.ctrl’. For this example, I created a template named ‘DojoSimplePieChartGrid.ctrl’. You will need to define any dojo libraries that will be used with the dojo.require() method, and these should be define in the /(!JSInit) attach point. As a general rule; the Javascript functions (setPieChartValues()and changePieColor(color)) can be attached to the /(!JSInit) attach point, and the Javascript that will be executed when the page loads can be attached to the /(!JSOnLoad) attach point. Finally, you will need to define a visible HTML element that will be associated with the chart. In this example I used a <div> element.
3. Modify the template to allow Plex runtime values.
WebClient can incorporate values from the Plex panel design and runtime environment into the rendered page. If you look at the template, you can see how these are defined.
- Panel Properties
The control takes the position and size from the Plex panel design, and the pie chart needs to fit within that area on the page. To determine the radius of the pie chart, it needs to be less than the shortest side of the control area, so I need to include the control height and width in the Javascript. This was done with the /(!Size:x) and /(!Size:y) replacement markers. At runtime these will be replaced by the width and height property values from the panel design.
- Control Name parameters
The color and data column are required by this pie chart template. As there are no suitable panel properties for these values, a defined parameter is required. These parameters are included in the template by adding the /(!Param:ValueColumn) and /(!Param:DefaultColor) replacement markers, and the values are defined in the control name as ValueColumn=3:DefaultColor=blue.
- Grid values
The Javascript in this example reads the data in the grid and adds it to the series data required by the pie chart. The grid data is available at runtime in the json format, and can be retrieved with the replacement marker
/(!This:!jsonRows).
This data is presented in the format:
[["1","Widget","It's a Widget","100.0","84.0"],
["2","Large Widget","It's a Widget, only bigger","150.0","120.0"],
["3","Small Widget","The smallest Widget you can buy","99.0","89.0"],
["4","Another Widget","It's another Widget","101.0","70.0"],
["5","new","new product","230.0","200.0"]]
This is essentially a two-dimensional array of rows and columns. This array can be processed by Javascript.
4. Override the control template.
Finally, to be able to use the template, the WebClient template builder takes direction from the control name property in the panel design. We added the directive:
ProductPieChart:MainArea:template=DojoSimplePieChartGrid:ValueColumn=3:DefaultColor=blue:default
The parameters are separated by colons; the values can be interpreted as:
ProductPieChart – The first parameter is always the control name, this will identify the control in the template, and is referred to in the template as /(!NameID).
MainArea – The second parameter always refers to the attach point in the root or page template where the control will be rendered. ‘MainArea’ is the default location.
template=DojoSimplePieChartGrid – This parameter directs the template builder to use the defined template when generating this control.
ValueColumn=3 – This value is referenced in the template as /(!Param:ValueColumn), so at runtime this will generate text ‘3’.
DefaultColor=blue – This value is referenced in the template as /(!Param:DefaultColor), so at runtime this will generate text ‘blue’.
default – If the ‘default’ parameter is included, the WebClient will generate the size and position based on the values in the panel properties for this control.
