|
Sending Dynamic Data to PopChart Server | PopChart Server User Guide 4.0.5 |
If you store data in files that use a common data format, or if you have a database or web application that automatically generates data in a common file format, you can import that data directly into your PopChart image.
Note: Although this method of importing data is simpler than creating PopChart XML or PCScript, you may find it less convenient when you start adding effects like PopUp Text or Drill-Down in Chapter 7.
This section first introduces these formats and then discusses three methods of importing this data:
PopChart Server will import data from the following types of files.
Important: No matter what data format you're dealing with, you must make sure that is organized in a manner suitable for the graph type you are trying to display. When dealing with the most common graph types, the organization of your data is straight-forward. However, when dealing with graph types whose data items have more than one value (e.g. X-Y, Time Plot, and Stock, data organization is a little less instinctive). See Chapter 12, "Data Organization," in the PopChart Server Reference manual to learn how to organize the data for your graph type.
Tab delimited data files are files in which each data value is delimited by a tab character, and each row of data is delimited by a line break. PopChart Server interprets these files in the following manner:
Note: If you need to reverse the categories and series in an imported file, you can use the graph. Transposed() PCScript command.
Example 6.9 shows how the example data from Table 6.1 looks as tab-delimited data.
Comma Separated Value files are files in which each data value is delimited by a comma, and each row of data is delimited by a line break. Usually, these files will have a .csv extension. PopChart Server interprets these files in the following manner:
Example 6.10 shows how the example data from Table 6.1 looks as comma separated values.
Example 6.10 Example Data in Comma Separated Values Format
Most newer database systems are capable of exporting data to an XML format. PopChart Server can import most XML files exported by these databases.
Note: XML Data files are different than PopChart XML Data. Whereas the former is a general and loose format for describing data, the latter is a small subset of a rigid and robust XML document type created specifically for defining a PopChart. For more information, refer to "Sending Data with PopChart XML".
Example 6.11 shows the basic syntax for an XML data file. The tags in italics represent names that are arbitrary. The tags in yellow-green represent the names of categories or series. And, of course Data represents actual data.
Note: By default, most databases will export data in this format, so it may not be necessary for you to understand this syntax.
<SeriesNameTag>Series Name</SeriesNameTag>
<CategoryName1>Data</CategoryName1>
Example 6.12 shows how the example data from Table 6.1 might look in an XML format.
Example 6.12 Example Data in XML Format
<Out_of_Commission>7</Out_of_Commission>
The first thing you probably noticed was the <CarStatus> tag. The actual name of this tag is irrelevant. PopChart Server merely requires that all of the data be inside a top level element, which, in this case, is CarStatus. We could just as easily have named this element Status or RandomMeaninglessName.
Below the top level element, you will find two CityInventory elements. Each of these elements represent a data series. You could add additional series by adding additional CityInventory elements. Again, the name of these elements is irrelevant. The only thing that is important is that they are all named the same. There is no limit to the number of series that you can represent.
Inside of the CityInventory element you will find a City subelement. This subelement contains the data series name, Atlanta. Again, the name of this subelement, City, is irrelevant. PopChart Server will treat the data in the first subelement as the data series name, regardless of that subelement's name.
Finally, all remaining subelements inside of the series (CityInventory) element represent categories of data. The names of these subelements become the names of the categories. In other words, the category names are Arrivals, Departures, Unused, and Out of Commission. The data inside of these elements, of course, represent data values.
Note: because XML element names cannot have any spaces in them, you should use an underscore _ character to represent a space. Thus, in Example 6.12, Out_of_Commission represents the category Out of Commission.
Important: All of the series elements should have the exact same subelements, in the exact same order.
Currently, PopChart Server does not support importing standard XML data for an X-Y, Time Plot, or Stock graph. You should use PopChart XML instead.
PopChart Server can also search through an HTML document or web page to find an HTML table containing data. This means that if you have web pages with HTML tables in it, all you have to do is tell PopChart Server where the web page is located and what the table's title attribute is (or what the table's number, in order of occurrence, is). This process is sometimes referred to as screen-scraping.
Example 6.13 shows how the example data from Table 6.1 might look in HTML.
In many cases, the HTML Table will contain rows or columns of information that you don't want. You can filter out these rows and columns with the graph. EnableRow and graph. EnableColumn PCScript commands. Simply set the first parameter to false, and then list the rows or columns that you want to ignore. For example, you could filter out columns 2,3, and 7 with the following PCScript command:
graph.enableColumn(false,2-3,7)
If you don't know the number of the table that you want import data from, you can use the @_SHOWTABLESFROMURL server command. This command returns a list of all the tables in a web page, with their corresponding table number. This is sometimes a good utility to use even if you think you know the table number, as PopChart Server sometimes doesn't see all the tables that you see on the web page (e.g. when the table is generated by JavaScript).
To use this command, simply "browse" to the following location:
http://popchartserver.mycompany.com:2001/?@_SHOWTABLESFROMURLurl
Replace popchartserver.mycompany.com:2001 with the address and host of your PopChart Server. Replace url with the address of the web page that you want to list the tables from. PopChart Server will return a screen similar to the following.
In this situation, table 17 is the table we are looking for.
Important: In order for PopChart Server to list the tables in a web page, it must be given permission to read data from the specified path or domain. For more information, see "Setting Path Permissions" in Chapter 3.
To import data files in any of the formats described in the previous section, you should use the loadData() method. This method will look at the data and automatically determine its format, so you can use the same function for any data format.
The loadData() method accepts four parameters, but most of the time, you will only use two of them. The first parameter is a String containing the name of the graph object (see "What is my Object Named?" in Chapter 6) into which you wish to load the data. The second argument is the path to and location of your data file, which can be either on your server or at a URL.
For example, suppose you've saved your data file, named prices.csv, in the data folder of your PopChart Server document root. You could load data from that file into a graph object named graph using the following PopChart Embedder method call:
myPopChart.loadData("graph","data/prices.csv");
Similarly, suppose you have a web application at http://webapp.mycompany.com/?getdata which generates data on the fly. You could load data from it into an object named bar1 with this PopChart Embedder method call:
myPopChart.loadData("bar1","http://webapp.mycompany.com/?getdata");
Important: Because of limitations with the Component Object Model, loadData() always requires four arguments in the COM PopChart Embedder, even if you have no need to set the last two parameters. If you don't need to set the last two parameter and you are using the COM PopChart Embedder, set the third argument to "replace" and the fourth argument to an empty string (e.g loadData("graph","prices.csv","replace","");).
A third parameter, required for HTML Tables but otherwise optional (except if you are using the COM PopChart Embedder), specifies the method for loading the data. Usually, you should set this to replace, which means any data that has already been loaded into the graph, including data from the appearance file, will be replaced with the new data. You can also set this value to append, which adds the new data to the end of any pre-existing data.
A fourth parameter, which should be used only for HTML Tables (it is required with the COM PopChart Embedder, but ignored unless you use HTML Tables), specifies the number or title of the HTML Table that you want to load data from. For example, if you set this parameter to the number 8, PopChart Server will import data from the eighth table in the specified web page. Or, if you set this value to data2, PopChart Server will look for a table whose title attribute is set to data2 and import data from it.
In this latter case, assuming we are loading data from the page http://www.myserver.com/stats.html into the graph2 object, our PopChart Embedder method call would look like this:
myPopChart.loadData("graph2","http://www.myserver.com/stats.html","replace","data2");
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.
In the subfolders of the examples directory are four files with data in each of the formats mentioned in this section. These files are: examples/data/data1.dat ( Example 6.9), examples/data/data1.csv ( Example 6.10), examples/data/data1.xml ( Example 6.12), and examples/html/popchart_examples/bar_gra2.htm.html (Table 2, Example 6.13).
By inserting the following line before the final line of the example code from Chapter 4 ( Example 4.7), you will be able to generate the PopChart image from the beginning of this chapter using standard XML data.
myPopChart.loadData("graph","examples/data/data1.xml");
Example 6.3 shows the full code necessary to generate the example PopChart image using the JavaScript PopChart Embedder:
Example 6.14 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.PCScript = "title.setText(Hello World)";
You can also import data files using PCScript LoadFile() method. The syntax is very similar to that discussed "Importing Data Files with PopChart Embedder" in Chapter 6. The only difference is that instead of accepting a parameter for the graph object that you want to load your data into, you call a method on the object itself.
For example, suppose you've saved your data file, named prices.csv, in the data folder of your PopChart Server document root. You could load data from that file into a graph object named graph using the following PCScript method call:
graph.loadFile(data/prices.csv)
Similarly, to replace the data in a graph object named graph2 with data from a table named data2 on the web page http://www.myserver.com/stats.html, you would send the following PopChart XML to PopChart Server:
graph2.loadFile(http://www.myserver.com/stats.html,replace,data2)
You would then send your PCScript command to PopChart Server using its pcScript attribute, as discussed in "Sending PCScript Via PopChart Embedder" in Chapter 6.
Note: You can only stream data that is in the standard XML data format.
The final method of importing data files does not actually involve files at all. Instead, you stream the data directly to PopChart Server. For example, suppose that your Active Server Page or Java Server Page has access to a String of XML formatted data. You could import this data directly to PopChart Server via the PopChart Embedder setData() method.
This method works almost exactly as the loadData() method, discussed in "Importing Data Files with PopChart Embedder" in Chapter 6. The main difference is that it accepts a String of data instead of the location of a data file.
So, for example, to stream the data from Example 6.12, we would use the following method call:
myPopChart.setData("graph","<CarStatus><CityInventory><City>Atlanta</City><Arrivals>23</Arrivals><Departures>36</Departures><Unused>11</Unused><Out_of_Commission>7</Out_of_Commission></CityInventory><CityInventory><City>Boston</City><Arrivals>41</Arrivals><Departures>17</Departures><Unused>25</Unused><Out_of_Commission>9</Out_of_Commission></CityInventory></CarStatus>");
This setData() method does not allow you to append data to the graph. Any existing data will be replaced when you use it. It also does not accept a parameter for the HTML Table. It will still import data from HTML tables, however, it will assume that there is only one table in the String.
|
|