Sending Dynamic Data to PopChart Server

PopChart Server User Guide 4.0.5

Sending Data with PopChart Script

PopChart Script, commonly referred to as PCScript, is a scripting language for PopChart Server. It provides you with an object-oriented interface for sending data and formatting options to PopChart Server.

Introduction to PCScript

In PCScript, each item in a PopChart is considered to be a separate object. There are four types of objects: graphs, text boxes, legends, and bitmaps. In this section, we will only discuss sending data to the graph object.

Command Syntax

Every PCScript command that you send to PopChart Server will be in the following format:

object.method(paramater1,parameter2,...)

Graph objects will usually be named graph, although, especially if you have multiple graphs in the same PopChart, this is not always the case (see "What is my Object Named?" in Chapter 6). In this section, however, we will assume that your graph object is named graph.

Since we are dealing only with sending data, the only methods that you will be concerned with are the SetCategories() and SetSeries() methods.

For more specific information about the PCScript command format, you should refer to "PCScript Command Format" in Chapter 5 of the PopChart Server Reference manual.

Command Strings

When you send PCScript commands to PopChart Server, you will send them via a PCScript command string. A PCScript command string is a string that contains all of the PCScript commands in the order that they are to be executed.

The commands can run together, so that nothing is separating them from each other, or they can be separated by white space. They should not be separated by a semi-colon or any other character.

Example 6.4 and Example 6.5 demonstrate two valid PCScript command strings, both of which contain the same commands.

In the next subsection, you will learn how to build a command string suitable for sending data to PopChart Server. After that, you will learn how to send that command string.

Specifying Your Data

To specify your data in PCScript, you will use two PCScript methods, SetCategories() and SetSeries().

Naming Categories

You will use SetCategories() only once—to specify your data categories (some graphs, such as X-Y and Time Plot graphs, do not use categories, so you would not use this method for those graphs). Be sure that you call the SetCategories() method before you call the SetSeries() method.

The syntax for the SetCategories() method is as follows:

graph.SetCategories(categoryname; categoryname; ...)

Each category name should be listed in order, separated by a semi-colon. In Table 6.1, our categories were named Arrivals, Departures, Unused, and Out of Commission. To name these categories in PCScript, you would use the following command.

graph.SetCategories(Arrivals; Departures; Unused; Out of Commission)

Note: Strings in PCScript do not have quotation marks around them. Because of this, if you have a comma or semi-colon in your category or series names, PopChart Server will not be able to interpret your string correctly. You can get around this problem by changing the parameter or item delimiters using the Main. ParamDelimiter or Main. ItemDelimiter command.

Specifying a Series of Data

Unless you only have one series of data, you will call the SetSeries() method multiple times—once for each series of data. The syntax for the SetSeries() method is as follows:

graph.SetSeries(seriesname; dataitem; dataitem; ...)

The first parameter is the name of the series. If the data series does not have a name, you will at least need to enter a semi-colon before entering any data items. Each subsequent parameter will be a data item. All parameters should be separated by semi-colons.

For standard data, such as our data from Table 6.1, a data item is simply a data value. So, for example, you could specify the data series in Table 6.1 using the following two commands.

graph.SetSeries(Atlanta; 23; 36; 11; 7)

graph.SetSeries(Boston; 41; 17; 25; 9)

For more complex data, a data item consists of several data values separated by commas. For example, consider an X-Y data series with the following plot points: (23,19), (39,27), and (14,85). The SetSeries() method for this series would be as follows.

graph.SetSeries(Boston; 23,19; 39,27; 14,85)

For more information about how to organize your data for more complex graphs, refer to Chapter 12, "Data Organization," in the PopChart Server Reference manual.

Sending PCScript to PopChart Server

There are several different strategies for sending PCScript to PopChart Server. Two of the best strategies are sending it via the PopChart Embedder and sending it via a Server Command File.

Sending PCScript Via PopChart Embedder

Usually, when you send pcScript to PopChart Embedder, you will want to build your PCScript using a separate variable. For example, many of the examples in this documentation build a PCScript command string in a local variable called pcscript.

After you have built your PCScript command string, you can then send it to PopChart Server using either the PopChart Embedder pcScript attribute.

The code below illustrates the use of the pcScript attribute in Java. In the first line, we create a local pcScript variable, to which we then add more information. In the last line, we set the PopChart Embedder pcScript attribute to the local pcscript variable. Note that the command string we build sends all of the information from Table 6.1.

Note: If you use this strategy with the JavaScript PopChart Embedder, you should make sure that your PCScript is short. Because of browser limitations, longer PCScript commands strings may cause the browser to be unable to display the PopChart image (refer to "Overcoming the URL Length Restriction"). A better option when using the JavaScript PopChart Embedder is to use a Server Command File. This limitation does not apply to the Java, COM, .NET and JavaBean versions of the PopChart Embedder.

Note: Using += to append to a String in Java is not optimal if you are appending a lot of data. Consider using a StringBuffer instead.

Server Command Files

Another strategy for sending PCScript is to store (or dynamically generate) your PCScript in a separate file and tell PopChart Server the location of this file. There are two potential advantages to this strategy.

1. The client or web application server does not have to process or send the data to PopChart Server, potentially saving bandwidth and circumventing size restrictions in the JavaScript PopChart Embedder or in the HTTP Request method (refer to "Overcoming the URL Length Restriction").

2. You can have a separate application that generates your PCScript. This application could, for example, query a database every 15 minutes and output a server command file containing up-to-date data.

A server command file can actually contain any number of server commands, but since you can implement almost all of the server commands with the PopChart Embedder, you will most likely only use it to store your PCScript commands. If you are interested in other server commands, however, you should refer to Chapter 11, "Getting PopChart Images with HTTP Requests."

At the beginning of your server command file, you should issue the @_PCSCRIPT server command, which tells PopChart Server that anything that follows is part of the PCScript command string. You can then list your PCScript commands. Example 6.7 shows how the data from Table 6.1 would look in a server command file. This file is saved as command1.txt in the examples/command folder.

You will need to tell PopChart Server where to find this server command by using the loadCommandFile(String) method. This method accepts a String containing either a URL for your server command file, or a file name relative to PopChart Server's document root. For example, to load the server command file from the example above, use the following PopChart Embedder method call.

myPopChart.loadCommandFile("examples/command/command1.txt");

Important: In order for PopChart Server to load a server command file, it must be given permission to read data from the specified path or domain. See "Setting Path Permissions" in Chapter 3 for more information.

Integrating with Example Code

To generate the PopChart image from the beginning of this chapter using the PopChart Embedder, all you need to do is insert the code from Example 6.6 before the final line of Example 4.7.

Example 6.8 shows the full code (minus the wrapping <script> tags) necessary to generate the example PopChart image using the JavaScript PopChart Embedder: