Sending Data with PopChart XML

PopChart XML is a new XML (eXtended Markup Language) format that allows you to control all aspects of a PopChart, including its appearance and data. For now, we will only concentrate on the data aspect of PopChart XML. In later chapters, however, you will learn how to add features such as Data Labels and Drill-Down with PopChart XML. Chapter 10, "Using PopChart XML," discusses different ways in which you can use PopChart XML.

Important: This section assumes you are at least somewhat comfortable using XML. If that is not the case, please refer to "XML Notations and Conventions" in Chapter 1 of the PopChart Server Reference manual for a brief overview of XML.

PopChart XML Data Format

Example 6.2 shows how the example data from Table 6.1 looks in PopChart XML.

Example 6.2 Example Data in PopChart XML

<Chart> 

   <GraphData Name='graph'> 

      <Categories> 

         <Category Name='Arrivals'/> 

         <Category Name='Departures'/> 

         <Category Name='Unused'/> 

         <Category Name='Out of Commission'/> 

      </Categories> 

      <Series Name='Atlanta'> 

         <Data Value='23.0'/> 

         <Data Value='36.0'/> 

         <Data Value='11.0'/> 

         <Data Value='7.0'/> 

      </Series> 

      <Series Name='Boston'> 

         <Data Value='41.0'/> 

         <Data Value='17.0'/> 

         <Data Value='25.0'/> 

         <Data Value='9.0'/> 

      </Series> 

   </GraphData> 

</Chart>

Note: PopChart Server can also use XML data that is in a standard database format (i.e. data that has been exported from a database in XML format). For more information, refer to "XML Data Files".

The first thing you'll probably notice is the <Chart> tag. In PopChart XML, everything must be inside of a Chart element.

Next, you will notice the <GraphData> tag. All data in PopChart XML is placed inside of a GraphData element. The GraphData element has an attribute called Name. You should set this attribute equal to the name of your graph (see "What is my Object Named?" in Chapter 6).

This is a sidebar.
Thus, if your graph was named linegraph, you would replace this line with the following:

<GraphData Name='linegraph'>

Inside of the GraphData you will find two types of elements. The first is your Categories element. This is where you tell PopChart Server what your category names will be. The Categories element can have any number of Category subelements, each of which stands for a separate category. The Category element has a Name attribute, which you should set to a category name.

For example, supposing our graph has three categories, Red, Green, and Blue, the Categories element would be as follows:

<Categories>
<Category Name='Red' />
<Category Name='Green' />
<Category Name='Blue' />
</Categories>

Important: Since there is nothing inside of the Category element, be sure to close it by placing a slash before the closing bracket (i.e. />).

There should be only one Categories element.

The other type of element in GraphData is the Series element. You will have one Series element for each series of data. The Series element has a Name attribute, which you should set to the name of the data series which the Series element represents.

Inside of the Series element you will find a number of Data subelements. The Data element represents a data item. Each Data element can have a number of attributes depending on the graph type. For most graphs, you only have to worry about the Value element, which should be set to the data value for your data item.

For example, if we have a series named Favorite Color, with the data values 81, 132, and 76, our Series element appears as follows:

<Series Name="Favorite Color">
<Data Value='81' />
<Data Value='132' />
<Data Value='76' />
</Series>

Important: Since there is nothing inside of the Data element, be sure to close it by placing a slash before the closing bracket (i.e. />).

Each series element should have one Data element for each <Category> tag in the Categories element.

The attributes for your Data element will differ according to the graph type. The list below shows what a Data element looks like for each graph type:
Graph Types Data Element
Area, Bar, Line, Pareto, Pie, Radar <Data Value='9.0' />
Stock (High-Low) <Data Name='6/5' High='15.0' Low='12.0' />
Stock (High-Low-Open-Close, Candlestick) <Data Name='6/5' High='15.0' Low='12.0' Open='13.2' Close='14.5'/>
Time Plot <Data Date='6/21/2000' Value='54.0' />
Time Plot (Bubble) <Data Date='6/21/2000' Value='54.0' Bubble='12.0' />
X-Y <Data X='12.0' Y='54.0' />
X-Y (Bubble) <Data X='12.0' Y='54.0' Bubble='5.0' />

For a more detailed description of how each graph type uses data, refer to Chapter 12, "Data Organization," in the PopChart Server Reference manual.

Sending the Data

How you send this data to PopChart Server will depend on how you store it.

If your data is stored in a file, or is generated dynamically by a web application server, you can use the loadPCXML(String) method. This method loads PopChart XML data into PopChart Server from a server-side file or from a URL.

For example, suppose you've saved your PopChart XML data in a file called votes.pcxml in the data folder of your PopChart Server document root. You could load data from that file with the following PopChart Embedder method call:

myPopChart.loadPCXML("data/votes.pcxml");

Note: The code above, like the code throughout this chapter, assumes that we have created a PopChart Embedder object named myPopChart (see "Instantiating a PopChart Embedder Object" in Chapter 4).

Similarly, suppose you have a web application at http://webapp.mycompany.com/?getpcxml which generates the PopChart XML data on the fly. You could load data from it with this PopChart Embedder method call:

myPopChart.loadPCXML("http://webapp.mycompany.com/?getpcxml");

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

Alternatively, you can "stream" the data to PopChart Server (i.e. your Java Server Page or Active Server Page containing the PopChart image either has the data already in it, or generates the data itself). In this case, you would use the addPCXML(String) method.

Note: You cannot stream XML to PopChart Server with the JavaScript PopChart Embedder. It must be located in a separate file.

For example, if we wanted to stream the PopChart XML from Example 6.2, we could make the following method call.

myPopChart.addPCXML("<Chart> <GraphData Name='graph'> <Categories> <Category Name='Arrivals'/> <Category Name='Departures'/> <Category Name='Unused'/> <Category Name='Out of Commission'/> </Categories> <Series Name='Atlanta'> <Data Value='23.0'/> <Data Value='36.0'/> <Data Value='11.0'/> <Data Value='7.0'/> </Series><Series Name='Boston'> <Data Value='41.0'/> <Data Value='17.0'/><Data Value='25.0'/> <Data Value='9.0'/> </Series> </GraphData> </Chart>");

Integrating with Example Code

A file containing the PopChart XML from Example 6.2 is located at examples/pcxml/data1_p.xml. Thus, by inserting the following line before the final line of Example 4.7, you will be able to generate the PopChart image from the beginning of this chapter.

myPopChart.loadPCXML("examples/pcxml/data1_p.xml");

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

Example 6.3 Adding PopChart XML Data to the Chapter 4 Example

myPopChart = new PopChartEmbedder(); 

myPopChart.appearanceFile = "examples/apfiles/bar.pcxml"; 

myPopChart.imageType = "FLASH"; 

myPopChart.fallback = "STRICT"; 

myPopChart.width = 600; 

myPopChart.height = 400; 

myPopChart.pcScript = "title.setText(Hello World)"; 

myPopChart.loadPCXML("examples/pcxml/data1_p.xml"); 

document.writeln(myPopChart.getEmbeddingHTML());

CORDA.com Previous Document Next Document