PopChart Server User Guide

Transcription

.....
PopChart
Server
User
Guide
...................................
Version 4.0.5
Last Updated on August 6, 2002
PopChart
6(59(5
Corda Technologies, Inc.
350 South 400 West, Suite 100
Lindon, UT 84042
Headquarters: (801) 805-9400
Fax: (801) 805-9405
Sales: (801) 805-9500
Technical Support: (801) 805-9505
Press Contact: (801) 805-9431
Sales Email: sales@corda.com
Support Email: support@corda.com
Microsoft, Visual Studio, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries. Screen shots reprinted by permission from Microsoft Corporation. Adobe is a registered trademarks
of Adobe Systems Incorporated in the United States and/or other countries. Macromedia, Flash, ColdFusion, and JRun are trademarks or
registered trademarks of Macromedia, Inc. in the United States and/or other countries. Sun, Java, JavaScript, iPlanet, and Solaris are
trademarks of Sun Microsystems, Inc. in the United States and other countries. Apple, WebObjects, and Mac OS are trademarks of Apple
Computer, Inc., registered in the U.S. and other countries. Netscape is a registered trademark of Netscape Communications Corporation in
the U.S. and other countries. JAWS is a registered trademark of Freedom Scientific in the United States and other countries. IBM and
WebSphere are registered trademarks of IBM in the United States. SVG is a trademark of the World Wide Web Consortium. UNIX is a
trademark registered in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Linux is a registered
trademark of Linus Torvalds. WebLogic is a registered trademark of BEA Systems, Inc. All other trademarks are the property of their
respective owners.
Copyright © 1996-2002 CORDA Technologies Inc.™ - PopChart™ - All Rights Reserved.
www.corda.com
Contents
.....
...................................
CHAPTER 1
Introduction
What Is PopChart? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Differences Between The Standard, Pro, and Enterprise Editions
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conventions Used in This Documentation . . . . . . . . . . . . . . . . . .
CHAPTER 2
1-2
. 1-5
. 1-7
1-11
. . . . . .
. . . . .
. . . . .
. . . . .
Installation
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deciding Where to Install PopChart Server . . . . . . . . . . . . . . . .
Downloading & Running the Installer . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting the PopChart Server Install Folder . . . . . . . . . . . . . . .
Choosing Shortcut Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing a Java Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing the Install Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Entering the License Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting Evaluation Key type . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Your Server / Completing the Installation . . . . . . . .
PopChart File/Directory Structure . . . . . . . . . . . . . . . . . . . . . . . .
Starting PopChart Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running PopChart Server as a Service . . . . . . . . . . . . . . . . . . . .
Running PopChart Server in UNIX Compatible Environments .
Interactive Data-Driven Graphics
2-1
. 2-3
. 2-5
. 2-6
. 2-7
. 2-8
. 2-9
2-10
2-12
2-14
2-16
2-18
2-19
2-20
2-21
2-22
2-25
2-26
. . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
iii
.....
PopChart
6(59(5
CONTENTS
Configuring Your Server
Migrating from a 3.x Version of PopChart Server .
CHAPTER 3
Configuring Your Server
Using the Administration Console . . . . . . . . . . . . . . . .
Setting Your Password. . . . . . . . . . . . . . . . . . . . . . . . .
Stopping, Starting, and Restarting PopChart Server
Entering a New License Key . . . . . . . . . . . . . . . . . . . .
Setting Server Address and Ports. . . . . . . . . . . . . . . . .
Using the Server Log and Console Output . . . . . . . . .
Changing Default Image Settings . . . . . . . . . . . . . . . .
Changing Cache Settings . . . . . . . . . . . . . . . . . . . . . . .
Installing Appearance Files . . . . . . . . . . . . . . . . . . . . .
Setting Path Permissions . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 4
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
4-2
. 4-3
. 4-5
. 4-6
. 4-8
. 4-9
4-11
4-13
4-16
4-18
4-19
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
Using PopChart Embedder
About the PopChart Embedder
iv
3-2
. 3-8
3-11
3-15
3-18
3-21
3-27
3-29
3-32
3-37
. . . . . . . . . . . . . . .
Embedding PopChart Images in a Web Page
Introducing the PopChart Embedder . . . . . . .
The Example Web Page . . . . . . . . . . . . . . . . . . .
Importing the PopChart Embedder Library . .
Delimiting the Code For Your PopChart Image
Instantiating a PopChart Embedder Object . .
Setting the Server Information . . . . . . . . . . . . . .
Choosing an Appearance File . . . . . . . . . . . . . .
Changing the Image Format . . . . . . . . . . . . . . .
Changing the Size of Your Image . . . . . . . . . . .
Customizing Your PopChart . . . . . . . . . . . . . . .
Writing the Image to Your Web Page . . . . . . . .
CHAPTER 5
2-28
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5-3
www.corda.com
User Guide
.....
CONTENTS
Sending Dynamic Data to PopChart Server
JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Server Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Server Page with JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Active Server Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ASP.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Including the PopChartEmbedder.jar File in Your Classpath . . . . . .
Installing the COM PopChart Embedder as a Component Services .
CHAPTER 6
.
.
.
.
.
.
.
.
.
Sending Dynamic Data to PopChart Server
How PopChart Server Uses Your Data
Sending Data with PopChart XML . . . . .
Sending Data with PopChart Script . . . . .
Importing Data from Data Files . . . . . . . .
Importing Data Directly from Databases .
CHAPTER 7
5-6
. 5-8
5-12
5-18
5-22
5-27
5-36
5-42
5-46
5-53
. .
6-2
. 6-5
6-10
6-16
6-25
. . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
Interactive and Special Effects
PopChart Script Review . . . . . . . . . . . . . . .
About PopChart XML in this Chapter . . . .
Data Labels . . . . . . . . . . . . . . . . . . . . . . . .
PopChart Notes . . . . . . . . . . . . . . . . . . . . .
PopUp Text . . . . . . . . . . . . . . . . . . . . . . . .
Drill-down Effects . . . . . . . . . . . . . . . . . . .
Changing Colors and Styles Dynamically .
Changing Scale Formatting Dynamically .
Scale Markers . . . . . . . . . . . . . . . . . . . . . .
HTML Data Tables . . . . . . . . . . . . . . . . . .
Legends . . . . . . . . . . . . . . . . . . . . . . . . . . .
7-2
. 7-4
. 7-5
. 7-9
7-12
7-14
7-18
7-22
7-27
7-29
7-31
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
v
.....
PopChart
6(59(5
CONTENTS
Displaying 508 Compliant Descriptive Text
Text Boxes . . . . . . .
Imported Graphics .
CHAPTER 8
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying 508 Compliant Descriptive Text
Corda Technologies and Descriptive Text . . . . . . . . . . . . . . . . . .
Why Do I Need Descriptive Text? . . . . . . . . . . . . . . . . . . . . . . . . .
“Viewing” Descriptive Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating Descriptive Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling How PopChart Server Describes a PopChart Image .
Customizing the Descriptive Text Template . . . . . . . . . . . . . . . . . .
CHAPTER 9
7-33
7-35
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-2
. 8-3
. 8-4
. 8-6
. 8-8
8-10
. . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
PopChart Fonts
About PopChart Fonts . .
Importing Custom Fonts
Using Custom Fonts. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-2
9-3
9-7
CHAPTER 10 Using PopChart XML
PopChart and XML . . . . . . . . . . . . .
Introduction to the PCXML Format
Appearance Files . . . . . . . . . . . . . . .
Data . . . . . . . . . . . . . . . . . . . . . . . . .
PCXML Transformations . . . . . . . .
10-2
. 10-3
. 10-7
. 10-8
10-11
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 11 Getting PopChart Images with HTTP Requests
HTTP Request Method Overview . . . . . . . . . . .
Request Format . . . . . . . . . . . . . . . . . . . . . . . . .
Server Commands . . . . . . . . . . . . . . . . . . . . . . .
Embedding a PopChart Image in an Image Tag
Embedding a FLASH PopChart Image . . . . . . .
vi
11-2
. 11-5
. 11-7
11-10
11-11
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
www.corda.com
User Guide
.....
CONTENTS
HTTP Redirection
Embedding an SVG PopChart Image . . .
Best Image Fallback . . . . . . . . . . . . . . . . .
Overcoming the URL Length Restriction
11-12
11-13
11-16
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 12 HTTP Redirection
Using HTTP Redirection . . . . . . . . . . . . .
Microsoft Internet Information Services .
Apache Web Server . . . . . . . . . . . . . . . . .
J2EE Web Application Servers . . . . . . . .
12-2
. 12-4
. 12-6
12-10
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . .
CHAPTER 13 Clustering
Requirements . . . . . . . . . . . . . . . . . . . . . . . .
About the pcClusterMonitor . . . . . . . . . . . .
Determining Your Network Architecture . .
Enabling PopChart Server for Clustering .
PopChart Embedder Configuration . . . . .
HTTP Redirector Configuration . . . . . . . . .
pcClusterMonitor Configuration . . . . . . . . .
13-2
. 13-3
. 13-4
13-11
13-12
13-15
13-16
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
CHAPTER 14 Troubleshooting PopChart Server
Updating PopChart Server . . . . . . . . . . . . . . . . . . . . .
Known Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running PopChart Server in Debug Mode . . . . . . . . .
Installation Problems . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setup Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Administration Console Problems . . . . . . . . . . . . . . . . .
Image Generation Problems . . . . . . . . . . . . . . . . . . . . . .
Network, Clustering, and HTTP Redirection Problems
PopChart Embedder Problems . . . . . . . . . . . . . . . . . .
14-2
. 14-3
. 14-5
. 14-6
. 14-7
. 14-9
14-10
14-14
14-15
. . . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . .
vii
.....
PopChart
6(59(5
CONTENTS
Improving Performance
APPENDIX A Improving Performance
Using the Pure Java AWT and Custom Fonts . . . . . . . . . . . . . . . .
Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Increasing or Decreasing the Maximum Number of Connections
Embedder Session Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Which Java VM PopChart Server Uses . . . . . . . . . . .
Increasing Efficiency by Saving and Loading Images . . . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
A-2
A-3
A-4
A-5
A-7
A-8
APPENDIX B Using The PopChart Web Server Control
About the PopChart Web Server Control . . . . . . . . . . . . . . .
Installing the Web Server Control . . . . . . . . . . . . . . . . . . . . .
Creating a PopChart-Enabled Web Application . . . . . . . . . .
Customizing Your PopChart . . . . . . . . . . . . . . . . . . . . . . . . .
Connecting to a Database . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Customization with PopChart Embedder.NET.
viii
B-2
. B-3
. B-7
B-11
B-20
B-22
. . . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
www.corda.com
I NTRODUCTION
W
.....
...................................
1
elcome to the PopChart Server User Guide. This manual is designed to teach you
how to use PopChart Server. This manual is designed for both those who are new to
PopChart Server and for those who are already familiar with PopChart Server, but just
want to learn about new features.
For readers already familiar with PopChart Server, we suggest you skip directly to the
chapter or chapters that discuss the features you want to learn about. Otherwise, we suggest
you start reading this manual from the beginning and keep reading until you are comfortable
with using PopChart Server. Very few individuals will want to read the entire manual, as
many of the chapters towards the end discuss advanced functionality and/or features
specific to using PopChart Server in certain environments.
If you are looking for something that will help you learn the basics of PopChart Server
quickly, you may want to refer to the PopChart Quick Start manual. If you are looking for
a reference on PopChart Server’s commands, the PopChart Embedder APIs, or other
specifications, you should refer to the PopChart Server Reference manual.
This documentation will be updated frequently as performance is enhanced and new
features are added. Please visit the Corda Technologies website (http://www.corda.com)
regularly for the latest documents.
1-1
.....
PopChart
1
6(5 9(5
INTRODUCTION
What Is PopChart?
.W. .H. A. . T. . I. S. . .P. O. . P. .C. H. . A. .R. .T.?. . . . . . . . . . . . . . . . . . . . . . . . .
In a world of ever increasing information, perhaps no skill is more valuable than the ability
to convey that information in the most understandable and accessible format possible. Raw
data is no exception to this rule, yet because understanding raw data often involves wading
through spreadsheet after spreadsheet in search of key figures and trends, it is often the
hardest type of information to convey.
For that reason, data visualization is paramount. Graphs and charts can convey in a few
seconds information that is often not clear even after hours of analyzing numbers. Data
visualization is what Corda Technologies is all about. With our easy-to-use PopChart
tools, you can translate your data into state-of-the-art PopChart images—eye-catching,
high-resolution, and interactive data-driven graphics, such as the ones on the next page.
A PopChart image can contain a variety of charts and graphs, fed with on-demand dynamic
data. It can include explanatory text boxes, callout notes, or PopUp text that appears as a
viewer rolls over certain parts of the graph. It can even include interactive drill-down
effects, such as linking to another PopChart image as a user clicks on a certain data item, or
executing your own custom JavaScript™ functions.
As you read through this documentation, you will learn all about how you can utilize
PopChart technology to convey your information. And, if you haven’t already, you will
soon discover why PopChart is your all-purpose data visualization tool.
A B O U T PopChart Server
PopChart Server does exactly what its name implies—that is, it serves images of charts
and graphs. But these aren’t just run-of-the-mill static charts and graphs. These are dynamic
and interactive images generated by PopChart Server on the fly.
It works like this. You create an appearance file (kind of like a template for a graph) with
PopChart Builder. Then, you send this appearance file to PopChart Server, along with
data and formatting options, and PopChart Server returns a PopChart image—a graphical
representation of your data, complete with PopUp text and the ability to drill-down to
another graph that explains a data item in greater detail.
The image can be in one of many different types of formats, including Macromedia®
FLASH™, SVG™, PNG, GIF, PDF, EPS, WBMP, and even d link descriptive text for the
visually impaired. You can also interface natively with PopChart Server in a variety of
environments, from simple HTML to ColdFusion®; from Java™ Application Servers to
Microsoft®’s .NET framework. PopChart Server can accept data from most database and
data file formats. It even supports XML, making PopChart Server easy to integrate with
your existing database system.
PopChart Server is the fastest, most robust, and most versatile data visualization and
charting tool on the market today. Best of all, because PopChart Server is written in 100%
Java, it can run on any platform. No matter what environment you operate in, you can take
1-2
www.corda.com
User Guide
.....
INT RODUC TION
What Is PopChart?
advantage of PopChart Server’s patented DataFunnel™ technology to deploy the latest in
state-of-the-art interactive data-driven graphics.
Over 20
different graph
types,
including Bars,
Pies, Gauges,
X-Y, Time, and
Radar.
Data can be
dynamic or
static.
PopChart also
supports XML!
Data items drill-down to other
web pages or PopCharts as
the user clicks on them. Or
you can execute a JavaScript
function.
Crisp, colorful, 3D graphics in
7 different formats, including
FLASH, GIF, SVG, and PDF.
1-3
.....
PopChart
1
6(5 9(5
INTRODUCTION
What Is PopChart?
OTHER POPCHART TOOLS
In addition to PopChart Server, you may also be interested in the following PopChart
tools:
POPCHART BUILDER
PopChart Server works hand-in-hand with PopChart Builder, a graphical design tool that
helps you design appearance files (templates) for your PopChart images. This easy-to-use
development tool can be purchased separately from PopChart Server, as many companies
have multiple developers creating appearance files, but only one or two servers.
For your convenience, the download for PopChart Server includes PopChart Builder, but
unless you have a separate license key, you will only be able to run the evaluation version of
it. If you chose to install documentation when you install PopChart Server, the PopChart
Builder User Guide is also included for your reference.
POPCHART XPRESS
For those looking to publish static PopChart images from their desktop, there’s PopChart
Xpress, a program that can run on any operating system and is easy enough for even nontechnical employess to use. You simply choose a graph type in the PopChart Wizard, copy
data from a spreadsheet program such as Microsoft Excel, select a few formatting options,
and PopChart Xpress generates everything you need to publish an image of your graph on
the web.
PopChart Xpress and PopChart Builder can be downloaded for evaluation or purchased
from the Corda Technologies website at http://www.corda.com.
1-4
www.corda.com
User Guide
.....
INT RODUC TION
DIFFERENCES BETWEEN THE
STANDARD, PRO, AND ENTERPRISE
EDITIONS
..................................................
There are three different editions of PopChart Server—PopChart Server, PopChart
Server Pro, and PopChart Server Enterprise. The following table shows what features
are available in each edition:
Features of PopChart 4.0 Server Products
Standard
Pro
Enterprise
Administration Console (HTML based)
X
X
X
PopChart XML Appearance Files
X
X
X
XML data file support
X
X
X
Graphical Logging
X
X
X
Double-Byte character support
X
X
X
Drill-down Effects, PopUp Text, and Rollover Data
Labels
X
X
X
Additional font support (includes font converter) –
international
X
X
X
Accessible descriptive text for the visually impaired
(508 compliant)
X
X
X
COM PopChart Embedder (ASP, Cold Fusion)
X
X
X
.NET PopChart Embedder
X
X
X
JavaScript PopChart Embedder (HTML)
X
X
X
PHP PopChart Embedder
X
X
Java PopChart Embedder (JSP, Servlets)
X
X
JavaBean PopChart Embedder (JSP)
X
X
Best Image Fallback
X
X
X
X
Anti-aliasing for GIF and PNG
X
X
Flash & SVG Image output
X
X
WBMP Image output
X
X
GIF & PNG Image output
X
1-5
.....
PopChart
1
6(5 9(5
INTRODUCTION
Features of PopChart 4.0 Server Products
Standard
Pro
Enterprise
PDF & EPS Image output
X
HTTP Redirectors for greater security and SSL
Support (Servlet, ISAPI (Windows IIS), and Apache
versions)
X
HTML table output
X
Clustering
X
Caching
X
At times, this documentation will discuss features that may only be available in the Pro or
Enterprise editions. At the beginning of sections that discuss an exclusively Pro or
Enterprise feature, you will see one of the following two lines:
Available only in PopChart Server Pro and PopChart Server Enterprise.
Available only in PopChart Server Enterprise.
1-6
www.corda.com
User Guide
.....
INT RODUC TION
What’s New
.W. .H. A. . T. .’ S. . .N. .E. W. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
With the release of PopChart 4.0, Corda Technologies has taken interactive data
visualization to a new level. It is hard to believe that with all of the great features such as
Flash, SVG, PNG, GIF, and WBMP image output, descriptive text for 508 compliance,
drill-down, pop-up and rollover and blazing speed that there is more to add. We have
worked hard to create even more to die for features in this release.
NEW FEATURES IN 4.0 RELEASE
Here is a list of some of the new features in PopChart 4.0.
• Web-based Administration Console provides improved reporting and simplifies
administration of PopChart Server.
• UNIX® scripts for starting and stopping PopChart Server for those who don't want to
use the Administration Console
• Support for GIF and PNG on UNIX systems via the Pure Java AWT
• You can now load appearance files and data from URLs.
• Support for PopChart XML, a new XML standard for describing appearance files and
data.
• On-the-fly appearance file modifications.
• Importing data directly from databases.
• Importing data from CSV and database generated XML data files.
• Importing data from HTML tables on web pages (Screen-scraping).
• PopChart Font Converter makes it possible to use your own fonts.
• More fully integrated double-byte character support makes it easy to use international
fonts.
• Anti-aliased GIF and PNG output with PopChart Server Pro and PopChart Server
Enterprise.
• PDF and EPS output with PopChart Server Enterprise.
• JavaScript PopChart Embedder makes learning to use PopChart Server quick and
easy.
• New and improved PopChart Builder interface, including a PopChart Wizard that will
help you create an appearance file in under a minute.
1-7
.....
PopChart
1
6(5 9(5
INTRODUCTION
What’s New
• Candlestick, Radar, Pareto, Bubble, and Gauge graph types.
• Macros for customizing data labels and drill-down.
• Improved automatic scale adjustments.
• Logarithmic scales.
• Line graphs now can have symbols, data labels, drill-down, and PopUp text.
• Improved legend formatting options vastly improves how PopChart Server adjusts to
large amounts of data, as well as allows you control over the number of columns in a
legend.
• PopChart Notes provide yet another way to interactively annotate your graphs.
• PopCharts can embed GIF or JPEG images, or use them as the background.
• Rotated text boxes and data labels.
• Background fill colors can be gradients.
• Background colors for graph grid area, legends.
• PopChart Server Enterprise supports HTML Table output below your graphs.
• Improved security permits file and domain restriction.
• Create 508 compliant charts and graphs with all PopChart products.
• Color theme support.
• Be ready for Web Services and .Net with end-to-end XML support and a .Net
component.
Experienced users might also want to note that there have been significant changes in the
way PopChart Server 4.0 operates. For more information, refer to the section entitled
“Migrating from a 3.x Version of PopChart Server” in Chapter 2, page 2-28.
NEW FEATURES/FIXES IN 4.0.1 RELEASE
The 4.0.1 release contains several new features and bug fixes. Significant new features
include:
• COM PopChart Embedder now supports importing data directly from an ODBC
database (via setDBQuery()).
• JavaScript PopChart Embedder now supports image maps (for PopUp and Drilldown
on GIF images).
1-8
www.corda.com
User Guide
.....
INT RODUC TION
What’s New
• Better support for embedded JPEG images when saving in the latest PCXML format (see
“Compatibility Between Versions” on page 10-3). They no longer result in large
appearance files or abnormally slow image generation time.
• Added a ZIndex to the many elements in PCXML, allowing them to be layered on the ZAxis dynamically.
• Added ability to change the color of Pareto bars, line, and line symbols, as well as the
line width.
For a list of all new features and bug fixes, refer to the release notes (the release_notes.txt
file in the Corda40 directory).
NEW FEATURES/FIXES IN 4.0.3 RELEASE
The 4.0.3 release contains several new features and bug fixes. Significant enhancements
include:
• Added the PopChart.NET Web Server Control, which is described in Appendix B,
“Using The PopChart Web Server Control.” Also fully documented the .NET
PopChart Embedder (refer to “ASP.NET” on page 5-27).
• Added PHP (refer to “PHP” on page 5-42) PopChart Embedder. Also included is a
beta version of the C++ PopChart Embedder, which is undocumented, but will work
with a Pro or Enterprise license.
• Added the makeFullRequest and maxRequestLength attributes to the PopChart
Embedder. These attributes allows you to specify that the PopChart Embedder
should embed a full image request instead of using PopChart Server’s key cache.
Essentially, this restores the functionality of the setUseCommPortNever() and
setUseCommPortIfOverLength() methods in version 3.x.
• Increased the functionality of the PopChart installer. It now generates PopChart
Builder and PopChart Server evaluation keys. It automatically registers the COM
PopChart Embedder.
• The D-link that appears at the lower right hand corner of an image when you have
enabled descriptive text output has been changed from an underlined and bracketed
upper-case [D] to an underlined lower-case d. This is to be more consistent with industry
standards.
The 4.0.3 release also contains many bug fixes. Significant bug fixes have been made in the
following areas: GIF and JPEG image import, Administration Console security, data
filtering, and the PopChart Builder interface. There have been many minor bug fixes.
1-9
.....
PopChart
1
6(5 9(5
INTRODUCTION
What’s New
There have also been several changes to the documentation and the installer. For a complete
list of changes, refer to the release notes (the release_notes.txt file in the Corda40
directory).
1-10
www.corda.com
User Guide
.....
INT RODUC TION
Conventions Used in This Documentation
CONVENTIONS USED IN THIS
DOCUMENTATION
..................................................
To make this manual easier to read, we use some special conventions when referring to files,
URLs, example code or text, and options or buttons in dialogs and menus. For the most part,
these should be pretty intuitive, but we mention them here just in case.
FILENAMES
Names of files are shown in a slightly larger arial font and are colored gray (e.g. myfile.txt).
Unless stated otherwise, files are all relative to the PopChart root directory. This directory
will vary from system to system. It is the folder where you installed PopChart Server.
Usually, this is C:\Program Files\Corda40 on Microsoft Windows® systems, or
/usr/local/Corda40 on UNIX® systems.
Another commonly used term is document root, which is where you keep all of your data,
xml, image, and appearance files for PopChart Server. Unless you have changed it in the
Administration Console, your document root will be the chart_root folder in your PopChart
root directory.
URLS
URLs are always shown in a slightly larger arial font. They are shown in two colors. If the
URL actually exists, it will be blue (e.g. http://www.corda.com). You will also be able to
click on it as if it were a normal link. If the URL is for example purposes only, it will be
colored gray (e.g. http://www.yourserver.com).
If the example URL is in reference to PopChart Server, you can usually make it a valid
URL if you replace www.yourserver.com with the address (and port) of your PopChart
Server.
EXAMPLE CODE
Small segments of code (including HTML and XML) that appear in the body of a normal
paragraph are shown in courier font, and are colored light green or yellow (e.g.
graph.Transposed(true)).
Medium sized segments of code appear on a single indented line in a courier font, as shown
below:
<img src=”http://www.yourserver.com:2001/?@_LOG>
1-11
.....
PopChart
1
6(5 9(5
INTRODUCTION
Conventions Used in This Documentation
Long segments of code look similar, but are on multiple lines and are delimited with a thin
horizontal line above and below the code. At the top left corner of the segment, there will be
an example number for reference. The code segment will also be given a title. Example 1.1
below demonstrates a longer segment of code.
Example 1.1
Example of Long Code Segment
myPopChart = new PopChartEmbedder();
myPopChart.appearanceFile("apfiles/test.bin");
myPopChart.pcScript("graph.setCategories(Jan;Feb;Mar;Apr;May;Jun)g
raph.setSeries(Temperature;30;40;50;60;70;80)graph.a
ddPopupText(1,1,Look at the pretty pictures)");
myPopChart.getEmbeddingHTML();
EXAMPLE TEXT
Any other example text, including text that should be typed into a dialog window and values
of attributes or variables, will appear italicized in a slightly larger arial font (e.g. false in
“The default value of graph.Transposed is false”).
MENU/DIALOG NAMES AND OPTIONS
Names of menus, dialogs, and options are in a slightly larger arial font and are colored light
green or yellow (e.g. Project Properties).
For brevity, whenever you have to go through multiple layers of menus or dialogs to arrive
at the desired menu, dialog, or option, a greater than > sign will be used to indicate that the
next menu, dialog, or option can be found under the previous.
For example, instead of saying, “Select the Save option from the File pull-down menu,”
this documentation will say, “Select File > Save.” Similarly, instead of saying, “Change
the value of the Port option in Address/Port screen of the Settings section in the
Administration Console,” this documentation will say, “Change the Settings >
Address/Port > Port option in the Administration Console.”
1-12
www.corda.com
I NSTALLATION
.....
...................................
T
2
his chapter will guide you through the process of installing PopChart Server and
running it for the first time.
Warning:
Do not install PopChart Server 4.0.5 over any previous versions of PopChart
Server. Older versions of PopChart Server can co-exist with PopChart Server 4.0.5,
but because the 4.0.5 version is so radically different, older versions cannot be
upgraded to version 4.0.5. For instructions on migrating from a previous version to
4.0.5, refer to “Migrating from a 3.x Version of PopChart Server” on page 2-28.
.S. Y. .S. T. .E. M. . . R. .E. Q. . U. .I.R. .E. M. .E. .N. T. .S. . . . . . . . . . . . . . . . . . . . .
PopChart Server 4.0.5 has the following system requirements:
Windows 98/NT4.0 or higher (2000
recommended), Mac® OS X, Solaris™ 8.0 or higher, and most UNIX or Linux®
compatible systems.
OPERATING SYSTEM
PROCESSOR
Equivalent of a Pentium II 233 or higher.
64MB dedicated to your Java Virtual Machine (128MB
recommended).
MEMORY
JRE 1.2 or higher. A Java VM (version 1.3.1) will be installed
automatically if you do not have one. Currently, we do not support Java VM version
1.4.
JAVA VM
HARD DRIVE SPACE
15 to 40 MB, plus 15 MB if you need to install a Java
Virtual Machine.
OTHER REQUIREMENTS
A network connection is required to serve
PopChart images.
To use the PopChart Embedder, most users will require a Java-extensible or
COM-enabled web application server.
To interface directly with a database, PopChart Server requires a JDBC or ODBC
driver for that database. PopChart Server can also import tab-delimited, comma
separated, and XML data, as well as data converted to the PopChart XML or
PopChart Script formats.
2-1
.....
PopChart
2
6(5 9(5
INSTALLATION
System Requirements
PopChart Builder, which can be installed automatically with PopChart Server, has the
additional requirement of JRE 1.3 or higher. On Mac OS X, we highly recommend the 1.3.1
version that was released on February 25th, 2002.
2-2
www.corda.com
User Guide
.....
INSTALLATION
Deciding Where to Install PopChart Server
D E C I D I N G W H E R E T O I N S T A L L PopChart
Server
..................................................
PopChart Server can be installed on just about any system, as long as it meets the
requirements outlined in the previous section. However, where you install PopChart
Server will depend largely on how you plan to use PopChart Server.
The following paragraphs discuss some questions that you should consider as you install
PopChart Server.
WHAT KIND OF SERVER LOAD DO YOU EXPECT?
In very light load situations, such as testing, development, or evaluation, it’s probably
easiest to install PopChart Server directly on your workstation. With light to medium
loads (up to 500 images per minute), you may be able to get by with a workstation, but
probably should move it to a light-weight or shared server. With heavy loads (over 500
images per minute), you might consider a dedicated server, while a very heavy load will
probably require clustering (see Chapter 13). You might also consider clustering if you are
concerned about redundancy.
WHAT OPERATING SYSTEM DO YOU WANT TO USE?
Because PopChart Server is a Java application, it runs on any system with a Java VM.
Naturally, performance will vary depending on the platform, but PopChart Server favors
no particular operating system. With light to medium server loads, it won’t matter what
operating system you are running—go with what you are most familiar with. With heavier
server loads, the usual logic prevails—if a certain system outperforms another system in
most benchmarks, PopChart Server will probably run better on that system.
HOW WILL YOU GENERATE CONTENT FOR YOUR GRAPHS?
If the information in your graphs is static, then this question is irrelevant. Most people,
though, will want to take advantage of PopChart Server’s dynamic capabilities. This
usually requires a web application of some sort that interacts with a database or data files to
generate data for your graph.
You should make sure that the system running PopChart Server can communicate with the
system running your web application and/or has access to the data. You may even find it
convenient to run PopChart Server on the same system as your web application server. Or
you could set up a separate web application server to deal specifically with graph content
generation.
WHO ARE YOU SERVING IMAGES TO?
It’s probably pretty obvious, but you should make sure that PopChart Server is installed
on a system accessible to the people who will be viewing the PopChart images. If you’re
generating images for a simple company intranet, then this is probably a very minor
concern. But if your serving images to the entire Internet, you will want to make sure that
2-3
.....
PopChart
2
6(5 9(5
INSTALLATION
Deciding Where to Install PopChart Server
PopChart Server is on a computer exposed to the Internet. Or if you need a little more
security than that, see the next question.
WHAT KIND OF WEB SECURITY DO YOU WANT?
PopChart Server is secure enough to install on system exposed to the Internet. However,
exposing it to the Internet will probably require you to open another port on your firewall.
Some users find it more desirable to put PopChart Server on a system behind their
firewall, and then use a redirector module. This allows clients to request images from a web
server, which then redirects the request to PopChart Server. This allows PopChart
Server to have the same security that the web server has, including SSH. See Chapter 12,
“HTTP Redirection,” for details.
2-4
www.corda.com
User Guide
.....
INSTALLATION
Downloading & Running the Installer
DOWNLOADING & RUNNING THE
INSTALLER
..................................................
Before you begin, you should download the PopChart Server 4.0.5 installer from
http://www.corda.com.
Note:
Linux and Solaris installations automatically include a compatible Java VM. For all other
UNIX compatible systems, read “Suggested Installation Procedure for Generic UNIX
Installer” on page 2-27.
T o r un th e i n s ta ll e r a ft er do w n l oa d i ng it
1
Locate the file that you downloaded. It’s name should be PCIS40.exe, PCIS40.bin, or
PCIS40.command, depending on your platform.
2
Run the installer by double-clicking on it or typing its name in a command prompt. On
UNIX compatible systems you may need to run sh PCIS40.bin in your command
prompt.
HEADLESS INSTALLER
A headless installer (i.e. no GUI) is available for UNIX compatible systems. There is a link
to it from the download page.
You will not be able to select any options—the default settings for the installation will be
used. Once you have run the headless installer, you should skip to “Starting PopChart
Server” on page 2-22 at the end of the chapter. You will also need to enter a license key
manually, following the instructions in “Entering a New License Key” on page 3-15.
2-5
.....
PopChart
2
6(5 9(5
INSTALLATION
Introduction
.I N. . T. .R. O. . D. .U. .C. T. .I .O. N. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
This is the first screen you will see. Press Next to continue.
Note:
2-6
At any time in the install process, you can return to a previous screen by clicking on the
Previous button.
www.corda.com
User Guide
.....
INSTALLATION
License Agreement
.L.I.C. .E. N. .S. .E. .A. .G. R. . E. .E. M. . E. .N. .T. . . . . . . . . . . . . . . . . . . . . . . .
This section contains the license agreement for using PopChart Server. You must read and
agree to the terms outlined in this agreement before continuing the installation process. You
can view this information again later by viewing the license.txt file that is installed in your
PopChart Server root directory.
After you have read this agreement, indicate whether or not you agree to the terms of the
license by clicking on either the appropriate radio button.
Important:
You must accept the terms of the license agreement to continue the installation.
Once you accept the terms of the license agreement, press Next to continue.
2-7
.....
PopChart
2
6(5 9(5
INSTALLATION
Release Notes
.R. E. .L. E. .A. .S. E. . .N. O. . T. .E. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
This section will contain information about new features in the version of PopChart
Server that you are installing, as well as any information pertinent to PopChart Server
that may not have made it into this documentation. We strongly recommend that you read
this section completely before continuing. You can find this information after installing
PopChart Server by viewing the readme.txt file.
Once you have read the release notes, press Next to continue.
2-8
www.corda.com
User Guide
.....
INSTALLATION
Selecting the PopChart Server Install Folder
S E L E C T I N G T H E PopChart Server I N S T A L L
FOLDER
..................................................
This screen allows you to choose the folder to which you wish to install PopChart Server.
This documentation will henceforth refer to this folder as the PopChart Server root
directory (not to be confused with the documentation root, which is usually the chart_root
folder inside of your PopChart Server root directory).
If the default folder shown in the text box is not acceptable, you can type a new folder.
Alternatively, you can browse to the install folder by selecting the Choose button.
Note:
Make sure you have permission to install to the folder you choose. For example, on Linuxcompatible systems, you will probably need to have root privileges to install to the
/usr/local directory (this is why it defaults to your home folder instead of something more
appropriate).
Once you have selected the install folder, press Next to continue.
2-9
.....
PopChart
2
6(5 9(5
INSTALLATION
Choosing Shortcut Location
.C. H. .O. .O. .S. I.N. .G. . S. .H. .O. .R. T. .C. U. .T. . L. .O. .C. A. .T. .I O. . N. . . . . . . . . . .
The PopChart installer can create shortcuts for you that will help you locate and run
PopChart programs and documents more quickly. These shortcuts include:
POPCHART SERVER
This starts PopChart Server.
POPCHART SERVER DEBUG
This starts PopChart Server in debug
mode.
POPCHART BUILDER
(If installed). This starts PopChart Builder.
POPCHART DOCUMENTATION
This brings you to the PDF and HTML
versions of the documentation.
This brings you to the PopChart Examples book,
which contains examples and code for each graph type and feature.
POPCHART EXAMPLES
Brings you to the web-based
administration console. PopChart Server must first be started, though.
POPCHART ADMINISTRATOR
UNINSTALL POPCHART
MY POPCHARTS
2-10
Begins the uninstallation process.
Opens up the document root folder.
www.corda.com
User Guide
.....
INSTALLATION
Choosing Shortcut Location
By default, these shortcuts are installed in a folder called PopChart 4.0.5 in either Start >
Programs (Windows), or the users Home folder (Mac OS X, Linux/UNIX compatible).
You can change the folder, or choose not to install shortcuts at all.
Important:
If you choose not to install shortcuts, you have to manually locate these files and documents.
On Windows NT®/2000, you can also select to install the shortcuts for all users that use
the system.
Once you have selected the folder for the shortcuts, click Next to continue.
2-11
.....
PopChart
2
6(5 9(5
INSTALLATION
Choosing a Java Virtual Machine
.C. H. .O. .O. .S. I.N. .G. . A. . .J. A. .V. .A. . V. .I .R. T. .U. A. . L. . M. . A. .C. .H. I. N. .E. . . . .
Note:
Mac OS X does not give the option of selecting a Java VM, so you will not see this screen on
that operating system.
Since PopChart Server is a pure Java application, it requires a Java VM (Virtual Machine)
to run.
If you do not know anything about Java Virtual Machines, or do not have a Java VM
installed on your machine, you should probably stick to the default selection of Install a
Java VM specifically for this application. This will install a bundled Java VM to the
jre folder of your PopChart root directory.
Note:
Installing the bundled Java VM will add 15-20 MB to your install size.
If you have a Java VM already on your computer, you can use that instead. The PopChart
installer will search your computer for existing Java Virtual Machines. You can select a VM
from this list to run PopChart Server. If the PopChart installer does not find your VM,
you can search for it again by clicking on the Search for Others button, or you can try to
locate it yourself by clicking on the Choose Another button.
2-12
Warning:
To use PopChart Builder, you must select a Java VM compatible with JRE 1.3 or
higher. The PopChart installer is not able to distinguish between Java VM versions,
so it may list a non-compatible VM. Make sure that the VM you select is compatible
with PopChart Server.
Warning:
We currently do not support Java VM version 1.4. You may still be able to get it
working, though (see “Unable to Run PopChart Server with Java 1.4 VM on
www.corda.com
User Guide
.....
INSTALLATION
Choosing a Java Virtual Machine
Windows” on page 14-7 and “Can’t Generate GIF Images with JVM 1.4” on
page 14-10).
Once you have selected the Java VM, click Next to continue.
2-13
.....
PopChart
2
6(5 9(5
INSTALLATION
Choosing the Install Set
.C. H. .O. .O. .S. I.N. .G. . T. .H. .E. .I.N. .S. T. .A. L. .L. .S. .E. T. . . . . . . . . . . . . . . .
PopChart Server will give you four different installation option. Each option is
customized for a different environment.
Note:
The edition of PopChart Server that you are running (e.g. PopChart Server Enterprise,
PopChart Server Pro) will depend on the license key you enter, not the install set.
This installs everything, including PopChart Server
and PopChart Builder. It includes examples and documentation for both products.
You will need 37 MB of hard drive space for this install set.
FULL INSTALLATION
This installs only PopChart Server. It includes examples
and documentation for PopChart Server. You will need 13 MB of hard drive
space for this install set.
SERVER ONLY
This installs only PopChart Builder. It includes examples
and documentation for PopChart Builder. You will need 31 MB of hard drive
space for this install set.
BUILDER ONLY
This installs PopChart Server for a production
environment. No examples or documentation will be installed. On Windows
NT/2000 and Mac OS X, PopChart Server is installed as a service. You will need
11 MB of hard drive space for this install set. If you choose this install set, make
sure you are logged in as a user with Administrative privelleges.
PRODUCTION SERVER
2-14
www.corda.com
User Guide
.....
INSTALLATION
Choosing the Install Set
Once you have decided on an install set, click Next to continue.
2-15
.....
PopChart
2
6(5 9(5
INSTALLATION
Entering the License Key
.E. N. .T. E. .R. .I .N. G. . .T. H. .E. . L. .I.C. E. .N. .S. E. . .K. E. .Y. . . . . . . . . . . . . . . .
After the installer has finished copying the necessary files, it will ask you for some user
information. You should enter the name of the individual and/or company to which your
product is licensed to. You should also enter the license key for PopChart Server and/or
PopChart Builder in the appropriate text box(es).
Warning:
Note:
If you are evaluating PopChart Server or PopChart Builder, do not enter anything in
the license key boxes. An evaluation key will be generated automatically for you
(refer to “Evaluating PopChart Products” on page 2-17).
Your license will determine which edition (e.g. PopChart Server Enterprise, PopChart
Server Pro) of PopChart Server you can run.
When you purchase PopChart Server, you should receive a license key. If you did not, you
should inquire about it with the vendor who sold you PopChart Server.
If you do not have a license key, you can purchase one from Corda Technologies. Visit
http://www.corda.com/purchase.cfm for more information.
2-16
www.corda.com
User Guide
.....
INSTALLATION
Entering the License Key
Note:
If you do not have the license key immediately available, or if you are evaluating PopChart
Server, you can enter your license key later following the steps outlined in “Entering a
New License Key” on page 3-15.
Once you have finished entering your license key, click Next to continue.
EVALUATING POPCHART PRODUCTS
If you are evaluating PopChart Server and/or PopChart Builder, the installer will
generate an evaluation key automatically for you. You will be able to run evaluation
versions of PopChart Server and/or PopChart Builder with the following restrictions:
•
Images generated by PopChart Server or PopChart Builder will have the words
Evaluation Use Only in the top left corner.
This license key will last 15 days. At the end of 15 days, PopChart Server and PopChart
Builder will run in an unlicensed mode, meaning you cannot save or preview appearance
files in PopChart Builder, and PopChart Server will shut down every three hours.
Extended time evaluation license keys are available upon request. Visit
http://www.corda.com/support for details.
T o r em ov e ev a lu a t io n r e s tr ic t io n s
To remove these restrictions, simply purchase a license from Corda Technologies.
When you buy a license key, you do not need to reinstall PopChart Server. Simply enter
your new license key following the steps outlined in “Entering a New License Key” on
page 3-15, and the evaluation restrictions will be removed.
2-17
.....
PopChart
2
6(5 9(5
INSTALLATION
Selecting Evaluation Key type
.S. E. .L. E. .C. .T.I.N. .G. . E. .V. A. . L. .U. A. .T. I. O. .N. . .K. E. .Y. . T. .Y. P. .E. . . . . . . .
If you are evaluating PopChart Server, you will also need to select which version
(Standard, Pro, or Enterprise) you want to evaluate. The next screen in the installer will let
you choose a version.
Note:
2-18
This screen will only appear if you are evaluating PopChart Server.
www.corda.com
User Guide
.....
INSTALLATION
Install Progress
.I N. . S. .T. A. .L. L. . .P. R. .O. .G. .R. E. .S. .S. . . . . . . . . . . . . . . . . . . . . . . . . .
Once you have selected all of your install options, the PopChart installer will begin
copying files to your computer. This screen shows you its progress. Depending on your
system, this process can take anywhere from a half to a couple of minutes. You can click
Cancel at any time to stop the installation.
2-19
.....
PopChart
2
6(5 9(5
INSTALLATION
Configuring Your Server / Completing the Installation
CONFIGURING YOUR SERVER /
COMPLETING THE INSTALLATION
..................................................
PopChart Server will briefly configure itself. After that, you will be brought to the
following screen.
This means you have successfully completed the installation process. Click Done to exit
the installer. The remaining sections in this chapter will help you start PopChart Server for
the first time.
2-20
www.corda.com
User Guide
.....
INSTALLATION
PopChart File/Directory Structure
.PopChart
. . . . . . . . . F. .I .L.E. ./ D. . I.R. .E. C. .T. O. . R. .Y. . S. .T. R. . U. .C. .T.U. .R. E. . . . . .
Before you begin using PopChart Server, you may want to be aware of how its files are
organized. It is not necessary to read this section, but it may be of benefit for power users.
The following list describes each of the folders that are installed in your PopChart Server
root directory. The PopChart Server root directory is the folder to which you chose to
install PopChart Server.
/bin
Executables, batch files, and scripts for PopChart Server, PopChart
Builder, and the Font Converter.
/chart_root Your document root. This is where you serve your appearance, data, and
command files from. Also contains your SVG templates and saved images, as
well as the example files.
/config
Stores configuration files and info, including path.xml and your license.
/dev_tools
Contains PopChart Embedders (Java, COM, JavaBean) and redirectors
(ISAPI, Apache, Servlet).
/docs
Documentation.
/lib
Contains.jar files, templates for PopChart Builder, and font-shape files.
/logs
Contains log files.
/tmp
Stores temporary files.
2-21
.....
PopChart
2
6(5 9(5
INSTALLATION
Starting PopChart Server
.S. T. .A. R. .T. .I N. .G. . .PopChart
. . . . . . . . .Server
...........................
Once you have installed PopChart Server, all you will need to do to start it is locate the
PopChart Server shortcut (on Windows, for example, it’s at Start > Programs >
PopChart 4.0) and run it.
Note:
If you chose not to install the shortcuts, you will need to locate the PopChartServer
executable in the bin folder and run it manually. On Windows and Mac OS X, this can be
done by double-clicking its icon. On Linux compatible systems, you may need to open a
command prompt, change to the directory, and type sh PopChartServer.bin.
When you start PopChart Server, you should see the following splash screen on Windows.
(On UNIX and Mac OS X compatible systems you will see nothing)
.
2-22
www.corda.com
User Guide
.....
INSTALLATION
After a few seconds the splash screen disappears. If everything started correctly, nothing
more will happen. Otherwise, you will receive an error message and PopChart Server will
shut down.
If you receive an error message, you should write it down and look it up in Chapter 14,
“Troubleshooting PopChart Server.”
TESTING YOUR INSTALLATION
If you want to make sure that PopChart Server started correctly you can always “ping” it
by loading the following address in your web browser:
http://localhost:2001
Note:
If you have changed the port number from 2001, you should replace 2001 with the
appropriate port number. Similarly, if you are trying to connect to PopChart Server from a
different machine, you should replace localhost with the name of the machine running
PopChart Server.
2-23
.....
PopChart
2
6(5 9(5
INSTALLATION
If PopChart Server is installed correctly, you should get a page similar to the one below.
If you do not get this page, PopChart Server was either not started, or did not start
properly. Try starting PopChart Server again, and if the error persists, refer to Chapter 14,
“Troubleshooting PopChart Server,” for advice.
2-24
www.corda.com
User Guide
.....
INSTALLATION
Running PopChart Server as a Service
.R. U. .N. .N. I. N. .G. . .PopChart
. . . . . . . . .Server
. . . . . . .A. S. . .A. . S. .E. .R. V. .I.C. E. . . . . .
On Windows NT/2000/XP and Mac OS X systems, you can install PopChart Server as a
service. This means that PopChart Server will run automatically in the background
whenever your computer is on, even if you are not logged in.
To install PopChart Server as a service, you should choose the Production install set
during the installation process, PopChart Server will automatically be installed as a
service. However, you can also install it as a service manually if you did not choose the
Production install set.
WINDOWS NOTES
Before PopChart Server will run as a service, you will need to either restart the computer
or manually start the service. You can manually start the service by launching
Administrative Tools > Services, right-clicking on the PopChartServer service, and
selecting Start.
Note:
If the PopChartServer service is not listed, you probably did not have Administrative
privileges when you installed PopChart Server. Uninstall PopChart Server, log in as an
Administrator, and install PopChart Server again.
T o in s t al l PopChart Server a s a s er v ic e if y o u d id n ot c h o o s e th e Production in s ta l l s et
You can still run PopChart Server as a service even if you did not choose the Production
install set. Follow these steps to do so.
1
Log in as Administrator or as a user with Administrative privileges.
2
Locate and run the bin/installService.bat file.
3
Restart your computer (or manually start the service using the procedure outlined at
the top of this page).
T o U n in s ta l l th e S e r v ic e Wi th o u t U n in s ta l li n g PopChart Server
1
1. Run the bin/removeService.bat file.
MAC OS X NOTES
You do not need to restart your computer before the service will be installed.
Currently, because of a bug in Mac OS X, the PopChart service will stop if the user logs out.
Also, if you request a GIF or PNG while PopChart Server is running as a service, a
generic Java icon will appear in the dock. Closing this icon will kill PopChart Server.
Again, this is a bug in Mac OS X, not PopChart Server. Apple® is aware of these bugs.
2-25
.....
PopChart
2
6(5 9(5
INSTALLATION
Running PopChart Server in UNIX Compatible Environments
R U N N I N G PopChart Server I N U N I X
COMPATIBLE ENVIRONMENTS
..................................................
Inside of the bin folder on UNIX installs, you will find a script called pca.sh, which can be
used to start and stop PopChart Server in place of the PopChartServer executable.
You can use the following commands from the bin folder of your PopChart installation to
start, stop, restart, and check the status of PopChart Server:
....................................................
Function
Command
Start
./pca.sh start
Stop
./pca.sh stop
Restart
./pca.sh restart
Status
./pca.sh status
You can create a symbolic link to the pca.sh script in your /usr/bin directory with the
command:
ln -s /usr/local/Corda/bin/pca.sh /usr/bin/pca
Replace /usr/local/Corda with the location of your PopChart installation. This will allow
you to start and stop PopChart Server without having to be in the bin directory.
You can also create a symbolic link to the pca.sh script in your startup directory with the
command:
ln -s /usr/local/Corda/bin/pca.sh /etc./rc3.d/S99.pca
Replace /usr/local/Corda with the location of your PopChart installation. Use rc2.d instead
of rc3.d for Solaris systems. This will allow PopChart Server to start automatically with
your server.
If you are having trouble with the scripts, you may need to change some values in the
config/pcs.settings file. Open this file in a text editor and make sure the settings are
appropriate for your system.
NOTES
PopChart Server now ships with ETeks Pure Java AWT, which is enabled by default on
UNIX platforms. The Pure Java AWT allows PopChart Server to generate GIF and PNG
images without the use of an X Server. With some JVMs the Pure Java AWT Settings must
be changed. For more information, refer to the section entitled “Using the Pure Java AWT
and Custom Fonts” on page A-2.
2-26
www.corda.com
User Guide
.....
INSTALLATION
Running PopChart Server in UNIX Compatible Environments
If you do not wish to use the Pure Java AWT on UNIX systems, PopChart Server’s Java
GIF and PNG renderer (AWT) requires access to an X Server or at least a Virtual Frame
Buffer, which emulates an X Server.
SUGGESTED INSTALLATION PROCEDURE FOR
GENERIC UNIX INSTALLER
On Linux and Solaris Sparc systems we provide JRE 1.3.1 with the install. You should
follow the normal installation procedure for these systems.
On all other UNIX or UNIX-like systems we provide a generic UNIX Installer. This
subsection will help you install with the generic installer.
In order to run the generic UNIX installer you must already have a running JVM or JRE
installed on the system, and the bin directory of your java home must (at least at installation
time) be in your path.
You can tell if java is in your path by typing which java.
Many Linux distributions come with a JVM clone named Kaffe whose executable is named
java. Installation on Linux systems will not work if Kaffe is your only JVM.
Installation seems to work best with a JVM from Sun®, version 1.2.2 to 1.3.1.
T o in s t al l th e ge n e r ic U N I X i ns t a ll er
1
Install a JVM between versions 1.2.2 and 1.3.1 from Sun if it’s available, otherwise
install one provided by your vendor.
2
Download the Generic UNIX PopChart Server installation file (PCS.bin).
3
Give the file executable permissions by typing "chmod u+x PCS.bin" in your download
directory.
4
Run the file from your download directory and complete the installation.
5
The installation program requires an X Display in order to run. If you do not have direct
access to the computer you are installing PopChart Server on, you may be able to
telnet/ssh into the server, export the display to an X Client, run the installer and
complete the installation.
6
An alternative would be to install it on a local system with a similar configuration to the
server (same java installation paths, operating system, and java vm installation
locations) and transfer it to the server via tar and ftp.
2-27
.....
PopChart
2
6(5 9(5
INSTALLATION
Migrating from a 3.x Version of PopChart Server
MIGRATING FROM A 3.X VERSION OF
PopChart Server
..................................................
Because PopChart Server 4.0.5’s directory structure is so radically different than that of
3.x versions of PopChart Server, you cannot simply upgrade from a 3.x version (at least
not if you want to keep your appearance files, data files, server settings, etc.).
Note:
If you uninstall your 3.x version of PopChart Server before installing PopChart Server
4.0.5, you will want to backup the files we are about to mention before uninstalling.
T o mi gr a te fr o m PopChart Server 3.x to PopChart Server 4.0.5
These are just recommended steps. How you migrate to 4.0.5 will differ greatly depending
on how 3.x was setup.
1
Copy any directories that store important data, appearance files, or templates (e.g.
apfiles, data, SVG_templates) to PopChart Server 4.0.5’s chart_root directory.
2
If you were running PopChart Server [D], copy dlink.xml from the pcis_classes
directory to PopChart Server 4.0.5’s config directory.
3
If you have made any modifications to path.xml file (in the pcis_classes directory), you
will need to merge the 3.x path.xml file with the 4.0.5 path.xml file.
PopChart Server 4.0.5 keeps its path.xml file in the config directory. The main
difference between this file and the 3.x file is that it now includes information about
valid callback domains. Copy the last two mappings from the 4.0.5 path.xml file
(which allow localhost callbacks) to the 3.x file, and then replace the 4.0.5 file
with the 3.x file. For more information about valid callback domains, refer to
“Setting Path Permissions” on page 3-37.
4
If you have any custom font files in the pcis_classes/fsfiles directory, copy these to
PopChart Server 4.0.5’s lib/fsfiles directory.
5
If you have set any command line arguments in the PopChartServer.lax file (on the line
that begins lax.command.line.args=), you should copy these to the PopChart
Server 4.0.5’s config/PCAgent.cfg file.
PopChart Server 4.0.5 stores all of its configuration settings in the PCAgent.cfg
file in its config directory. Any command line arguments that you were using in
PopChart Server 4.0.5 should be transferred to the [PCISStartupArgs]
section of this file. Each command line argument should be on a separate line. You
can read more about this file in “Configuration File Format” on page 3-2 of the
PopChart Server Reference manual.
2-28
www.corda.com
User Guide
.....
INSTALLATION
6
If you are running PopChart Server 3.x on a port other than 2001, or running the
commport on a port other than 2002, you will need to change these ports in PopChart
Server 4.0.5’s config/PCAgent.cfg file.
PopChart Server 3.x ran on ports 81 and 82, but PopChart Server 4.0.5 runs on
ports 2001 and 2002. If you wish to migrate to the new ports, you can ignore this
step (but be sure to change any HTML or PopChart Embedder code that had been
using PopChart Server 3.x’s ports).
To change the ports that PopChart Server 4.0.5 runs on, modify the following
two lines in the config/PCAgent.cfg file.
-port 2001
-commport 2002
You should replace 2001 and 2002 with the ports that you want PopChart Server
4.0.5 to use.
7
Load-balancing is no longer available in PopChart Server 4.0.5. If you were using loadbalancing, you should switch to clustering (refer to Chapter 13).
8
If you have been using the graph.LoadFile() command to import tab-delimited data
for X-Y, Time Plot, or Stock graphs, you will need to convert your tab-delimited files to
the new spreadsheet format for these graph types.
PopChart Server 4.0.5 uses spreadsheet data differently than PopChart Server 3.x
for these graph types. The new spreadsheet format for these graph types is more
intuitive than the format for PopChart Server 3.x. Unfortunately, we were unable to
make this aspect of PopChart Server backwards-compatible with tab-delimited data
files.
To learn how to format your tab-delimited data file, refer to “Spreadsheet” header under
the “Plot Data Class” and “Stock Data Class” sections of Chapter 12 in the
9
If you are using any redirectors, you should locate the redirector and replace it with the
4.0.5 version. The redirectors are located in PopChart Server 4.0.5’s dev_tools folder.
10
If you have been using the PCISEmbedder, replace your old PCISEmbedder library files
with the new PopChart Embedder library files.
Be sure to remove your old PCISEmbedder files (i.e. PCISEmbedder.jar,
PCISEmbedderBean.jar, PCISEmbedder.dll), as these may interfere with the
new PopChartEmbedder libraries.
The new PopChart Embedder libraries are located in the dev_tools folder.
The
PCISEmbedder.jar file has been replaced by the PopChartEmbedder.jar file.
Remove the PCISEmbedder.jar file from your classpath and add the
PopChartEmbedder.jar to your classpath (see “Including the
I F Y O U W E R E U S I N G T H E J A V A PCISEmbedder
2-29
.....
PopChart
2
6(5 9(5
INSTALLATION
PopChartEmbedder.jar File in Your Classpath” on page 5-46 if you do not
know how to do this).
The
PCISEmbedderBean.jar file has been eliminated. The JavaBean embedder is
now included in the PopChartEmbedder.jar file. Remove the
PCISEmbedderBean.jar file from your classpath and add the
PopChartEmbedder.jar to your classpath (see “Including the
PopChartEmbedder.jar File in Your Classpath” on page 5-46 if you do not
know how to do this).
I F Y O U W E R E U S I N G T H E J A V A B E A N PCISEmbedder
The
PCISEmbedder.dll file has been replaced by the PCEmbedder.dll file. Remove
the PCISEmbedder.dll file from your component services (by deleting the
PopChart.Embedder component) and install the new PopChart Embedder
component (see “Installing the COM PopChart Embedder as a Component
Services” on page 5-53 if you do not know how to do this).
I F Y O U W E R E U S I N G T H E C O M PCISEmbedder
Note:
11
The COM PopChart Embedder is not backwards compatible with PopChart Server 3.x.
If you need to run the 3.x PCISEmbedder and the 4.x PopChart Embedder simultaneously
on the same system, please contact our technical support staff for a solution.
If you have been using the PCISEmbedder without the comm port, go through any of
your existing code that uses the PCISEmbedder and set it to use the comm port.
The PopChart Embedder in PopChart Server 4.0.5 (and thus the deprecated
PCISEmbedder) requires the use of the comm port. To modify your existing code
to use the comm port, replace any setServerInfo() method calls with the
following two statements.
myPopChart.externalServerAddress =
"http://www.myserver.com:2001";
myPopChart.internalCommPortAddress =
"10.0.2.1:2002";
This, of course, assumes that your PCISEmbedder object is named
myPopChart. You should replace www.myserver.com:2001 with the address
and port that clients will use to request images from PopChart Server. You should
replace 10.0.2.1:2002 with the address and port that your application server will
use to communicate with PopChart Server (i.e. the comm port). To learn more
about the externalServerAddress and internalCommPortAddress
attributes, see Chapter 4 of the PopChart Server Reference manual.
12
(Optional) Go through any existing code that uses the PCISEmbedder and update it for
PopChart Embedder API.
PopChart Server 4.0.5 now uses the PopChart Embedder instead of the
PCISEmbedder that was used in prior versions. The API for the PopChart
2-30
www.corda.com
User Guide
.....
INSTALLATION
Embedder is different, so that it is more consistent across different platforms.
Many PCISEmbedder methods and properties have been deprecated.
To maintain backwards compatibility, there is still a PCISEmbedder class in the
PopChart Embedder library files. The PCISEmbedder methods will still work if
you keep using the PCISEmbedder class, so you won’t have to migrate your
existing code. Be aware, however, that the PCISEmbedder will no longer be
supported after the 4.x versions of PopChart Server.
Refer to “Deprecated Methods” on page 4-31 of the PopChart Server
Reference manual to see what changes you should be making to your code.
13
(Optional) Go through any existing PCScript and update it for 4.0.5 PCScript
commands.
Several 3.x PCScript methods, including Graph.Series and
Graph.Categories, have been deprecated. Like deprecated PCISEmbedder
methods, they will still work, but will no longer be supported after the 4.x versions
of PopChart Server.
Refer to “Deprecated Methods” on page 5-46 of the PopChart Server
Reference manual to see what changes you should be making to your code.
14
(Optional) If you are not yet using the PopChart Embedder, you may want to look into it.
We are now presenting the PopChart Embedder as the preferred way of
communicating with PopChart Server. The PopChart Embedder greatly
simplifies the process of embedding a PopChart image, as well as adds a significant
amount of functionality. You can still request images using HTTP Requests and the
Image URL Method, but this documentation is designed mostly for people using
the PopChart Embedder.
2-31
.....
PopChart
2
2-32
6(5 9(5
INSTALLATION
www.corda.com
C ONFIGURING Y OUR S ERVER
T
.....
...................................
3
his chapter will help you configure your PopChart Server. It assumes you have
already installed PopChart Server and tested your installation, as described in Chapter 2,
“Installation.”
This chapter will help you perform the following tasks:
• Using the Administration Console
• Setting Your Password
• Stopping, Starting, and Restarting PopChart Server
• Entering a New License Key
• Setting Server Address and Ports
• Setting Server Address and Ports
• Changing Default Image Settings
• Changing Cache Settings
• Installing Appearance Files
• Setting Path Permissions
For more complicated configuration issues, you may also be interested in these chapters:
• Chapter 9, “PopChart Fonts.”
• Chapter 12, “HTTP Redirection.”
• Chapter 13, “Clustering.”
• Chapter 14, “Troubleshooting PopChart Server.”
• Appendix A, “Improving Performance.”
3-1
.....
PopChart
3
6(5 9(5
C O N F I G U R I N G YO U R S E R V E R
Using the Administration Console
.U. S. .I.N. G. . .T. .H. E. . .A. D. .M. .I.N. .I S. .T. R. . A. .T. I. O. .N. . C. . O. .N. .S. O. .L. .E. . .
The easiest way to configure PopChart Server is through the PopChart Administration
Console. The Administration Console is a secure web based administration system that
starts up with PopChart Server (it is not technically part of PopChart Server, since it
runs as a separate process and uses separate ports).
Note:
If you are unable to start the Administration Console, you may need to change the ports that
it uses (2003 and 2004). Instructions for changing these ports are located in “Changing
Server and Administration Port Settings” on page 2-20 of the PopChart Server
Reference manual.
LOGGING IN
To log in to the PopChart Administration Console, follow these steps.
T o lo g in t o t h e A d m in i s tr a ti on C on s o le
1
Start PopChart Server.
If you do not know how to do this, refer to “Starting PopChart Server” on page 2-22.
2
If you are accessing the Administration Console from the machine running PopChart
Server, click on the PopChart Server Administrator shortcut.
When you click on this shortcut, you will be brought to the following page.
3-2
www.corda.com
User Guide
.....
After two seconds, you will be redirected to the Administration Console.
3-3
.....
PopChart
3
3-4
6(5 9(5
www.corda.com
User Guide
.....
3
If you are accessing the Administrative console remotely, or do not have a shortcut, go
to the following URL: http://www.myserver.com:2004/casapp/administrator.
You should replace www.myserver.com with the host name or IP address of the server
running PopChart Server. If you have changed the Administration Console port (not
the PopChart Server port), you will need to replace 2004 with the port that you
changed it to.
If a Cannot Find Server error appears, make sure that PopChart Server has been
started and that you do not receive an Administrative Console could not be started
error.
4
Enter your password and click on the Submit button.
When you first log into the Administration Console, this password is password. You
should change this password immediately to ensure security (refer to “Setting Your
Password” on page 3-8).
When you click submit, you should be brought to a page that looks similar to the following
page:
3-5
.....
PopChart
3
6(5 9(5
If you receive a Connection or Password Error instead, check to make sure your
password is correct and try submitting it again.
3-6
www.corda.com
User Guide
.....
OBTAINING HELP
The remainder of this chapter contains instructions on how you on how to make some of the
more common configuration changes to PopChart Server. For a full reference on the
Administration Console, refer to Chapter 2 of the PopChart Server Reference manual.
You can get help from within of the Administration Console at any time simply
by clicking on the help icon at the top right corner of the page.
3-7
.....
PopChart
3
6(5 9(5
Setting Your Password
.S. E. .T. T. .I .N. G. . .Y. .O. U. .R. . .P. A. .S. S. .W. . O. .R. .D. . . . . . . . . . . . . . . . . .
When you first install PopChart Server, your password is set to password. You will use
this password both when you log in to the Administration Console, and when you use
certain server commands (e.g. @_SAVE).
Warning:
Your password can use alphanumerical characters and spaces only. Using other
characters for your password will result in an error.
For security reasons, you should change this password immediately after you log in to the
Administration Console for the first time.
Important:
Be sure to write down your password so that you remember it. If you forget it, refer to
“Unknown or Forgotten Administration Console Password” on page 14-9 for
instructions on how to recover it.
T o c h an g e y o u r p a s sw o r d
1
Login to the Administration Console.
If you do not know how to do this, refer to “Using the Administration Console” on
page 3-2.
3-8
www.corda.com
User Guide
.....
2
Using the menu on the left, go to the Security > Change Password screen.
3
In the New Password box, enter a new password.
We recommend that your password be at least eight characters long and contain at least
one number, one lower-case letter, and one upper-case letter. It should not contain the
@ (at) or % (percentage) characters.
3-9
.....
PopChart
3
6(5 9(5
4
Enter this password again in the Confirm Password box.
5
Click Apply.
6
Restart PopChart Server.
If you do not know how to do this, refer to “Stopping, Starting, and Restarting
PopChart Server” on page 3-11.
3-10
www.corda.com
User Guide
.....
STOPPING, STARTING, AND RESTARTING
PopChart Server
..................................................
You usually only need to restart PopChart Server when you are upgrading it, changing its
configurations, or when it has stopped functioning properly. The Administration Console
will warn you when you need to restart PopChart Server by showing you the following
message at the bottom of Current PopChart Server Settings:
Note:
You need to restart PopChart Server anytime you change its configuration settings (but not
after uploading appearance files). When you change a setting, a notice prompting you to
restart PopChart Server will appear on the right sidebar of the console. You can click on
the word restart in this notice to restart PopChart Server without following the steps
below.
T o R e s ta rt PopChart Server
This will automatically stop and restart PopChart Server for you.
1
page 3-2.
2
Using the menu on the left, go to the Server > Home screen.
You will be brought to this screen automatically when you first log on.
3-11
.....
PopChart
3
6(5 9(5
3
Click Restart.
T o S to p PopChart Server
This temporarily stops PopChart Server. It does not stop other PopChart processes, such
as the Administration Console. To start PopChart Server once you have stopped, you
should follow the steps outlined in “To Start PopChart Server” below. Do not attempt to
start it with the installed shortcut or executable.
1
page 3-2.
2
3
Click Stop.
T o S ta r t PopChart Server
These steps assume that PopChart Server has been stopped using the steps outlined in “To
Stop PopChart Server” above. If you need to start PopChart Server in any other
situation, refer to “Starting PopChart Server” on page 2-22.
1
page 3-2.
3-12
www.corda.com
User Guide
.....
2
3
Click Start.
You will only see this button if PopChart Server has already been stopped.
T o S to p al l P o pC h a r t P ro c e s se s
This will kill all PopChart processes, including the Administration Console. Once you have
done this, the only way to start PopChart Server again, is to click on the installed shortcut
or run the executable.
1
page 3-2.
3-13
.....
PopChart
3
3-14
6(5 9(5
2
Using the menu on the left, go to the Server > Stop All screen.
3
Click Stop.
www.corda.com
User Guide
.....
Entering a New License Key
.E. N. .T. E. .R. .I .N. G. . .A. . N. .E. .W. . .L. I.C. .E. N. .S. .E. .K. .E. Y. . . . . . . . . . . . .
If you did not enter a license key when you installed PopChart Server, you can enter your
key in the Administration Console. Likewise, if you have purchased a new license key, you
can change it in the Administration Console.
For more information about obtaining a license key or evaluating PopChart Server, refer
to “Entering the License Key” on page 2-16.
T o e n te r o r c h an g e y o u r l ic e n se ke y
1
page 3-2.
3-15
.....
PopChart
3
6(5 9(5
2
3-16
Using the menu on the left, go to the Server > Version / License screen.
www.corda.com
User Guide
.....
3
In the License Key box, enter your new license key.
4
Click Apply to save your changes.
5
3-17
.....
PopChart
3
6(5 9(5
Setting Server Address and Ports
.S. E. .T. T. .I .N. G. . .S. .E. R. .V. E. .R. . .A. D. .D. .R. E. .S. .S. .A. .N. D. . .P. O. . R. .T. S. . .
By default, PopChart Server communicates with web clients over port 2001. This is
known as the server port. this is the only port you will need to expose externally if you want
to serve images to the outside world. If you don’t want to expose this port externally, you
may want to look into an HTTP redirector, which is discussed in Chapter 12, “HTTP
Redirection.”
PopChart Server uses a different port for communicating with web application servers via
the PopChart Embedder. This port is known as the comm port, and by default runs on port
2002.
We’ve selected these ports because it is highly unlikely that another application will be
using them. However, if you do have an application that uses these ports, or if you just
prefer to use different ports, you can change the server and comm ports with the
Administration Console.
Note:
PopChart Server’s Administration Console also uses two ports—2003 and 2004. You
cannot change these ports in the Administration Console. Instead, follow the instructions in
“Changing Ports outside of the Administration Console” below.
T o C h a ng e th e S e r ve r P o r t o r C om m P o r t
1
page 3-2.
3-18
www.corda.com
User Guide
.....
2
Using the menu on the left, go to the Settings > Address / Port screen.
3-19
.....
PopChart
3
6(5 9(5
3
4
If you need to change the server port, type in the new server port in the Port text box.
If you need to change the comm port, type in the new comm port in the Comm Port
text box.
5
If you need to change the server IP address or the comm port IP address, you can also
change those in the Server Address and Comm Address boxes.
Warning:
You should only change the address settings if you need to bind PopChart Server to
a specific IP address on a machine with multiple IP address. If you select an invalid
address, PopChart Server may not work properly.
6
7
CHANGING PORTS OUTSIDE OF THE
ADMINISTRATION CONSOLE
If you have a conflict with any of PopChart Server’s default ports (2001 through 2004),
you may be unable to login to your server with the Administration Console. In this case, you
can change the server or comm port outside of the Administration Console.
Instructions for changing these ports externally are located in “Changing Server and
Administration Port Settings” on page 2-20 of the PopChart Server Reference manual.
3-20
www.corda.com
User Guide
.....
Using the Server Log and Console Output
USING THE SERVER LOG AND CONSOLE
OUTPUT
..................................................
PopChart Server provides two ways of monitoring server transactions: the server log, and
console output. This section will help you configure and use these features.
TRANSACTION LOG
This is an internal log that stores information about PopChart Server’s most recent
transactions. If enabled, you can view it at the bottom of the Server > Statistics screen
in the Administration Console.
T o e n ab l e t he tr a n sa c ti o n l o g
1
page 3-2.
3-21
.....
PopChart
3
6(5 9(5
2
Using the menu on the left, go to the Files > Log File Location screen.
3
Check the Enable Data Logging box.
4
In the Number of transactions to log box, enter the number of recent transactions
you want PopChart Server to keep in its log.
For example, if you enter 150, PopChart Server will keep information about the last
150 requests it received.
3-22
www.corda.com
User Guide
.....
5
6
CONSOLE OUTPUT
This is what you would see if you were running PopChart Server from the command line
(such as when you run the PopChart Server with Console icon). It shows you real-time
console messages from PopChart Server. It will keep track of all messages since the
Administration Console was last stopped.
T o v ie w co n s o le ou t p ut
1
page 3-2.
3-23
.....
PopChart
3
6(5 9(5
2
Using the menu on the left, go to the Files > View Console Output screen.
By default, PopChart Server will output very little information to the console. If you
enable debug mode, however,PopChart Server can send detailed messages to the console
for every image it generates, including the file format and the amount of time it took to
generate the image. It can also dump every request it receives to the console.
3-24
www.corda.com
User Guide
.....
T o e n ab l e d e b ug m o d e
1
page 3-2.
2
Using the menu on the left, go to the Settings > Debug screen.
3-25
.....
PopChart
3
6(5 9(5
3
Check the Enable Debug Mode box.
4
Select a debug setting by selecting either the Normal or Verbose radio button.
The Normal setting will output detailed information about each image that PopChart
Server generates. The Verbose setting will do this, as well as dump each request that
PopChart Server receives over the server and comm ports to the console.
5
6
Warning:
3-26
Do not run PopChart Server in debug mode, especially under the verbose setting,
for extended periods of time. Besides consuming additional resources, debug
output will create a very large temporary file to store the console output.
www.corda.com
User Guide
.....
Changing Default Image Settings
.C. H. .A. .N. G. . I.N. .G. . D. .E. .F. A. .U. .L.T. . I. M. .A. .G. .E. .S. .E. T. .T. I.N. .G. .S. . . .
When you first install PopChart Server, PopChart Server will assume that unless
instructed otherwise (using the imageType PopChart Embedder attribute), it should
generate PopChart images in the FLASH format.
You can change the default format for your PopChart images in the Administration console.
T o c h an g e t h e d e fa u lt i ma g e f or ma t
1
page 3-2.
2
Using the menu on the left, go to the Settings > Image Type screen.
3
From the Default Image Type pull-down menu, select an image type.
Your default image format can be either SVG™, Macromedia® Flash™, or GIF. For
other formats, you will need to override the format manually, using the imageType
PopChart Embedder attribute, or by changing the -type attribute in the
configuration file.
4
5
For more information about image formats, refer to Chapter 14 of the PopChart Server
Reference manual.
AUTOMATIC PNG DETECTION
Another feature of PopChart Server is Automatic PNG Detection. When this feature is
enabled, PopChart Server will automatically detect whether or not a client supports PNG
images. If the client requests a GIF image, but supports the PNG format, PopChart Server
3-27
.....
PopChart
3
6(5 9(5
Changing Default Image Settings
will return a PNG image instead of a GIF image. Otherwise, PopChart Server will simply
return a GIF image.
By default, this feature is enabled.
Note:
To a user, PNG images are exactly like GIF images, except they contain more colors, have a
higher resolution, and are smaller in size. All major browsers and image editors support the
PNG format. Unless you specifically need GIF images, there is no harm in leaving this
feature enabled.
T o e n ab l e o r d is a b le A ut o ma ti c P N G De t e ct io n
1
page 3-2.
3-28
2
Using the menu on the left, go to the Settings > Image Type screen.
3
Check the Auto PNG Images box.
4
5
www.corda.com
User Guide
.....
Changing Cache Settings
.C. H. .A. .N. G. . I.N. .G. . C. .A. .C. H. . E. . .S. E. .T. T. .I .N. G. .S. . . . . . . . . . . . . . . .
PopChart Server Enterprise employs caching to help increase performance. For details
about caching, refer to
IMAGE CACHE
Using the Administration Console, you can adjust the number of images that PopChart
Server stores in its cache.
The appropriate size for your cache will depend greatly from server to server. For advice on
finding the optimal cache setting, refer to “Caching” on page A-3.
T o c h an g e t h e s iz e o f t h e c a ch e
1
page 3-2.
3-29
.....
PopChart
3
6(5 9(5
2
3-30
Using the menu on the left, go to the Settings > Cache / Connections screen.
www.corda.com
User Guide
.....
3
In the Cache Size box, enter the number of images that you would like PopChart
Server to store in its cache.
4
5
APPEARANCE FILE CACHE
PopChart Server Enterprise can also cache appearance files. Using the Administration
Console, you can enable or disable the appearance file cache.
T o e n ab l e o r d is a b le ap p e a ra n c e f il e c a ch i n g
1
page 3-2.
2
Using the menu on the left, go to the Settings > Cache / Connections screen.
3
Check the Enable Appearance File Caching box to enable appearance file caching.
Uncheck it to disable appearance file caching.
4
5
3-31
.....
PopChart
3
6(5 9(5
Installing Appearance Files
.I N. . S. .T. A. .L. L. .I.N. G. . .A. .P. P. .E. .A. R. .A. .N. C. .E. . F. .I.L. E. .S. . . . . . . . . . .
Appearance files are essentially templates for the PopChart images that PopChart Server
generates. They can be created with PopChart Builder, or, if you’re really adventurous,
you can create them yourself in XML.
Appearance files should be kept in PopChart Server’s document root, which is usually the
chart_root directory. Although they can be stored in any folder within the document root,
this documentation usually places them in the apfiles directory.
By default, PopChart Builder will save any appearance files that you create to the
chart_root/apfiles directory. This means that unless you change the save location, you do
not have to install the appearance files if you are using PopChart Builder on the same
machine that PopChart Server runs on.
If you are running PopChart Builder on a different machine, the simplest way to install an
appearance file is probably just to copy it directly to the appropriate folder on the machine
that runs PopChart Server. However, this may not always be possible.
T o in s t al l a p pe a r an c e f il e s u s in g t h e A d mi ni s tr a ti on C o ns o l e
1
page 3-2.
3-32
www.corda.com
User Guide
.....
2
Using the menu on the left, go to the Files > Upload Appearance Files screen.
3-33
.....
PopChart
3
6(5 9(5
3
In the Destination Directory text box, enter the location (path only) that you would
like to save the appearance file to.
This location is relative to the document root. For example, entering apfiles would
upload the appearance file to the apfiles directory. Leaving this box blank will upload
the file to the document root.
Currently, you can only upload to a directory under the document root (i.e. you can’t
move up a directory by using .. in the file name).
Note:
4
In order to upload an appearance file, the subdirectory to which you are uploading must
already exist.
In the File to Upload box, enter the appearance file that you want to upload.
Alternatively, you can click the Browse button to locate this file.
The path to this file will be relative to your local machine.
5
Note:
Click Upload to install the file.
Appearance files should always have a .pcxml extension. If you are using an appearance
file from PopChart 3.x, this is not a requirement.
You may also find it useful to see what appearance files are already on PopChart Server.
T o v ie w cu r re n t ly i n s ta ll e d a p p ea r a n ce fi le s
1
page 3-2.
3-34
www.corda.com
User Guide
.....
2
Using the menu on the left, go to the Files > List Appearance Files screen.
The list on this page displays all appearance files in the directory specified at the top of
the page. This directory is relative to the document root directory. When you first enter
this screen, you will be shown the apfiles subdirectory.
3-35
.....
PopChart
3
6(5 9(5
3
If you need to view the appearance files in a subfolder of the document root directory,
enter the subfolder name in the Change Directory box and click Apply.
If you need to browse up to the document root, you can enter .. to browse up a level.
3-36
www.corda.com
User Guide
.....
Setting Path Permissions
.S. E. .T. T. .I .N. G. . .P. .A. T. .H. . P. .E. R. . M. .I.S. S. .I.O. .N. S. . . . . . . . . . . . . . . .
For security reasons, PopChart Server can only read and write appearance, data, and
PopChart XML files from authorized locations. By default, PopChart Server can only
read from its document root directory and subdirectories, and the localhost (127.0.0.1)
domain. It can only write to the images folder of the document root directory.
This means that you will need to authorize any other locations that you want PopChart
Server to read from or write to. For example, suppose that you wanted to load data from a
web application server located at http://webapp.mycompany.com. PopChart Server
would need to be given permission to retrieve data from this location. Likewise, you would
need to give PopChart Server permission to load an appearance file from the C:\InetPub
folder on the computer running PopChart Server
You can control which locations PopChart Server can read or write from by editing the
path.xml file. This file is located in the config directory. You can edit it in a text editor such
as Microsoft Notepad, or you can edit it in the Administration Console.
THE NEED FOR SECURITY
To convince you of the need for a path.xml file, and also to keep you from defeating the
purpose of this file, we should point out two ways by which an insecure server can be
abused.
First of all, PopChart Server’s save capabilities can be used to overwrite crucial system
files. For example, PopChart Embedder’s
saveImageToPopChartServer(String) method allows a programmer to save
images for future use to the machine running PopChart Server. A hacker could easily use
this method to save an image over a system file, thus crashing your server.
To prevent this from occurring, the path.xml file controls which directories PopChart
Server can write too. By default, the only directory to which images can be saved is the
images folder inside of the document root directory. Unless you have a really good reason
to add another location, you should probably leave it this way.
Note:
You also need to specify a password to save images to PopChart Server.
The second security issue is that PopChart Server can now read appearance and data files
from URLs. Although this flexibility is one of PopChart Server 4.0.5’s most attractive
features, it also opens up the possibility for parasites—outside users that use your
PopChart Server to serve their own PopChart images.
For example, suppose the webmaster for a small website decides she wants the benefits of
PopChart Server, but doesn’t want to buy it. All this webmaster has to do is figure out the
address and port that your PopChart Server runs on (which is easy to discover by viewing
your web page’s HTML), and she would instantly be able to use it to request and generate
images for her own website. Of course, our more philanthropic customers might not mind
3-37
.....
PopChart
3
6(5 9(5
lending a few graphs to the less fortunate, but what if this small website suddenly becomes
popular, thus dramatically increasing your server load? Or what if this small website
belongs to a competitor?
To prevent such abuse, the path.xml file allows you to specify a list of valid callback
domains. The term callback describes any requests PopChart Server makes to an outside
resource for information (appearance files, data, etc.).
M O D I F Y I N G path.xml
To add or remove path and URL permissions for PopChart Server, you should modify the
path.xml file.
T o a d d p e rmi s s io n t o r ea d fr o m a sp e c if ie d UR L
1
Login to the Administration Console and go to the Security > Path / URL
Permissions screen.
The text box on this screen contains the contents of the path.xml file. You can edit the
file directly in this text box.
3-38
www.corda.com
User Guide
.....
2
Copy the following text (which also appears at the top of the page in the Administration
console) and paste it immediately above the last line:
<Map Name="MyAppServer" Path="appservername.mycompany.
com" Action="allowDomain"/>
3-39
.....
PopChart
3
6(5 9(5
3
Replace MyAppServer (the value of the Name attribute) with the name you wish to give
to this mapping.
This name is for descriptive purposes only, and is entirely up to you. In fact, this step is
entirely optional.
4
Replace appservername.mycompany.com (the value of the Path attribute) with the
name or IP address of the host that you want to allow PopChart Server to read from.
This will allow PopChart Server to read any file that comes from the specified host.
For example, if we specify www.mycoolstats.com, we could read from sources such
as http://www.mycoolstats.com/data/110899.html,
http://www.mycoolstats.com/renderer?name=bar&apfile=26, etc.
You can also use wildcards. For instance, *.corda.com would allow any host in the
corda.com domain (www.corda.com, popchart.corda.com, etc.). Similarly, 10.0.*.*
would allow PopChart Server to read from any IP address that begins with 10.0.
5
Click Apply to apply your changes. You do not need to restart PopChart Server.
T o a d d p e rmi s s io n t o r ea d fr o m a sp e c if ie d lo c al p a t h
1
Login to the Administration Console and go to the Security > Path / URL
Permissions screen.
The text box on this screen contains the contents of the path.xml file. You can edit the
file directly in this text box.
2
Copy the following text and paste it immediately above the last line:
<Map Name="Read" Path="./path" Action="Load"/>
Note:
3
This text is different from the text that appears in the Administration Console.
Replace Read (the value of the Name attribute) with the name you wish to give to this
mapping.
This name is for descriptive purposes only, and is entirely up to you. In fact, this step is
entirely optional.
4
Replace ./path (the value of the Path attribute) with the local path that you want to
allow PopChart Server to read from.
If you precede the path with ./, PopChart Server will assume it to be relative to the
document root. Otherwise, it will assume the path to be an absolute path, accessible to
the machine that PopChart Server is running on. You can also put a wildcard at the
end of a path to indicate that PopChart Server has permission to read from any of the
path’s subdirectories.
For example, if you set this value to F:\InetPub\mydata\*, you are giving PopChart
Server permission to read anything from the F:\InetPub\mydata directory, as well as
any of its subdirectories. If you set this value to ./data, you are giving PopChart
3-40
www.corda.com
User Guide
.....
Server permission to read from the data directory in the document root, but none of its
subdirectories.
5
Click Apply to apply your changes. You do not need to restart PopChart Server.
3-41
.....
PopChart
3
3-42
6(5 9(5
www.corda.com
E MBEDDING P OP C HART I MAGES IN A W EB P AGE
.....
...................................
T
4
his chapter will walk you through the process of embedding a simple PopChart image
into a web page. This chapter assumes that you have successfully installed PopChart
Server, and that you have been able to start it. If this is not the case, please review
Chapter 2, “Installation.”
In this chapter, we will use the JavaScript version of the PopChart Embedder utility to
embed the example PopChart. As long as you have a basic knowledge of HTML and
JavaScript, you should be able to follow along. The PopChart Embedder utility is
described briefly in “Introducing the PopChart Embedder” at the beginning of this
chapter.
The procedure for embedding a simple PopChart image consists of the following steps:
1
Importing the PopChart Embedder Library
2
3
Instantiating a PopChart Embedder Object
4
Setting the Server Information
5
Choosing an Appearance File
6
Changing the Image Format
7
Changing the Size of Your Image
8
Customizing Your PopChart
9
Writing the Image to Your Web Page
The sections in this chapter discuss each of these steps in detail.
For a more complex PopChart image, of course, you will also want to add data, interactivity,
and special effects. These features will be discussed in Chapter 6, “Sending Dynamic Data
to PopChart Server,” and Chapter 7, “Interactive and Special Effects.”
4-1
.....
PopChart
4
6(5 9(5
E M B E D D I N G P O P C H A R T I M A G E S I N A WE B P A G E
Introducing the PopChart Embedder
.I N. . T. .R. O. . D. .U. .C. I.N. .G. . T. .H. .E. .PopChart
. . . . . . . . . Embedder
.................
The PopChart Embedder is a programming utility that helps you embed a PopChart
image into a web page. The utility is available for Java, JavaBeans, JavaScript, .NET, and
COM, meaning that it can be used in most of the common web environments.
In this chapter, and throughout most of this manual, we will use the JavaScript PopChart
Embedder. The reason for this is that almost all users already know enough HTML and
JavaScript to be able to use the JavaScript embedder.
Not to worry, though. The PopChart Embedder API is virtually the same for all versions,
You will easily be able to apply example code for the JavaScript embedder to the Java,
JavaBean, .NET, or COM embedder.
Important:
Though the JavaScript embedder is great for learning how to use PopChart Server, we do
not recommend that you use it in a production environment. It is significantly slower than
other embedders, and will result in a higher server load. Also, because of the nature of
JavaScript, the JavaScript embedder cannot support some of PopChart Embedder’s more
advanced functionality—such as importing data directly from a database, or streaming
PopChart XML or data to PopChart Server.
After you feel comfortable using the PopChart Embedder in general, refer to Chapter 5,
“Using PopChart Embedder.” That chapter will help you set up the PopChart
Embedder for your programming environment.
4-2
www.corda.com
User Guide
.....
The Example Web Page
.T.H. .E. . E. .X. A. . M. .P. .L.E. . .W. .E. B. . .P. A. .G. .E. . . . . . . . . . . . . . . . . . . .
In this chapter, we will embed our PopChart image into the following example web page:
For your benefit, this page is installed with PopChart Server in the
chart_root/examples/html folder. It is called blank_page.html. You may want to copy
this file and rename it before you begin modifying it.
The arrow indicates where we want to insert the PopChart image. To begin embedding an
image, open this web page in a text editor such as Microsoft Notepad. You will see the
following source.
4-3
.....
PopChart
4
6(5 9(5
The Example Web Page
All of the code that we are about to add should be inserted below the line that reads
.
4-4
www.corda.com
User Guide
.....
Importing the PopChart Embedder Library
I M P O R T I N G T H E PopChart Embedder
LIBRARY
..................................................
The first task is to import the PopChart Embedder library. How you do this will depend
upon which version of PopChart Embedder you are running. As we mentioned in
“Introducing the PopChart Embedder” on page 4-2, this chapter focuses on the
JavaScript emebedder. To learn how to import the PopChart Embedder library for your
programming environment, refer to Chapter 5, “Using PopChart Embedder.”
To import the PopChart Embedder library, insert the following HTML tag into the
example web page:
<script language="JavaScript1.2"
src="http://localhost:2001/jsEmbedder"></script>
This code assumes that you are testing this example on the machine running PopChart
Server. If this is not the case, you should replace the name localhost in the src tag with
the name of the computer running PopChart Server (or the address of an HTTP
redirector). It also assumes that your server port is 2001. If you have changed your server
port, or are using a redirector, you will need to change or omit this number accordingly.
Note:
For those of you who are curious about what is going on here, we are requesting the
JavaScript Embedder from PopChart Server. PopChart Server will return a small (20k),
cacheable JavaScript file that contains the PopChart Embedder library.
4-5
.....
PopChart
4
6(5 9(5
DELIMITING THE CODE FOR YOUR
POPCHART IMAGE
..................................................
The next step, which is probably intuitive for experienced programmers, is to delimit the
code for our PopChart image. Using the JavaScript embedder, this simply means placing a
<script> tag in the location where we wish to embed our PopChart image.
In other words, you are creating a “shell” for your JavaScript code. Any remaining code
should be placed inside of this tag.
You should insert the following lines into your web page.
Example 4.1
JavaScript “Shell” to Embed a PopChart Image
<script language="JavaScript1.2">

</script>
4-6
www.corda.com
User Guide
.....
Just to make sure your following along, the image below shows you what the source for
your web page should look like after you insert the code we’ve given you so far.
The arrow indicates where you should place the rest of the code that we will give you in this
chapter.
4-7
.....
PopChart
4
6(5 9(5
Instantiating a PopChart Embedder Object
I N S T A N T I A T I N G A PopChart Embedder
OBJECT
..................................................
The next step is to instantiate, or create, a PopChart Embedder object.
Note:
For those of you unfamiliar with the concepts behind object-oriented programming, you
may find it helpful to read a quick primer on it, but you can probably get through this
chapter by just “winging it.”
To instantiate a PopChart Embedder object in JavaScript, you first need to decide on a
name for your object. The name is for programming purposes only—it will have no effect
on the final image. Throughout most of this documentation, we choose the name
myPopChart.
Then, we would use the following line to instantiate the object:
Of course, if you want to use a name other than myPopChart, you should change this line
accordingly.
So, thus far, you should have inserted the following code into the web page:
Example 4.2
Example Code After Instantiating a PopChart Embedder Object
</script>
4-8
www.corda.com
User Guide
.....
.S. E. .T. T. .I .N. G. . .T. H. . E. . .S. E. .R. V. .E. .R. . I.N. .F. O. .R. .M. .A. T. .I .O. N. . . . . . .
Note:
We do not need to do this for the JavaScript PopChart Embedder. For now you can skip
this section. However, you will need to complete this step for other versions of the
PopChart Embedder.
An important step in embedding a PopChart image is to tell the PopChart Embedder the
location of PopChart Server. With the JavaScript embedder, you have already done this
when you imported the PopChart Embedder library (you had to tell the web page where
to find PopChart Server in order to import the PopChart Embedder library).
With other versions of the PopChart Embedder, however, you need to set two PopChart
Embedder attributes, externalServerAddress and
internalCommPortAddress. To make sure you are aware of these attributes, we
introduce them now. However, you will not actually use them until Chapter 5.
EXTERNAL SERVER ADDRESS
The externalServerAddress attribute tells PopChart Embedder what address web
clients will use to access PopChart Server. Web clients will always access PopChart
Server on the server port, which by default is 2001. So, for example, if PopChart Server
is running on port 2001, and web servers access it via address
http://pcserver.mycompany.com, you would need to include the following line of code:
"http://pcserver.mycompany.com:2001";
Note:
If you are using the a redirector, your external server address will be the address of the
redirector. You should not include a port number when you use the redirector. For more
information, refer to the section entitled “Using HTTP Redirection” on page 12-2.
INTERNAL COMM PORT ADDRESS
The internalCommPortAddress attribute tells PopChart Embedder what address
PopChart Embedder should use to access PopChart Server. PopChart Embedder will
always access PopChart Server on the comm port, which by default is 2002.
The actual address of the PopChart Server is often the same as the address that you
specified as the external server address. If this is the case, then the following line of code
would accompany the line of code we used to set the external server address:
"http://pcserver.mycompany.com:2002";
4-9
.....
PopChart
4
6(5 9(5
However, it is not always the case that the web clients and the PopChart Embedder talk to
PopChart Server at the same address. Behind a firewall, or if you are using a redirector
(see Chapter 12) or clustering (see Chapter 13), PopChart Embedder may
communicate with PopChart Server at a different address. This address will depend
greatly upon how your PopChart Server is set up.
4-10
www.corda.com
User Guide
.....
.C. H. .O. .O. .S. I.N. .G. . A. .N. . .A. P. .P. .E.A. .R. A. . N. .C. .E. .F. I. L. .E. . . . . . . . . .
One of the most important steps to embedding a PopChart image is to tell PopChart
Server what appearance file it should be using. An appearance file is kind of like a template
that tells PopChart Server how to format a PopChart image. It already contains data, but
most of the time this data is just “filler” data—you will override it later on.
There are a number of example appearance files in the examples/apfiles directory of the
document root. For this example, we will use the bar.pcxml example appearance file.
To tell PopChart Server to use this appearance file, set the appearanceFile attribute
of the PopChart Embedder, as we have done below:
myPopChart.appearanceFile =
"examples/apfiles/bar.pcxml";
Note that the location of the appearance file should be relative to the document root
directory. Alternatively, you can use an absolute path or a URL. For example, suppose you
wanted to use an appearance file that is generated dynamically by a web application at
http://webapps.mycompany.com/graphgenerator?type=bar. You would use the
following line of code:
ABOUT APPEARANCE FILES
Appearance files are one of the most important elements in
PopChart images. They contain all of the information
about what the graphs should look like—essentially
providing PopChart Server with a template for the image
it should generate.
Appearance files contain sample data to help you get a feel
for what the graph will look like when it has real data in it.
To make things simple for now, we will just use that
sample data. In most cases, though, you will send live data
to PopChart Server, which will be applied dynamically
to the graphs in your appearance file. Although the data
will change, PopChart Server will retain the layout and
formatting options that you specified in your appearance
file.
You can create appearance files in PopChart Builder, an
easy to use designer for graph generation. You can create
an appearance file from scratch, or you can customize one
from a template using the PopChart Wizard.
There are also several example appearance files in the
examples/apfiles folder of your document root.
Appearance files are saved in a format called PopChart
XML (see Chapter 10). This is a text-based format that
you can easily manipulate in a text editor. In fact, with
PopChart XML you can even create appearance files
without PopChart Builder. PopChart XML is also
flexible enough to allow you to modify or create your
appearance file on the fly.
By default, PopChart Server expects to find its
appearance files in its document root (chart_root). For
organizational purposes, we recommend you keep them in
the apfiles subfolder of that directory. Appearance files
have a .pcxml extension.
You can also load appearance files from a URL. So, for
instance, you could use a web application server to
generate or customize your appearance files.
4-11
.....
PopChart
4
6(5 9(5
myPopChart.appearanceFile = "http://webapps.mycompany.
com/graphgenerator?type=bar";
However, be aware that if your appearance file resides anywhere other than the document
root directory, you must give PopChart Server permission to read from that location. For
more information, refer to the section entitled “Setting Path Permissions” on page 3-37.
After choosing an appearance file, you should have inserted the following code into your
web page:
Example 4.3
Example Code After Choosing an Appearance File
myPopChart.appearanceFile = "examples/apfiles/bar.pcxml";
</script>
4-12
www.corda.com
User Guide
.....
.C. H. .A. .N. G. . I.N. .G. . T. .H. .E. .I.M. .A. G. . E. . .F. O. .R. .M. .A. T. . . . . . . . . . . . .
Note:
This step is optional. If you do not set an image format, the default image format will be
used. For more information, refer to the section entitled “Changing Default Image
Settings” on page 3-27.
Next, you need to specify a format for your PopChart image. PopChart Server can serve
images in a variety of formats, including SVG™, Macromedia® Flash™, PNG, GIF, PDF,
EPS, and WBMP.
Note:
You will need PopChart Server Pro or PopChart Server Enterprise to generate any
format besides GIF or PNG. You will need PopChart Server Enterprise to generate PDF
or EPS.
For information about these image formats, refer to Chapter 14 of the PopChart Server
Reference manual.
To specify the image format, use imageType attribute of the PopChart Embedder, as we
have done below:
myPopChart.imageType = "FLASH";
The value that you should assign to imageType is an upper-case string containing the
format name. For example, we wanted a FLASH image, so we set this attribute to
"FLASH". Had we wanted a PDF image, we would have set it to "PDF".
BEST IMAGE FALLBACK
A major problem with embedding a PopChart image is deciding what image format you
should display it in. Naturally, most people prefer FLASH or SVG images to GIF and PNG.
But while the latter formats are almost universally supported, a browser must have a plug-in
to display FLASH or SVG images. While over 90% of today’s browser’s support the
FLASH plug-in, you would have to settle on the low-quality GIF format if you don’t want
to require clients to have a certain plug-in.
However, there is another option. PopChart Server’s Best Image Fallback feature allows
PopChart Server to serve PopChart images in the highest quality format that a client’s
browser currently supports.
For example, with best image fallback, if you’ve told PopChart Server to generate a
FLASH image, but a certain browser does not have the FLASH plug-in, PopChart Server
will automatically return a GIF image. Likewise, if you’ve told PopChart Server to
generate an SVG image, but a certain browser does not have the Adobe® SVG Viewer,
PopChart Server will automatically return a FLASH (or GIF) image.
4-13
.....
PopChart
4
6(5 9(5
Note:
Best Image Fallback does not apply to PDF, EPS, or WBMP images. You may also be
interested in the Automatic PNG Detection feature (refer to “Automatic PNG Detection”
on page 3-27), which returns a PNG instead of GIF image if a browser supports PNG.
To request best image fallback, use fallback attribute of the PopChart Embedder, as
we have done below:
myPopChart.fallback = "STRICT";
FALLBACK METHODS
There are three different methods of best image fallback. When you enable or disable
fallback, you will assign the fallback to one of these methods.
Strict fallback, for which you should assign fallback to “STRICT”,
instructs PopChart Server to only return an image in FLASH or SVG if the
browser has the appropriate plug-in.
STRICT
Loose fallback, for which you should assign fallback to “LOOSE”,
instructs PopChart Server to return an image in FLASH if the browser could
support the plug-in. This means the browser will download a plug-in if it is not
already installed. It works just like Strict fallback, however, in regards to SVG.
LOOSE
You can also set the fallback method to “NONE”, in which case best
image fallback will be disabled.
NONE
THE EXAMPLE CODE SO FAR
After setting the image format, you should have inserted the following code into your web
page:
Example 4.4
Example Code After Choosing an Appearance File
4-14
www.corda.com
User Guide
.....
</script>
4-15
.....
PopChart
4
6(5 9(5
.C. H. .A. .N. G. . I.N. .G. . T. .H. .E. .S. .I Z. .E. . O. . F. . Y. .O. .U. .R. .I.M. .A. .G. E. . . . . .
Note:
This step is recommended. If you do not set an image size, the size of the appearance file
will be used for GIF and PNG images. However, the default size of the plug-in (which is
usually smaller than you need) will be used for FLASH and SVG images.
The next step for embedding a PopChart image in your web page is to set the size of your
image. You do this by setting the height and width attributes of the PopChart
Embedder.
For example, if you wanted your embedded image to be 600 pixels wide and 400 pixels
high, you would use the following two lines of code:
myPopChart.height = 400;
myPopChart.width = 600;
Alternatively, if you want to set the size of the image to be a certain percentage of the web
page’s width and height, you can set the htmlHeight and/or the htmlWidth attribute.
For example, if we wanted the image to fill 75% of the web page’s width, you could use the
following command:
myPopChart.HTMLWidth = "75%";
Important:
The htmlHeight and htmlWidth attributes can also accept height and width values in
pixels, so be sure to use a percentage % sign to indicate that you are specifying a
percentage.
htmlHeight and htmlWidth do not change the size of the image that PopChart
Server generates, but they do tell the browser to scale the image to a certain size. Thus, you
may sometimes find it desirable to set height and width when you set htmlHeight
and htmlWidth.
After setting the image format, you should have inserted the following code into your web
page:
Example 4.5
Example Code After Setting the Image Size
4-16
www.corda.com
User Guide
.....
</script>
4-17
.....
PopChart
4
6(5 9(5
.C. U. .S. .T.O. .M. .I .Z. I.N. .G. . Y. .O. .U. R. . .P. .O. P. .C. .H. A. .R. .T. . . . . . . . . . . .
Now that you have set the basic attributes of your PopChart image, you are ready to
customize your image. You can customize your image by adding data, as well as features
like PopUp text and drill-down effects.
Later chapters will delve into these topics. For now—just for the sake of our example—we
will add only one customization. We will change the title of our text box to Hello World.
To do this, we will a send line of PopChart Script to PopChart Server. PopChart Script
(PCScript) is a scripting language that allows you to make last-second changes to an
appearance file. Chapter 5, “PCScript,” in the PopChart Server Reference manual
discusses PCScript in detail.
The following line of PCScript changes the text in our title box to Hello World.
title.setText(Hello World)
To send this PCScript command to PopChart Server, you would use the pcScript
attribute of the PopChart Embedder, as in the line of code below:
myPopChart.pcScript = "title.setText(Hello World)";
After adding this simple customization, you should have inserted the following code into
your web page:
Example 4.6
Example Code After Customization
</script>
4-18
www.corda.com
User Guide
.....
WRITING THE IMAGE TO YOUR WEB
PAGE
..................................................
The final step in embedding your PopChart image is to write it to your web page. PopChart
Embedder’s getEmbeddingHTML() method will return a string that contains all of the
HTML and/or JavaScript code necessary to embed the PopChart image into your web page.
All you have to do is write this string to the web page.
Of course, how you write the getEmbeddingHTML() string your web page will depend
on your programming environment. As we mentioned in “Introducing the PopChart
Embedder” on page 4-2, this chapter focuses on the JavaScript emebedder. To learn how to
import the PopChart Embedder library for your programming environment, refer to
Chapter 5, “Using PopChart Embedder.”
To write the embedding HTML to your web page in JavaScript, all you need to do is wrap
the getEmbeddingHTML() method call in a document.write() statement, as we
have done in the line of code below.
document.write(myPopChart.getEmbeddingHTML());
After inserting this line of code into your web page, you will have all the code necessary to
embed your PopChart image.
Example 4.7
Complete Example Code
document.write(myPopChart.getEmbeddingHTML());
</script>
4-19
.....
PopChart
4
6(5 9(5
Note:
If you want to align your PopChart image (e.g. align="center", align="right"),
you should surround this code with a <div> tag, and set the align attribute in the <div>
tag.
The image below shows what the source for the example web page should look like once
you have inserted this code.
4-20
www.corda.com
User Guide
.....
This final image shows the resulting web page.
4-21
.....
PopChart
4
6(5 9(5
For your convenience, this HTML page is saved as example1.html in the
examples/code/JavaScript folder.
Congratulations! You have just created your first PopChart image. In the next few chapters
you will learn how to add dynamic data and special effects to this image.
4-22
www.corda.com
U SING PopChart Embedder
T
.....
...................................
5
his chapter discusses the PopChart Embedder, a utility that helps you embed
PopChart images into web pages. There are several versions of this utility, including Java,
JavaBeans, JavaScript, and COM.
In Chapter 4, we introduced you to the PopChart Embedder and embedded a PopChart
image using the JavaScript version of the PopChart Embedder. In this chapter, you will
learn how to use the PopChart Embedder in a variety of environments. For each
environment, we will show you how to migrate the code from Example 4.7 to the new
environment.
Since you are probably going to use the PopChart Embedder in only one programming
environment, you most likely won’t want to read this entire chapter. You may find it
beneficial to read the first section, “About the PopChart Embedder,” but it is not required.
After that, you should skip ahead to the section appropriate for your environment.
This chapter discusses using the PopChart Embedder in the following environments:
• JavaScript
• Java Server Pages
• Java Server Page with JavaBeans
• Java Servlets
• Active Server Pages
• ASP.NET
• ColdFusion
• PHP
5-1
.....
PopChart
5
6(5 9(5
U S I N G PopChart Embedder
If you are looking for a comprehensive reference for the PopChart Embedder API, you
should refer to Chapter 4 of the PopChart Server Reference manual.
T I P : U S I N G PopChart Builder T O G E N E R A T E PopChart Embedder C O D E
One of the many convenient features of PopChart Builder
is that it will automatically generate code to embed a
PopChart image for you. Simply load or create an
appearance file, select File > Sample Code, and
choose the version of PopChart Embedder that you will
be using. A dialog with sample PopChart Embedder
code that you can copy will pop up.
In this dialog, you have a variety of choices. You can
generate example code for a variety of environments,
including JSPs, ASPs, Servlets, JavaBeans, JavaScript,
PHP pages, and just straight HTML. The dialog also
5-2
allows you to specify important variables, such as
PCScript and your server address.
In some cases, you can cut and paste this example code
directly into a file on your web server and have it work
immediately. Most of the time, though, you’ll want to
customize this code further before publishing your
PopChart image.
Either way, the sample code can save you a lot of time.
And, of course, it’s a great learning tool.
www.corda.com
User Guide
.....
.A. B. .O. .U. .T. .T. H. .E. . PopChart
. . . . . . . . . .Embedder
.........................
One of the PopChart Server’s best features is that the images it generates can be
embedded into a web page using HTML—a technology so simple that pretty much any
graphically based browser can display PopChart images. No special plug-ins or applets are
required.
Of course, having just embedded a PopChart image in the previous chapter using
JavaScript, a more savvy web programmer might dispute our claim to be based entirely on
HTML. However, all that the JavaScript PopChart Embedder did was generate the
appropriate HTML to embed your PopChart image.
For example, we could have generated the PopChart image from Example 4.7 using the
following HTML:
Example 5.1
HTML Code for Embedding a PopChart Image
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
codebase="http://download.macromedia.com/pub/shockwa
ve/cabs/flash/swflash.cab#version=4,0,0,0"
border="0" width="600" height="400" >
<param name="MOVIE"
value="http://localhost:2001/?@_FILEexamples/apfiles
/bar.pcxml@_HEIGHT400@_WIDTH600@_PCSCRIPTtitle.setTe
xt(Hello%20World)@_FLASH">
<img width="600" height="400"
src="http://localhost:2001/?@_FILEexamples/apfiles/b
ar.pcxml@_HEIGHT400@_WIDTH600@_PCSCRIPTtitle.setText
(Hello%20World)@_GIF">
</object>
After sitting down for a minute or two and trying to decipher this code, most programmers
will agree that the code from JavaScript PopChart Embedder is a lot more straightforward
and manageable. In case you are not convinced, quickly glance through some of the
example code in Chapter 11, “Getting PopChart Images with HTTP Requests,” which
teaches you how to embed PopChart images using straight HTML.
Writing and maintaining such code can be very tedious and confusing. That’s why we
created the PopChart Embedder to generate this code for you. All you have to do is create
a PopChart Embedder object, set a few attributes, and then call the
getEmbeddingHTML() method. The getEmbeddingHTML() method then
“compiles” your PopChart and returns the code necessary to request an image of the
PopChart from PopChart Server.
5-3
.....
PopChart
5
6(5 9(5
Note:
It is not entirely accurate to say that the JavaScript Embedder translates the code from
Example 4.7 to the HTML in Example 5.1. For more information, refer to the section
entitled “How Does it Work?” on page 5-6.
PopChart Embedder O N T H E S E R V E R - S I D E
While the JavaScript PopChart Embedder works on the client-side to generate embedding
HTML, most web developers generate their web pages dynamically on the server-side,
especially when they publish live data from a database. In these circumstances, it makes
much more sense to use a server-side version of the PopChart Embedder.
The server-side version of PopChart Embedder is available in the following formats:
Java, JavaBean, and COM (Component Object Model). It can be used in a variety of
environments, including Java Server Pages, Active Server Pages, Java Servlets, and
ColdFusion.
Note:
The Java and JavaBean versions of PopChart Embedder are only available in PopChart
Server Pro and PopChart Server Enterprise.
By providing you with a native interface for embedding PopChart images, the PopChart
Embedder helps separate content from presentation. You don’t have to worry about HTML
code, because the PopChart Embedder does this for you. Beyond that, using the
PopChart Embedder on the server-side provides additional flexibility, such as importing
from a database and adding HTML Tables.
Example 5.9 illustrates how embedding images with a server-side version of the PopChart
Embedder typically works.
Example 6
5-4
PopChart Embedder Process Flow
www.corda.com
User Guide
.....
This process can be broken down into the following steps:
1
The Web Application Server (or PopChart Embedder) retrieves data from the database.
2
Using the PopChart Embedder, the Web Application Server sends data and other
instructions to PopChart Server.
3
PopChart Server stores the data and instructions and sends back the HTML necessary
to embed a PopChart image. This HTML consists of an <object>, <embed>, or <img>
tag whose URL source instructs the browser to get a specific reference (key) from
PopChart Server.
4
The Web Application Server builds an HTML page that, integrating the HTML that
PopChart Server returned, embeds the PopChart image.
5
The HTML page is served to the web client (browser).
6
Seeing the appropriate tag in the HTML page, the browser requests an image from
PopChart Server.
7
PopChart Server uses the reference (key) from the browser’s request to look up the
stored data and instructions and create a PopChart image. This image is then returned
to the browser.
8
The browser displays the PopChart image.
5-5
.....
PopChart
5
6(5 9(5
JavaScript
.J.A. .V. A. .S. .C. R. .I.P. T. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The JavaScript PopChart Embedder is new to PopChart Server 4.0. It provides you
with a convenient interface for embedding PopChart images directly into your web page,
without the use of a web application server.
All you have to do is load the PopChart Embedder library via a <script> tag in your
document header, and then place your PopChart Embedder code inside of a <script>
tag wherever you want your PopChart image.
Because Chapter 4 is based entirely on the JavaScript PopChart Embedder, we will not
repeat embedding instructions in this section. You should read Chapter 4 to learn how to
embed PopChart images with the JavaScript PopChart Embedder.
JAVASCRIPT EMBEDDER LIMITATIONS
Because of the nature of JavaScript, the JavaScript embedder is somewhat limited. For the
most part, it is provided to help you learn how to use PopChart Server more quickly. It
should not be used in a production environment.
Limitations when using the JavaScript PopChart Embedder include:
• Higher server-load and bandwidth usage.
• PCScript command strings longer than 256 bytes may cause the browser to be unable to
load a PopChart image.
• Unable to import data directly from a database (no setDBQuery() support).
• Unable to show HTML tables (addHTMLTable(String,String) does not work).
• The addPCXML() and setData() methods are not supported.
Additionally, the JavaScript PopChart Embedder has not been tested as extensively as the
other PopChart Embedders.
HOW DOES IT WORK?
For most users, the answer to this question is that it doesn’t matter. However, since the
JavaScript embedder works somewhat differently than the server-side PopChart
Embedders, more advanced users may find it helpful to know exactly what is going on.
When you import the JavaScript embedder library using the <script> tag, you are
essentially telling the web browser to ask PopChart Server for a JavaScript file. PopChart
Server sees the request for jsEmbedder and internally loads a JavaScript file (PopChart
Server has to process the file before returning it to the client).
5-6
www.corda.com
User Guide
.....
JavaScript
Note:
This file is about 20K in size. It is cacheable, so the browser will only need to download it
the first time it displays a PopChart image.
The file that PopChart Server loads depends on what edition you are running. For the
standard edition of PopChart Server, this file is the lib/gifonly.js file. For PopChart
Server Enterprise and PopChart Server Pro, this file is lib/fallback.js. PopChart
Server makes a couple of macro substitution to the &host;, &bVersion;,
&bVersion;, and &bVersion; entities (if they exist), and then serves the resulting file
to the web browser.
Note:
More adventurous users can even try customizing these files for their own needs. One
possible customization is to substitute &host; with PopChart Server’s server address,
and then serve the embedder directly from your web server. This way, the only file that
actually has to know the location of PopChart Server is your JavaScript embedder. You
will need to restart PopChart Server, though, after customizing this file.
The web browser, which will wait to process any further JavaScript commands until it
receives the JavaScript file, processes the file as soon as it is returned. The web browser will
then proceed to process other segments of JavaScript.
When you call the getEmbeddingHTML() method, PopChart Server will “compile”
your PopChart image into another <script> tag. This tag is in the form:
<script language=”JavaScript1.2"
src="http://server_address/?@_JSserver_commands">
</script>
The web browser will write this to the document and continue processing any JavaScript
statements it sees until it reaches a </script> tag. Then, it will process the <script>
tag that getEmbeddingHTML() returned. This tag again requests a JavaScript file from
PopChart Server. This time, PopChart Server will see the @_JS server command and
recognize that it should return a JavaScript file that will write the HTML appropriate for
embedding the PopChart image.
After this file is returned to the web browser, the web browser processes it, resulting in an
<object>, <embed>, or <img> tag being written to the web page. From here on out, the
process is very much like the process for server-side PopChart Embedders, beginning
with Step 6.
5-7
.....
PopChart
5
6(5 9(5
Java Server Pages
.J.A. .V. A. . .S. E. .R. .V. E. .R. . P. .A. .G. .E.S. . . . . . . . . . . . . . . . . . . . . . . . .
When you embed a PopChart image in a Java Server Page (JSP), you will use either the Java
PopChart Embedder or the JavaBean PopChart Embedder. This section assumes you
are using the Java PopChart Embedder. The next section will discuss the use of the
JavaBean PopChart Embedder.
For the most part, the code that you will use for embedding a PopChart image into a Java
Server Page with Java is exactly the same as the code you created for the JavaScript
embedder in Chapter 4. This section will explain the major differences. Example 5.1 at
the end of this section shows you how the web page from Example 4.7 would look as a
Java Server Page.
Note:
This documentation assumes that if you want to embed a PopChart image in a Java Server
Pages, you have already set up a Java-extensible web application server, and that you
already know how to create a basic Java Server Page. If this is not the case, you may wish to
set up a web application server and brush up on Servlets before continuing.
IMPORTING THE LIBRARY
Before you can import the PopChart Embedder library into a Java Server Page, you must
first make sure that the PopChartEmbedder.jar file, located in the
dev_tools/java_embedder folder, is in the classpath for your web application. If you do
not know how to add a Jar file to your web application’s classpath, refer to “Including the
PopChartEmbedder.jar File in Your Classpath” on page 5-46.
To import the PopChart Embedder library, include the following line at the beginning of
your Java Server Page.
<%@ page import="com.corda.pcis.PopChartEmbedder" %>
This instructs the web application to load the PopChartEmbedder class.
DELIMITING THE CODE FOR YOUR POPCHART
IMAGE
You delimit Java code for your PopChart image with <% and %> (open angle bracketpercent sign, percent sign-closing angle bracket), as in the following code segment:
5-8
www.corda.com
User Guide
.....
Java Server Pages
<%
myPopChart.appearanceFile = "apfiles/line.pcxml";
myPopChart.loadPCXML("http://myserver.com/?graph1");
%>
I N S T A N T I A T I N G A PopChart Embedder O B J E C T
To instantiate a PopChart Embedder object, you should use the following line of code
(this assumes that you want to name your object myPopChart).
PopChartEmbedder myPopChart = new PopChartEmbedder();
SETTING THE SERVER INFORMATION
As mentioned in “Setting the Server Information” on page 4-9, non-JavaScript versions of
PopChart Embedder require you to tell them the location of PopChart Server. You need
to set two values: the address that the web client will use to access PopChart Server
(externalServerAddress), and the address that PopChart Embedder uses to access
PopChart Server (internalCommPortAddress).
These are not the same addresses. First of all, PopChart Embedder uses a different port to
communicate with PopChart Server. This port is known as the comm port, and, unless you
change it, is set to 2002. Second of all, if you are using a firewall or a redirector, PopChart
Server’s address will be different for the web client than for the PopChart Embedder.
For example, if you are running PopChart Server at 10.0.1.1, but your web clients request
images from http://popchart.mycompany.com, you need to include the following lines of
code in the code that generates your PopChart image:
"http://popchart.mycompany.com:2001";
myPopChart.internalCommPortAddress = "10.0.1.1:2002";
SETTING THE USER AGENT
When you use the JavaScript PopChart Embedder, it automatically tells PopChart
Server what the web client’s user agent is. However, server-side PopChart Embedders
can only tell PopChart Server a client’s user agent if you specifically pass this information
on to PopChart Embedder using the userAgent attribute. This information is
significant because if PopChart Server knows what browser a client is using, it can return
optimized (i.e. shorter and without JavaScript) HTML for embedding the PopChart image.
5-9
.....
PopChart
5
6(5 9(5
Java Server Pages
Server-side PopChart Embedders can only tell PopChart Server a client’s user agent if
you specifically pass this information on to PopChart Embedder using the userAgent
attribute. The following line of code shows how to do this with the Java PopChart
Embedder.
myPopChart.userAgent = request.getHeader("USERAGENT");
It is not necessary to tell PopChart Embedder the client’s user agent; however, you will
not be able to take advantage of optimized HTML if you do not do this.
WRITING THE IMAGE TO YOUR WEB PAGE
When you are ready to actually write your embedding HTML to the web page, you will
need to place the following code segment at the location in your Java Server Page where
you want the PopChart image to appear.
<%= myPopChart.getEmbeddingHTML() %>
Note that it is opened with a <%= instead of just <%. The equals sign instructs the
application server to write a string to the web page, which in this case is
myPopChart.getEmbeddingHTML(). There should be nothing else between the
opening and closing angle brackets, as the web application server expects only a string, not
a code segment.
Note:
WebObjects® Users: You should bind this return value to a WOString. In your .wod file
you must make sure that you include the following line in your WOString declaration:
escapeHTML = NO. Otherwise the HTML codes will be converted to escape characters.
COMPLETE EXAMPLE CODE
The following Java Server Page will produce exactly the same results as the page you
created in Chapter 4.
Example 5.1
Embedding a PopChart Image in a Java Server Page
<%@ page language="java" contentType="text/html" %>
<%@ page import="com.corda.pcis.PopChartEmbedder" %>
<%
myPopChart.externalServerAddress = "localhost:2001";
myPopChart.internalCommPortAddress = "localhost:2002";
5-10
www.corda.com
User Guide
.....
Java Server Pages
myPopChart.userAgent = request.getHeader("USER-AGENT");
%>
<html>
<head>
<title>My First Embedded PopChart</title>
</head>
<body>
<h1>This is a PopChart Image</h1>
<hr>

<hr>
<p>If you see an image above, congratulations. You have
successfully embedded your first PopChart image.</p>
</body>
</html>
5-11
.....
PopChart
5
6(5 9(5
Java Server Page with JavaBeans
.J.A. .V. A. . .S. E. .R. .V. E. .R. . P. .A. .G. .E. .W. .I.T. H. . .J. A. .V. .A. B. .E. .A. N. .S. . . .
When you use the PopChart Embedder with JavaBeans, the code for embedding a
PopChart image into a Java Server Page (JSP) looks dramatically different. However, it is
actually very similar to the Java code. PopChart Embedder attributes and methods are
simply converted to JavaBean setter and getter properties.
This section will help you learn how to use the JavaBean PopChart Embedder. Example
5.3 at the end of this section shows you how the web page from Example 4.7 would look
using JavaBeans in a Java Server Page.
Although we will show you how to convert some of the more common attributes and
methods to a JavaBean syntax (and we hope that the conversion process is intuitive), if you
need to find the JavaBean equivalent of any statement, you can look at the JavaBean
Syntax under the corresponding attribute or method description in Chapter 4 of the
Note:
This documentation assumes that if you want to embed a PopChart image with JavaBeans,
you have already set up a Java-extensible web application server, and that you already
know how to use JavaBeans. If this is not the case, you may wish to set up a web application
server and learn JavaBeans before continuing.
C O N V E R T I N G T H E PopChart Embedder T O A
JAVABEAN SYNTAX
One of the key differences between the JavaBean PopChart Embedder is the syntax.
Because the syntax is so different, you will be unable to simply cut and paste most of the
example code from this documentation into a JSP with JavaBeans. Fortunately, this
subsection will help you learn how to convert the examples to the syntax.
SETTER PROPERTIES
Any PopChart Embedder attribute can be converted to a JavaBean setter property. To
convert the attribute, create a JSP:setProperty tag. Assign the name attribute of this
tag to the name of your PopChart Embedder object. Assign the property attribute of
this tag to the PopChart Embedder attribute that you want to set. Finally, assign the
value attribute of this tag to the value that you want to give the PopChart Embedder
attribute.
For example, consider the appearanceFile attribute, which would normally be used
like this:
myPopChart.appearanceFile = "pie.pcxml";
This attribute becomes the following setter property in the JavaBean:
5-12
www.corda.com
User Guide
.....
<JSP:setProperty name="myPopChart"
property="appearanceFile" value="pie.pcxml" />
Any PopChart Embedder that accepts zero or one parameters can be converted to setter
properties in the same fashion. If the method accepts one parameter, that parameter becomes
the JSP:setProperty tag’s value attribute. Otherwise, the value attribute should be
ignored.
For example, consider the loadPCXML(String) method, which would normally be used
like this:
myPopChart.loadPCXML(data/may.pcxml);
This method becomes the following setter property in the JavaBean:
<JSP:setProperty name="myPopChart"
property="loadPCXML" value="data/may.pcxml" />
GETTER PROPERTIES
Any PopChart Embedder method that returns a value can be converted to a getter method.
To convert the method, create a JSP:getProperty tag. Assign the name attribute of
this tag to the name of your PopChart Embedder object. Assign the property attribute
of this tag to the PopChart Embedder method that you want to use, except that you should
remove the get from the method’s name.
For example, consider the getEmbeddingHTML() method, which would normally be
used like this:
String pcHTML = myPopChart.getEmbeddingHTML();
This method becomes the following getter property in the JavaBean:
<JSP:getProperty name="myPopChart"
property="embeddingHTML" />
You do not need to import the PopChart Embedder library into a Java Server Page if you
are using JavaBeans. however, you must make sure that the PopChartEmbedder.jar file,
located in the dev_tools/java_embedder folder, is in the classpath for your web
application. If you do not know how to add a Jar file to your web application’s classpath,
refer to “Including the PopChartEmbedder.jar File in Your Classpath” on page 5-46.
5-13
.....
PopChart
5
6(5 9(5
IMAGE
JavaBean commands are designed to look like regular HTML tags. Because of this, there is
no special way of delimiting the code that embeds your PopChart image. You simply throw
the JavaBean code directly into the JSP.
To instantiate a PopChart Embedder object, you should use the following JavaBean tag
<jsp:useBean id="myPopChart" scope="page"
class="com.corda.bean.PopChartEmbedderBean" />
images from http://popchart.mycompany.com, you need to include the following lines
tags:
<jsp:setProperty name="myPopChart"
property="externalServerAddress"
value="http://popchart.mycompany.com:2001" />
property="internalCommPortAddress"
value="10.0.1.1:2002" />
5-14
www.corda.com
User Guide
.....
When you use the JavaScript PopChart Embedder, it automatically told PopChart
Server what the web client’s user agent was. However, server-side PopChart Embedders
The following line of code shows how to do this with the JavaBean PopChart Embedder.
property="userAgent"
value="<%=request.getHeader(\"user-agent\")%>" />
MISCELLANEOUS DIFFERENCES
There are certain Java methods that are unavailable in a JavaBean syntax. These are as
follows:
•
•
•
•
•
void addHTMLTable(String,String)
void loadData(String,String,String,String)
void saveImageToAppServer(String, String)
void setDBQuery(String, String, String, String, String, String)
void setResultSet(String,ResultSet)
You can still take advantage of these functions, but you must use Java code, as described in
the previous section, “Java Server Pages.” The name that you gave the object (e.g.
myPopChart) when you initialized it will be the same as the name you use to access its
Java methods.
Example 5.2 shows how JavaBean and Java code can be mixed together.
Example 5.2
Mixed JavaBean and Java Code
value="localhost:2001" />
5-15
.....
PopChart
5
6(5 9(5
<jsp:setProperty name="myPopChart" property="appearanceFile"
value="examples/apfiles/bar.pcxml" />
<%
myPopChart.loadData("graph", "data/data1.csv");
myPopChart.addHTMLTable("graph");
%>
<jsp:getProperty name="myPopChart" property="embeddingHTML" />
need to place the following code segment at the location in your Java Server Page where
you want the PopChart image to appear.
Note that it is opened with a <%= instead of just <%. The equals sign instructs the
application server to write a string to the web page, which in this case is
myPopChart.getEmbeddingHTML(). There should be nothing else between the
opening and closing angle brackets, as the web application server expects only a string, not
a code segment.
Note:
WebObjects Users: You should bind this return value to a WOString. In your .wod file you
must make sure that you include the following line in your WOString declaration:
escapeHTML = NO. Otherwise the HTML codes will be converted to escape characters.
The following Java Server Page will produce exactly the same results as the page you
Example 5.3
Embedding a PopChart Image with JavaBeans
<%@ page language="java" contentType="text/html" %>
<html>
<head>
</head>
5-16
www.corda.com
User Guide
.....
<body>
<hr>
<jsp:setProperty name="myPopChart" property="appearanceFile"
value="examples/apfiles/bar.pcxml" />
<jsp:setProperty name="myPopChart" property="imageType"
value="FLASH" />
<jsp:setProperty name="myPopChart" property="fallback"
value="STRICT" />
<jsp:setProperty name="myPopChart" property="imageType"
value="FLASH" />
<jsp:setProperty name="myPopChart" property="width"
value="600" />
<jsp:setProperty name="myPopChart" property="height"
value="400" />
<jsp:setProperty name="myPopChart" property="pcScript"
value="title.setText(Hello World)" />
<jsp:setProperty name="myPopChart" property="userAgent"
value="<%=request.getHeader(\"user-agent\")%>"
/>
<jsp:getProperty name="myPopChart" property="embeddingHTML" />
<hr>
</body>
</html>
5-17
.....
PopChart
5
6(5 9(5
Java Servlets
.J.A. .V. A. . .S. E. .R. .V. L. .E. T. .S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
For the most part, the code that you will use for embedding a PopChart image into a Java
Servlet is exactly the same as the code you created for the JavaScript embedder in
Chapter 4. This section will explain the major differences. Example 5.4 at the end of this
section shows you how the web page from Example 4.7 would look as a Java Servlet.
Note:
This documentation assumes that if you want to embed a PopChart image in a Java Servlet,
you have already set up a Java-extensible web application server, and that you already
know how to create a basic Java Servlet. If this is not the case, you may wish to set up a web
application server and brush up on Servlets before continuing.
Before you can import the PopChart Embedder library into a Java Servlet, you must first
make sure that the PopChartEmbedder.jar file, located in the dev_tools/java_embedder
folder, is in the classpath for your web application. If you do not know how to add a Jar file
to your web application’s classpath, refer to “Including the PopChartEmbedder.jar File
in Your Classpath” on page 5-46.
To import the PopChart Embedder library, include the following line at the beginning of
your Servlet.
import com.corda.pcis.PopChartEmbedder;
This instructs the Servlet to import the PopChartEmbedder class.
5-18
www.corda.com
User Guide
.....
Java Servlets
attribute. The following line of code shows how to do this with the Java PopChart
Embedder.
need to output the getEmbeddingHTML() method to the web page. For example, this is
often times done with a PrintWriter object. If you have instantiated a PrintWriter
object named pw, you would use the following line of code to output the embedding HTML
pw.println(myPopChart.getEmbeddingHTML());
5-19
.....
PopChart
5
6(5 9(5
Java Servlets
The following Java Servlet will produce exactly the same results as the page you created in
Chapter 4.
Example 5.4
Embedding a PopChart Image in a Java Servlet
import
import
import
import
import
java.text.*;
java.io.*;
javax.servlet.*;
javax.servlet.http.*;
com.corda.pcis.PopChartEmbedder;
public class ServletExample1 extends HttpServlet
{
public void init(ServletConfig config)
throws ServletException
{
super.init(config);
}
public void doPost(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException
{
doGet(request, response);
}
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException
{
response.setContentType("text/html");
PrintWriter pw = response.getWriter();
try
{
"http://localhost:2001";
"http://localhost:2002";
5-20
www.corda.com
User Guide
.....
Java Servlets
pw.println(myPopChart.getEmbeddingHTML());
}
catch(Exception exc)
{
pw.println("Error generating image.");
}
}
}
Note:
This code catches any exceptions that may be generated as you embed the PopChart image.
You do not have to do this. The PopChart Embedder itself does not throw any exceptions.
However, the PrintWriter or the request object might throw an exception, so you
might want to catch it. Besides, it’s good coding practice to catch exceptions.
5-21
.....
PopChart
5
6(5 9(5
Active Server Pages
.A. C. .T. .I V. .E. . S. .E. .R. V. .E. R. . .P. .A. G. .E. .S. . . . . . . . . . . . . . . . . . . . . .
You can embed a PopChart image into an Active Server Page (ASP) using the Component
Object Model (COM) version of the PopChart Embedder.
For the most part, the code that you will use for embedding a PopChart image into an Active
Server Page is exactly the same as the code you created for the JavaScript embedder in
Chapter 4. This section will explain the major differences. Example 5.5 at the end of this
section shows you how the web page from Example 4.7 would look as an Active Server
Page.
Note:
This documentation assumes that if you want to embed a PopChart image in an Active
Server Page, you already know how to use them. If this is not the case, you may wish to
brush up on Active Server Pages before continuing.
INSTALLING THE COMPONENT
Important:
If you have re-installed PopChart Server since version 4.0.3, please ignore this step. The
PopChart Embedder COM Component has been installed automatically for you.
Before you can use the PopChart Embedder in an Active Server Page, you must first
make sure that the PCEmbedder.dll file, located in the dev_tools/COM_embedder
folder, is installed as a component service. If you do not know how to install a component to
your component services, refer to “Installing the COM PopChart Embedder as a
Component Services” on page 5-53.
After you have installed PopChart Embedder to your server’s component services, you
don’t need to do anything else to use the PopChart Embedder in an ASP.
IMAGE
You delimit code for your PopChart image with <% and %> (open angle bracket-percent
sign, percent sign-closing angle bracket), as in the following code segment:
<%
myPopChart.appearanceFile = "apfiles/line.pcxml"
myPopChart.loadPCXML("http://myserver.com/?graph1")
%>
5-22
www.corda.com
User Guide
.....
Active Server Pages
set myPopChart =
Server.CreateObject("PopChart.Embedder")
"http://popchart.mycompany.com:2001"
myPopChart.internalCommPortAddress = "10.0.1.1:2002"
attribute. The following line of code shows how to do this with in an ASP
myPopChart.userAgent =
Request.ServerVariables("HTTP_USER_AGENT")
5-23
.....
PopChart
5
6(5 9(5
Active Server Pages
In addition to the afore-mentioned differences, you should be aware of the following issues
when you use Active Server Pages.
NUMBER OF PARAMETERS NOT OPTIONAL
Due to limitations in the Component Object Model, we are unable to set default values for
any parameters in the COM PopChart Embedder. Because of this, any methods which
normally have optional parameters will require those parameters in the COM PopChart
Embedder.
At this time, the only two methods this effects are
loadData(String,String,String,String) and
addHTMLTable(String,String).
For loadData(), if you don’t need to set the last two parameters, set the third argument
to “replace” and the fourth argument to an empty string (e.g
loadData("graph","prices.csv","replace","")).
For addHTMLTable(), simply give your table a title, or set the last argument to an empty
string addHTMLTable("graph","").
NO SEMI-COLONS AT THE END OF LINES
Note:
This applies to Active Server Pages, not to the COM PopChart Embedder in General.
Active Server Pages use VBScript, whose syntax requires that you do not have a semi-colon
at the end of a line of code. Since other languages either require a semi-colon, or are
indifferent, most of the example code in this documentation uses a semi-colon at the end of
each line of code. You should be careful to remove any semi-colons from example code if
you use it in an ASP.
For example, this line of code is invalid in an ASP:
myPopChart.appearanceFile="bar.pcxml";
This line of code is valid:
myPopChart.appearanceFile="bar.pcxml"
NO PARENTHESIS AROUND FUNCTIONS THAT DO NOT
RETURN VALUES
Note:
5-24
www.corda.com
User Guide
.....
Active Server Pages
VBScript syntax also requires any functions that do not return a value (void methods) to
not have parentheses around the parameters.
For example, we show the addHTMLTable() syntax to be:
myPopChart.addHTMLTable("graph","title");
This is perfectly valid in every language except VBScript. So in ASPs, you would need to
use the following syntax:
myPopChart.addHTMLTable "graph", "title"
For most ASP developers this will be a very obvious conversion process.
need to output the getEmbeddingHTML() method to the ASP. To do this, use the
Response.Write command, as shown below.
Response.Write myPopChart.getEmbeddingHTML()
The following Active Server Page will produce exactly the same results as the page you
Example 5.5
Embedding a PopChart Image in an Active Server Page
<html>
<head>
</head>
<body>
<hr>
<%
set myPopChart = Server.CreateObject("PopChart.Embedder")
myPopChart.externalServerAddress="localhost:2001"
myPopChart.internalCommPortAddress = "localhost:2002"
myPopChart.appearanceFile = "examples/apfiles/bar.pcxml"
myPopChart.imageType = "FLASH"
5-25
.....
PopChart
5
6(5 9(5
Active Server Pages
myPopChart.fallback = "STRICT"
myPopChart.width = 600
myPopChart.height = 400
myPopChart.pcScript = "title.setText(Hello World)"
myPopChart.userAgent = Request.ServerVariables("HTTP_USER_AGENT")
%>
<hr>
</body>
</html>
5-26
www.corda.com
User Guide
.....
ASP.NET
.A. S. .P. .. N. .E. .T. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
You can embed a PopChart image into an ASP.NET web application using the .NET version
of the PopChart Embedder. The .NET version of the PopChart Embedder is written in
C#. However, it can be used with both C# and Visual Basic. This section will give code
examples for both.
For the most part, the code that you will use for embedding a PopChart image into an
ASP.NET web application is exactly the same as the code you created for the JavaScript
embedder in Chapter 4. This section will explain the major differences. Example 5.7 and
Example 5.8 at the end of this section show you how the web page from Example 4.7
would look as an ASP.NET web application.
Note:
This documentation assumes that if you want to embed a PopChart image with .NET, you
already know enough about .NET to create a basic web application. If this is not the case,
you may wish to brush up on .NET before continuing.
REFERENCING THE LIBRARY
Before you can use the PopChart Embedder in a web application, you must first add a
reference to the PopChart Embedder .NET library.
T o a d d a r e fe r en c e t o PCNetEmbedder.dll
1
Open the web application into which you will be embedding your PopChart.
You will need to add a reference to the PopChart Embedder library for every web
application that uses the PopChart Embedder.
2
Select Project > Add Reference.
3
Be sure that the .NET tab is selected, and then click the Browse... button.
4
Locate the PCNetEmbedder.dll file, select it, and then click OK.
5
The PopChart component should now be listed in the Selected Components box.
This file is located in the dev_tools/dotnet_embedder folder of your installation.
Click OK to finish adding the reference.
IMPORTING THE NAMESPACE
After you have referenced the PopChart Embedder library, you will need to import the
PCNetEmbedder namespace into any C# (.cs) or Visual Basic (.vb) files in your web
application that will contain PopChart Embedder code.
5-27
.....
PopChart
5
6(5 9(5
ASP.NET
C#
To import the PCNetEmbedder namespace in C#, you should use the using directive.
Typically, at the top of a C# file, there will already be a list of using directives. Simply at
the following directive at the bottom of the list:
using PCNetEmbedder;
VISUAL BASIC
To import the PCNetEmbedder namespace in Visual Basic, simply place an import
statement at the top of the file, as illustrated below:
Imports PCNetEmbedder
PLACING A CONTROL IN YOUR WEB FORM
As you probably already know, ASP.NET pages consists of two separate files: the layout file
(the .aspx file), and the class file (the .vb or .cs file). Your layout (.aspx) file specifies
information about the layout of controls and components within the page, as well as static
HTML. The class (.cs or .vb) file contains any code that will be used within the page.
When you embed a PopChart into an ASP.NET page, you will need to modify both of these
files. In the layout (.aspx) file, you will place a control to contain your PopChart. In the
class (.cs or .vb) file, you will place all of your PopChart Embedder code.
For the purposes of this example, we will simply use a generic HTML control to embed our
PopChart—the <div> tag. It is easiest to just insert this tag directly into the HTML source
code for the web form.
You can also create your own controls, such as the PopChart Web Server Control, discussed
in Appendix B, “Using The PopChart Web Server Control.”
Note:
There are many other ways of embedding a PopChart image into a web page that do not use
controls, including simply outputting getEmbeddingHTML() through
Response.Write. To keep things simple, this section focuses only on embedding your
PopChart within an HTML control.
T o p la c e a co n t ro l f or y o u r P o p C ha r t im ag e in t h e w e b f o rm
1
Open the layout (.aspx) file for the ASP.NET page where you will be adding your
PopChart.
2
Select View > HTML Source.
3
Locate the place within your web page where you want to place the PopChart image.
4
Add the following tag:
<div id="PopChart1" runsat="server"></div>
5-28
www.corda.com
User Guide
.....
ASP.NET
The id attribute may be set to anything, as long as no other control has the same id. For
the purposes of this example, we have chosen PopChart1. The runsat="server"
attribute is required.
Example 5.6 shows what our .aspx file would look like if we were to add this tag to an
ASP.NET page similar to the web page shown in “The Example Web Page” on page 4-3.
Example 5.6
Example .aspx File
<%@ Page language="c#" Codebehind="WebForm1.aspx.cs"
AutoEventWireup="false"
Inherits="MyPopChart.WebForm1" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
<HTML>
<HEAD>
<title>WebForm1</title>
<meta content="Microsoft Visual Studio 7.0"
name="GENERATOR">
<meta content="C#" name="CODE_LANGUAGE">
<meta content="JavaScript" name="vs_defaultClientScript">
<meta
content="http://schemas.microsoft.com/intellisense/i
e5" name="vs_targetSchema">
</HEAD>
<body MS_POSITIONING="GridLayout">
<form id="Form1" method="post" runat="server">
</form>
<div id="PopChart1" runat="server"></div>
</body>
</HTML>
Note:
This example page is for C#. The Visual Basic version of this page would look almost
exactly alike, and the process of adding a control to either version of the .aspx page is the
same.
I N S E R T I N G Y O U R PopChart Embedder C O D E
Most people will want to put their PopChart Embedder code in the Page_Load method
of their ASP.NET’s class file. This file will have the exact same name as your layout file,
with the addition of a .cs or .vb extension. The Page_Load method contains any code that
should run immediately before serving the page to a browser.
To specify your PopChart Embedder code, open your ASP.NET’s class file, locate the
Page_Load method, and insert the necessary code below the line that reads
5-29
.....
PopChart
5
6(5 9(5
ASP.NET
//Put user code to initialize the page here
The first thing you will need to do is instantiate an instance of the PopChart Embedder
object.
C#
To instantiate a PopChart Embedder object in C#, you should use the following line of
code (this assumes that you want to name your object myPopChart).
VISUAL BASIC
To instantiate a PopChart Embedder object in Visual Basic, you should use the following
line of code (this assumes that you want to name your object myPopChart).
Dim myPopChart = New PopChartEmbedder()
C#
5-30
www.corda.com
User Guide
.....
ASP.NET
VISUAL BASIC
"http://popchart.mycompany.com:2001"
attribute. It is not necessary to tell PopChart Embedder the client’s user agent; however,
you will not be able to take advantage of optimized HTML if you do not do this.
C#
The following line of code shows how to set the user agent with C#.
myPopChart.userAgent = Request.UserAgent;
VISUAL BASIC
The following line of code shows how to set the user agent with Visual Basic.
myPopChart.userAgent = Request.UserAgent
In addition to the afore-mentioned differences, you should be aware of the following issues
when you use Visual Basic with ASP.NET.
NO SEMI-COLONS AT THE END OF LINES
Note:
Visual Basic syntax requires that you do not have a semi-colon at the end of a line of code.
Since other languages either require a semi-colon, or are indifferent, most of the example
5-31
.....
PopChart
5
6(5 9(5
ASP.NET
code in this documentation uses a semi-colon at the end of each line of code. You should be
careful to remove any semi-colons from example code if you use it with Visual Basic.
For example, this line of code is invalid in a Visual Basic:
For most Visual Basic developers this will be a very obvious conversion process.
When you are ready to actually write your embedding HTML to the control you created in
“Placing a Control in Your Web Form” on page 5-28. You will need to output the
getEmbeddingHTML() method to the control.
T o w r it e th e em be d d in g H TM L to an H T M L c o n tr ol
1
Declare an HtmlGenericControl object.
You can name this object anything you want. We suggest you give it the same name as
the control you created in “Placing a Control in Your Web Form” on page 5-28. In
this example, the object will be named PopChart1.
In C#, you should use the following command:
HtmlGenericControl PopChart1;
In Visual Basic, you should use the following command:
Dim PopChart1 As HtmlGenericControl
2
Using the FindControl method, assign this object to the HTML control you created for
your PopChart in “Placing a Control in Your Web Form” on page 5-28.
The FindControl method takes one argument, a control id. It searches the layout
page for a web server or HTML control that has the specified id (i.e. the value you gave
your control’s id attribute, in this case PopChart1), and then returns the corresponding
object. You can then access this object from your code.
In C#, you will need to cast the returned object of the FindControl method as
HtmlGenericControl. thus, your assignment statement will look like this:
PopChart1 =
(HtmlGenericControl)FindControl("PopChart1");
5-32
www.corda.com
User Guide
.....
ASP.NET
In Visual Basic, your assignment statement will look like this:
PopChart1 = FindControl("PopChart1")
Note:
3
You can easily combine these first two steps, as has been done in the examples at the end of
this section.
Assign the InnerHTML attribute of this object to the string returned by PopChart
Embedder’s getEmbeddingHTML() method.
In C#, you can make this assignment with the following line of code:
PopChart1.InnerHtml = myPopChart.getEmbeddingHTML();
In Visual Basic, you can make this assignment with the following line of code:
PopChart1.InnerHTML = myPopChart.getEmbeddingHTML
Below are the class files (in both C# and Visual Basic) you would need to embed the
PopChart that you created in Chapter 4. The accompanying layout (.aspx) file can be
found earlier in this section in Example 5.6.
Note:
Code generated by the web form designer has been omitted from the example below.
C#
Example 5.7
Embedding a PopChart Image in an ASP.NET (Visual Basic)
using
using
using
using
using
using
using
using
using
using
using
System;
System.Collections;
System.ComponentModel;
System.Data;
System.Drawing;
System.Web;
System.Web.SessionState;
System.Web.UI;
System.Web.UI.WebControls;
System.Web.UI.HtmlControls;
PCNetEmbedder;
namespace MyPopChart
{
public class WebForm1 : System.Web.UI.Page
5-33
.....
PopChart
5
6(5 9(5
ASP.NET
{
private void Page_Load(object sender, System.EventArgs e)
{
// Put user code to initialize the page here
HtmlGenericControl PopChart1 =
(HtmlGenericControl)FindControl("PopChart1");
myPopChart.externalServerAddress = "localhost:2001";
myPopChart.userAgent = Request.UserAgent;
PopChart1.InnerHtml = myPopChart.getEmbeddingHTML();
}
#region Web Form Designer generated code has been omitted
#endregion
}
}
VISUAL BASIC
Example 5.8
Embedding a PopChart Image in an ASP.NET (Visual Basic)
Imports PCNetEmbedder
Public Class WebForm1
Inherits System.Web.UI.Page
#Region " Web Form Designer Generated Code (has been omitted)"
#End Region
Private Sub Page_Load(ByVal sender As System.Object, ByVal e As
System.EventArgs) Handles MyBase.Load
’Put user code to initialize the page here
Dim myPopChart = New PopChartEmbedder()
5-34
www.corda.com
User Guide
.....
ASP.NET
Dim PopChart1 As HtmlGenericControl =
FindControl("PopChart1")
myPopChart.externalServerAddress = "localhost:2001"
myPopChart.internalCommPortAddress = "localhost:2002"
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.userAgent = Request.UserAgent
myPopChart.addHTMLTable("graph", "title")
PopChart1.InnerHTML = myPopChart.getEmbeddingHTML
End Sub
End Class
5-35
.....
PopChart
5
6(5 9(5
ColdFusion
.C. O. . L. .D. F. .U. S. .I.O. .N. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ColdFusion application servers can use either the Java PopChart Embedder or the COM
PopChart Embedder. In both cases, the code looks almost exactly alike, and is very
similar to the code you created for the JavaScript embedder in Chapter 4. This section will
explain the major differences. Example 5.9 and Example 5.10 at the end of this section
show you how the web page from Example 4.7 would look as a ColdFusion Page.
Important:
Note:
ColdFusion MX currently does not allow access to the component object model. This is
apparantly a bug in ColdFusion MX. Because of it, the COM version of the PopChart
Embedder will not work with ColdFusion MX. You should use the Java version instead.
This documentation assumes that if you want to embed a PopChart image in an
ColdFusion Page, you already know how to use ColdFusion. If this is not the case, you
may wish to brush up on ColdFusion before continuing.
INSTALLING THE LIBRARY
The instructions for installing the PopChart Embedder differ according to which version
you use.
J A V A PopChart Embedder
Just as you have to put the PopChartEmbedder.jar file, located in the
dev_tools/java_embedder folder, in the classpath of a Java Application Server, you also
need to put it in the classpath for ColdFusion. If you do not know how to add a Jar file to
your ColdFusion’s classpath, refer to “Including the PopChartEmbedder.jar File in
Your Classpath” on page 5-46.
C O M PopChart Embedder
Important:
If you have re-installed PopChart Server since version 4.0.3, please ignore this step. The
PopChart Embedder COM Component has been installed automatically for you.
Before you can use the PopChart Embedder in a ColdFusion page, you must first make
sure that the PCEmbedder.dll file, located in the dev_tools/COM_embedder folder, is
installed as a component Service. If you do not know how to install a component to your
component services, refer to “Installing the COM PopChart Embedder as a
Component Services” on page 5-53.
To instantiate a PopChart Embedder object on ColdFusion, you should use the
<cfobject> tag. You should set the name attribute of this tag to the name of your
PopChart Embedder object (e.g. myPopChart) and the action attribute to Create.
5-36
www.corda.com
User Guide
.....
ColdFusion
The values of the other attributes of this tag will depend upon the version of PopChart
Embedder that you use.
J A V A PopChart Embedder
Set the type attribute to Java and the class attribute to
com.corda.pcis.PopChartEmbedder.
<cfobject type="Java" action="Create" name="myPopChart"
class="com.corda.pcis.PopChartEmbedder">
C O M PopChart Embedder
Set the type attribute to COM and the class attribute to PopChart.Embedder.
<cfobject type="COM" action="Create" name="myPopChart"
Class="PopChart.Embedder">
Note:
You do not need to close the cfobject tag (i.e. do not use a </cfobject> tag).
IMAGE
Except for instantiating the PopChart Embedder object and writing the embedding
HTML to the web page, all PopChart Embedder code should go inside of a
<cfscript> tag, as in the following code segment:
<cfscript>
myPopChart.appearanceFile = "apfiles/line.pcxml";
myPopChart.loadPCXML("http://myserver.com/?graph1");
</cfscript>
5-37
.....
PopChart
5
6(5 9(5
ColdFusion
attribute. The following line of code shows how to do this in a ColdFusion page.
myPopChart.userAgent =
Request.ServerVariables("HTTP_USER_AGENT");
MISCELLANEOUS NOTES
Although almost all of the code looks the same in ColdFusion for the Java and COM
versions of PopChart Embedder, remember that code that uses the Java PopChart
Embedder will act like Java code, while code that uses the COM PopChart Embedder
will act like COM code.
This means that if you use PopChart Embedder methods that act differently in the Java
and COM versions (e.g. setDBQuery()), you need to be sure to use the correct syntax. If
you add additional code, be sure that it conforms to the syntax of the language you have
chosen. Also, please consult “Miscellaneous Differences” on page 5-24 for additional
information about using the COM PopChart Embedder.
5-38
www.corda.com
User Guide
.....
ColdFusion
When you are ready to actually write your embedding HTML to the ColdFusion page, you
will need to output the getEmbeddingHTML() method. To do this, use the
<cfoutput> tag, as shown below. Be sure to put pound signs before and after the
myPopChart.getEmbeddingHTML() statement.
<cfoutput>
#myPopChart.getEmbeddingHTML()#
</cfoutput>
The following ColdFusion page uses the Java PopChart Embedder to produce exactly
the same results as the page you created in Chapter 4.
Example 5.9
Embedding a PopChart Image with ColdFusion (Java)
<html>
<head>
</head>
<body>
<hr>
<cfobject TYPE="Java" ACTION="Create"
CLASS="com.corda.pcis.PopChartEmbedder"
NAME="myPopChart">
<cfscript>
myPopChart.externalServerAddress="localhost:2001";
myPopChart.userAgent = CGI.HTTP_USER_AGENT;
</cfscript>
<cfoutput>
5-39
.....
PopChart
5
6(5 9(5
ColdFusion
</cfoutput>
<hr>
</body>
</html>
This last ColdFusion Page uses the COM PopChart Embedder to produce the same
results.
Example 5.10
Embedding a PopChart Image with ColdFusion (COM)
<html>
<head>
</head>
<body>
<hr>
<cfobject type="COM" action="Create" name="myPopChart"
Class="PopChart.Embedder">
<cfscript>
myPopChart.userAgent = CGI.HTTP_USER_AGENT;
</cfscript>
<cfoutput>
</cfoutput>
<hr>
5-40
www.corda.com
User Guide
.....
ColdFusion
</body>
</html>
5-41
.....
PopChart
5
6(5 9(5
PHP
.P. H. .P. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you use PHP to deliver web content, you can embed a PopChart image using the PHP
version of the PopChart Embedder.
For the most part, the code that you will use for embedding a PopChart image with a PHP
script is exactly the same as the code you created for the JavaScript embedder in Chapter 4.
This section will explain the major differences. Example 5.11 at the end of this section
shows you how the web page from Example 4.7 would look using PHP.
Note:
This documentation assumes that if you want to embed a PopChart image in an PHP Page,
you already know how to use PHP. If this is not the case, you may wish to brush up on PHP
before continuing.
INCLUDING THE LIBRARY
Before you can include the PopChart Embedder library into a PHP script, you must first
make sure that the PopChartEmbedder.php file, located in the
dev_tools/php_embedder folder, is accessible to your PHP scripts. Usually the easiest
way of making them accessible is to copy them to the same folder as the scripts that will use
the PopChart Embedder. Alternatively, you can copy the PopChartEmbedder.php file
to a shared or includes directory that is accessible to your PHP server.
To include the PopChart Embedder library in a PHP script, include the following line at
the beginning of your script.
require("PopChartEmbedder.php");
This instructs the PHP compiler to load the PopChartEmbedder class.
$myPopChart = new PopChartEmbedder();
IMAGE
All PopChart Embedder code, including the require statement, should be delimited by
<?php and ?>, as in the following code segment:
5-42
www.corda.com
User Guide
.....
PHP
<?php
$myPopChart->appearanceFile = "apfiles/line.pcxml";
$myPopChart->loadPCXML("http://myserver.com/?graph1");
?>
$myPopChart->externalServerAddress =
$myPopChart->internalCommPortAddress =
"10.0.1.1:2002";
attribute. The following line of code shows how to do this in a PHP page.
$myPopChart->userAgent =
$HTTP_SERVER_VARS[’HTTP_USER_AGENT’];
5-43
.....
PopChart
5
6(5 9(5
PHP
MISCELLANEOUS NOTES
There are certain PopChart Embedder methods that are unavailable in the PHP version.
These are as follows:
•
•
•
•
byte[] getImageData()
void saveImageToAppServer(String, String)
void setDBQuery(String, String, String, String, String, String)
void setResultSet(String,ResultSet)
SYNTAX DIFFERENCES
In PHP, you will always use pointer notation when calling methods or accessing attributes.
This differs from the dot-notation that is used in most of the examples in this
documentation. Also, variable names must always begin with a dollar sign.
For example, consider the following command in Java.
myPopChart.appearanceFile = "bar.pcxml";
The equivalent code in PHP would be as follows:
$myPopChart->appearanceFile = "bar.pcxml";
For most PHP developers, this will be an obvious conversion process.
need to output the getEmbeddingHTML() method. To do this, use the echo statement,
as shown below.
echo $myPopChart->getEmbeddingHTML();
The following web page uses the PHP PopChart Embedder to produce exactly the same
results as the page you created in Chapter 4.
Example 5.11
Embedding a PopChart Image with PHP
<html>
<head>
5-44
www.corda.com
User Guide
.....
PHP
</head>
<body>
<hr>
<?php
require("PopChartEmbedder.php");
$myPopChart = new PopChartEmbedder();
$myPopChart->externalServerAddress="localhost:2001";
$myPopChart->internalCommPortAddress = "localhost:2002";
$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->userAgent = $HTTP_SERVER_VARS[’HTTP_USER_AGENT’];
echo $myPopChart->getEmbeddingHTML();
?>
<hr>
</body>
</html>
5-45
.....
PopChart
5
6(5 9(5
Including the PopChartEmbedder.jar File in Your Classpath
I N C L U D I N G T H E PopChartEmbedder.jar F I L E
IN YOUR CLASSPATH
..................................................
Before you import the PopChart Embedder library into a Java Server Page or a Servlet,
you first need to include the PopChartEmbedder.jar file in your web application server’s
classpath. This file, located in the dev_tools/java_embedder folder, contains all of the
classes necessary to use the PopChart Embedder in a Java environment.
How you include the PopChartEmbedder.jar file will depend upon your web application
server. Listed below are the instructions for several of the more common web application
servers. If yours is not listed, consult your web application server’s documentation for
instructions.
Before you read on, though, you should copy the PopChartEmbedder.jar file to a location
accessible to your web application server.
COLDFUSION
Launch the ColdFusion Administrator on the machine where you are installing the
PopChart Embedder. Once there, click on the Java option under Server on the left hand
menu. This will bring you into the Java Settings window.
Make sure Load JVM when starting Cold Fusion has been checked. If it hasn’t, you
will also need to specify the location of the Java VM on your server. On Microsoft
Windows, look for jvm.dll. On UNIX, look for libjvm.so. If you installed a Java VM with
PopChart Server, you can find the appropriate file in the jre/bin/hotspot folder.
After making sure the Java VM is enabled, you then need to add the location (absolute path)
of your PopChartEmbedder.jar file to the Class Path variable, as shown in the
following image.
5-46
www.corda.com
User Guide
.....
Note:
If there are already other files in the classpath, make sure you separate the files with a semicolon.
Click on the Apply button to save your changes.
5-47
.....
PopChart
5
6(5 9(5
IPLANET™
Begin by logging in to the iPlanet Web Administration Page. Once you are logged in,
choose the server which you wish to alter from the pulldown list and press the Manage
button.
Click on the Servlets tab. Make sure that you have enabled JSPs and Servlets for your
server by selecting Yes for the following settings: Activate the Servlet Engine? and
Enable JSP? (only the first setting needs to be enabled for Servlets).
To add the PopChartEmbedder.jar file to the iPlanet application server classpath, select
the Configure JVM Attributes from the left sidebar. Add the absolute path to the
5-48
www.corda.com
User Guide
.....
appropriate jar file to the end of the Classpath variable. If there are already other files in
this list, be sure to add a semi-colon before the path to PopChartEmbedder.jar.
Once a jar file has been added to the classpath, the server must be restarted. To do this, push
the OK button and then hit Apply to verify that iPlanet has restarted.
5-49
.....
PopChart
5
6(5 9(5
JRUN™
To add the PopChartEmbedder.jar file to the JRun application server classpath, copy it to
the /JRun/servers/default/default_app/WEB-INF/lib/ directory, where default is the
name of the server and default_app is the name of the web application to which you wish
to add the JAR file (within every web application there should be a WEB-INF/lib/ directory
that holds JAR files). Once the jar file is added, the web server must by restarted so that
JRun will load the new jar file.
TOMCAT
To add the PopChartEmbedder.jar file to the classpath of a Tomcat web application
application, copy it to the lib folder of your web application (e.g.
/Tomcat/webapps/default/WEB-INF/lib, where default is the name of the web
application). Then restart Tomcat.
WEBLOGIC®
To add the PopChartEmbedder.jar file to the WebLogic application server classpath,
copy it to the WEB-INF\lib subdirectory within the root directory of your web application.
On Microsoft Windows, for example, the root directory is usually
C:\bea\wlserver6.1\config\mydomain\applications\DefaultWebApp_myserver. After
you add the file, WebLogic will need to be restarted.
WEBOBJECTS
You need to add the path to your PopChartEmbedder.jar file in two locations.
B uil d C la s s P a th In your /Supporting Files/Makefile.preamble file, search
for the OTHER_CLASSPATH variable. Add to this variable the location of your
PopChartEmbedder.jar file. For example, if you’ve copied the file to
/System/java_jars/PopChartEmbedder.jar, this line would read as follows:
OTHER_CLASSPATH =
/System/java_jars/PopChartEmbedder.jar
D e plo y C la s s Pa th In your /Supporting Files/CustomInfo.plist file, search
for the NSJavaUserPath variable. Add to this variable the location of your
PopChartEmbedder.jar file. For example, if you’ve copied the file to
/System/java_jars/PopChartEmbedder.jar, this line would read as follows:
5-50
www.corda.com
User Guide
.....
NSJavaUserPath =
(/System/java_jars/PopChartEmbedder.jar)
WEBSPHERE®
To add the PopChartEmbedder.jar file to the WebSphere application server classpath,
go into the administration console and expand the WebSphere Administrative
Domain tree on the left side. Several machine names should appear. Select the name of the
machine that you wish to use with PopChart Server.
Next, select the appropriate web server. By default, every machine with WebSphere has a
server named Default Server. Then, select a servlet engine (e.g. Default Servlet
Engine). Finally, select a web application within the servlet engine (e.g. default_app).
After selecting a web application, click on the Advanced tab. At this point you should see
the Classpath, containing a list of JAR and ZIP files. Click on the button to the right of
Classpath and browse to the location of PopChartEmbedder.jar (be sure the files of
type box at the bottom of the browsing dialog is set to Jar Files (.jar)).
5-51
.....
PopChart
5
6(5 9(5
After you select the file from this dialog, the PopChartEmbedder.jar file should appear in
the list of jar and zip files in the classpath. The web application will not load this jar file
until you push the Apply button.
After pushing Apply, the newly added jar file should appear in the bottom list,
Classpaths in Use. At this point, you will know that the jar file was successfully added
to the web application.
5-52
www.corda.com
User Guide
.....
Installing the COM PopChart Embedder as a Component Services
I N S T A L L I N G T H E C O M PopChart Embedder
AS A COMPONENT SERVICES
..................................................
Note:
If you have performed a clean installation of PopChart Server since the 4.0.3 release, the
COM PopChart Embedder will be installed automatically for you. You only need to follow
these instructions if you want access to the PopChart Embedder component from
Component Services.
When using the Component Object Model (COM) version of the PopChart Embedder on
Windows 2000/XP, you first need to install it as component service. For instructions on
installing the COM PopChart Embedder on Windows NT, see “To install the COM
PopChart Embedder using the Command Prompt” on page 5-56.
Note:
You will need Administrative privileges to install this Component.
T o in s t al l th e C O M PopChart Embedder us i n g C o mp o ne n t S e rv i c es
1
In the Control Panel menu, select Administrative Tools > Component Services.
2
On the left pane of the Component Services window, you will find a listing with
various option trees. Expand the Component Services > Computer > My Computer
tree.
3
Under the My Computer tree, select the COM+ Applications directory.
The right pane will display a list of COM+ Applications currently installed on the
system.
4
Right click on the COM+ Applications directory, and select New > Application. The
COM Application Install Wizard should start up.
5
In the COM Application Install Wizard, click on Next to proceed to the next screen.
6
In the Install or Create a New Application screen, choose Create an empty
application.
7
The next screen, Create Empty Application will ask you for the name of the
application.
You can name it anything you want. We suggest PopChart Embedder.
8
Make sure the activation type is set to Server application, and then select Next.
9
Select the user account to associate with the component application.
Do not use the Interactive user setting. Under this setting, the COM PopChart
Embedder will only work when a user is logged into the computer.
5-53
.....
PopChart
5
6(5 9(5
10
When you click on Next, the Wizard will say you are done. Click on Finish to exit the
wizard.
Under the COM+ Applications directory you should now see a COM+ Application with
the name you just specified.
11
Now that a COM+ Application is set up, you need to tell it where to find the COM object.
To do this, expand the tree of the COM+ Application you just created (e.g. PopChart
Embedder). Right click on the Components directory (left pane) and select New >
Component. The COM Component Install Wizard should start up.
12
Click on Next to proceed to the next screen which should be titled, Import or Install a
Component.
13
Choose Install new component(s).
14
You will be asked to specify a file. Locate the PCEmbedder.dll file in the
dev_tools/COM_embedder directory and select it.
The PCEmbedder.dll should now be listed on the Install new component(s)
dialog.
5-54
www.corda.com
User Guide
.....
15
Select Next to continue, and then Finish to complete the installation.
If the COM object has been installed correctly, you should be able to right-click on the
COM+ Application you created (e.g. PopChart Embedder) in the left pane, select
Start, and start it without any error messages.
Note:
When you examine the COM+ Applications while PopChart Embedder is running, the
ball in its icon on the right pane will rotate if it is running properly.
5-55
.....
PopChart
5
6(5 9(5
T o in s t al l th e C O M PopChart Embedder us i n g th e C om ma nd P ro mp t
Installing the COM PopChart Embedder on Windows NT is a simple process.
1
Open up a command prompt.
2
Change to the dev_tools/com_embedder folder of your PopChart root directory.
3
Type in the following command:
regsvr32 PCEmbedder.dll
CHANGING COMPONENT PROPERTIES
Some users may also want to change how the PopChart Embedder component runs. You
can change the settings for how the PopChart Embedder runs in Windows 2000/XP by
right-clicking on its icon and selecting Properties.
This will bring up a screen listing the COM object’s various properties. Unless you know
what you are doing, we suggest you do not change these. The only exception may be the
Server Process Shutdown settings in the Advanced pane. To preserve system
resources, Windows will shut down the application after a certain period of inactivity. The
application will then restart whenever it is requested. However, this means that the first time
you use the PopChart Embedder after it has shut down, it will take between 5-10 seconds
to retrieve a PopChart image. On a high-volume server, this shouldn’t be a problem because
the application will rarely be idle long enough to shut down. However, if you don’t want the
server shutting down, or you want a longer idle period before it shuts down, you should
modify this settings.
5-56
www.corda.com
S ENDING D YNAMIC D ATA TO PopChart Server
T
.....
...................................
6
he most important part of a graph is the data inside of it. Although you can always enter
your data manually into each appearance file with PopChart Builder, one of PopChart
Server’s most useful features is its ability to import live, dynamic data into PopChart
images.
Your appearance file can be used as a template for graphs that contain live data. The live
data will replace the sample data from your appearance file. PopChart Server can even
automatically rescale, resize, and reposition objects in your appearance file for you if your
live data set is significantly different than the data in your appearance file (refer to
“Dynamically Resizing the Appearance File” on page 1-19 of the PopChart Builder
User Guide).
Since your data can be (and often is) stored in a wide variety of formats, we’ve designed
PopChart Server 4.0.5 to accept data in as many different forms as possible. Before you
get started using dynamic data though, it is important that you understand how PopChart
Server will interpret the data that you send it. Thus, the first part of this chapter discusses
how PopChart Server uses your data.
The last part of this chapter describes four different strategies for sending your data to
PopChart Server. Each of these strategies has its strengths and weaknesses. For example,
importing your data from a file or from a database may be easier to set up initially, while
you may find PopChart XML more powerful (in terms of interactivity and customization) in
the long run.
Note:
Using PopChart XML or PopChart Script does not mean that you can’t graph data from
your database. Most people, in fact, use a web application to make SQL queries to their
database, process the results, and output the data in a format compatible with PopChart
XML or PopChart Script.
The four strategies are:
• Sending Data with PopChart XML — a new XML format for interfacing with
PopChart.
• Sending Data with PopChart Script — an object oriented scripting language.
• Importing Data from Data Files — importing from tab-delimited, comma-separated,
and XML data files, as well as HTML tables within web pages.
• Importing Data Directly from Databases — fetching data with SQL queries from
OBDC/JBDC driven databases.
6-1
.....
PopChart
6
6(5 9(5
S E N D I N G D Y N A M I C D A T A T O PopChart Server
.H. O. . W. . .PopChart
. . . . . . . . . Server
. . . . . . . U. .S. .E. S. . .Y. O. .U. .R. . D. .A. .T.A. . . . . . .
The building block of every graph in PopChart Server is a data item. Exactly what this
data item is will depend on the graph. For example, a data item in a bar graph is simply a
single data value represented as a bar. A data item in an X-Y Bubble graph, however,
consists of three data values—an X-value, a Y-value, and Bubble value. Grouped together,
all of the data items in a graph can be referred to as a data set.
PopChart Server groups data items into series and categories. It is easiest to think of
series and categories as corresponding to rows and columns on a spreadsheet, respectively.
Be aware, though, that this does not necessarily mean that your data will be organized in this
fashion when you send it to PopChart Server.
All data items in a specific data series are displayed in the same color. In line graphs, they
are also connected by a line. Each item in a series of data belongs to a different category. All
items in the same category will be grouped together in the graph. Example 6.1 illustrates
the roles of series and categories of data in creating a graph.
Example 6.1
Series and Categories
9/5/01
10789 9745 13841
7861
Team B
Team C
9/4/01
9/3/01
Team A
8916
9612
11263 6047 12743
Each value on this row is
a data item in the Team
C series of data. The
data items will appear as
green bars.
Each value in this column is
considered to be a data item in
the 9/4/01 category. They are
grouped together in the graph.
For all variations of Bar, Line, and Radar graphs, you will organize your data in the
spreadsheet format of the above example. Pie graph data is organized similarly, but only has
one category of data, whereas data for a Pareto graphs only has one data series. The data in
more complex graphs, such as Stock, X-Y, and Time Plot graphs, is organized somewhat
differently, though the basic concept of series and categories remains the same. To learn
6-2
www.corda.com
User Guide
.....
exactly how you should organize data for these graph types, refer to Chapter 12, “Data
Organization,” in the PopChart Server Reference manual.
The examples in this chapter will use the sample set of data in Table 6.1 below, which
describes the inventory at a car rental agency.
TABLE 6.1 Example Data
Arrivals
Departures
Unused
Out of
Commission
Atlanta
23
36
11
7
Boston
41
17
25
9
In this set of data, there are four categories and two series of data.
The four categories are: Arrivals, Departures, Unused, and Out of Commission. In the
Arrivals category there are two data items with these values: 23 and 41. In the Departures
category there are two data items with these values: 36 and 17. In the Unused category
there are two data items with these values: 11 and 25. Finally, in the Out of Commission
category there are two data items with these values: 7 and 9.
The two series are Atlanta and Boston. In the Atlanta series there are four data items with
these values: 23, 36, 11, and 7. In the Boston series there are four data items with these
values: 41, 17, 25, and 9.
This data is suitable for the bar graph that we created in Chapter 4. You should also be able
to use it for any of the example area, bar, line, or radar graphs. When applied to the graph
6-3
.....
PopChart
6
6(5 9(5
we created in Chapter 4 (see Example 4.7 on page 4-19), this data will render the following
PopChart image.
Hello World
The remaining sections of this chapter will show you how to send this data to PopChart
Server.
TIP: USING THE POPCHART EXAMPLES
One handy tool for learning how to use PopChart Server
is the PopChart Examples book. This book, which you
can get to via the PopChart Examples shortcut that was
installed with PopChart Server, contains a number of
example PopCharts with instructions on how to build them
in PopChart Builder.
If you view the Dynamic HTML version of the book, the
book will use live code to generate the example images
6-4
(PopChart Server must be running). You can view this
live JavaScript code at the bottom of each example. Using
the frame at the top of the book, you can also select how
the example should import its data. The example book
contains example data in the following formats: standard
XML, PopChart XML, CSV, Tab-delimited, PCScript, and
server command file. You can jump directly to any of these
data examples to see how you should format your data.
www.corda.com
User Guide
.....
Sending Data with PopChart XML
.S. E. .N. .D. I.N. .G. . D. .A. .T. A. . .W. .I.T. H. . .P. O. . P. .C. H. . A. .R. .T. .X. M. . L. . . . . .
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” on page 1-7 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’/>
</Series>
<Series Name=’Boston’>
</Series>
</GraphData>
</Chart>
6-5
.....
PopChart
6
6(5 9(5
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 the
section entitled “XML Data Files” on page 6-17.
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?” on page 6-6). 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' />
WHAT IS MY OBJECT NAMED?
Each object in a PopChart (i.e. graph, text box, legend, or
bitmap) must have its own unique name. You will use this
name to reference the object in the PopChart Embedder,
in PopChart XML or in PCScript. For example, the
PCScript command to modify the data inside a text box is:
textbox.SetText(My Title)
In this case, the name of the text box object is textbox.
Were the name something else, like title, for instance, the
command would be:
title.SetText(My Title)
Thus, it is important to know what your objects are named,
and to make sure there are no duplicate names. By default,
PopChart Builder assigns each object a unique name. The
6-6
first graph will be named graph, and all subsequent graphs
will be named graph2, graph3, and so on. Text boxes,
legends, and bitmaps follow a similar naming scheme,
except text boxes are based on the name textbox, legends
are based on the name legend, and bitmaps are based on
the name bitmap.
Since there is usually only one object of each type in a
PopChart, you can generally assume that your graph object
is named graph, your text box is named textbox, and so
on. However, if you need to find out what an object is
named, you can always open your appearance file in
PopChart Builder, right-click on the object, select its
Properties dialog, and find its Object Name under the
Advanced tab.
www.corda.com
User Guide
.....
<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’ />
</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-LowOpen-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' />
6-7
.....
PopChart
6
6(5 9(5
....................................................
Graph Types
Data Element
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” on page 4-8).
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/?get
pcxml");
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” on page 3-37 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.
6-8
www.corda.com
User Guide
.....
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.loadPCXML("examples/pcxml/data1_p.xml");
document.writeln(myPopChart.getEmbeddingHTML());
6-9
.....
PopChart
6
6(5 9(5
Sending Data with PopChart Script
.S. E. .N. .D. I.N. .G. . D. .A. .T. A. . .W. .I.T. H. . .P. O. . P. .C. H. . A. .R. .T. .S. C. . R. .I .P. T. .
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?” on page 6-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” on page 5-2 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.
6-10
www.corda.com
User Guide
.....
Example 6.4
PCScript Command String 1
graph.setCategories(Apples)textbox.setText(Apple Graph)graph.setSe
ries(Andy,10;Julie,14;Bryan,11)graph.addPopupText(1,
1-3,Apples are Good)graph.DDEnable(1,1-3,http://www.
applepies.com)
Example 6.5
graph.setCategories(Apples)
textbox.setText(Apple Graph)
graph.setSeries(Andy,10;Julie,14
;Bryan,11) graph.addPopupText(1,1-3,Apples are Good)
graph.DDEnable(1,1-3,http://www.pplepies.com)
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
6-11
.....
PopChart
6
6(5 9(5
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.
S E N D I N G P C S C R I P T T O 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.
S E N D I N G P C S C R I P T V I A 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.
6-12
www.corda.com
User Guide
.....
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.
Example 6.6
Sending the PCScript Command String via PopChart Embedder
String pcscript = "graph.SetCategories(Arrivals; Departures;
Unused; Out of Commission)";
pcScript += "graph.SetSeries(Atlanta; 23; 36; 11; 7)";
pcScript += "graph.SetSeries(Boston; 41; 17; 25; 9)";
myPopChart.pcScript = pcscript;
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” on page 11-16). 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” on page 11-16).
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
6-13
.....
PopChart
6
6(5 9(5
data from Table 6.1 would look in a server command file. This file is saved as
command1.txt in the examples/command folder.
Example 6.7
Server Command File
@_PCSCRIPT
graph.SetCategories(Arrivals; Departures; Unused; Out of
Commission)
graph.SetSeries(Atlanta; 23; 36; 11; 7)
graph.SetSeries(Boston; 41; 17; 25; 9)
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” on
page 3-37 for more information.
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:
Example 6.8
String pcscript = "graph.SetCategories(Arrivals; Departures;
Unused; Out of Commission)";
6-14
www.corda.com
User Guide
.....
pcscript += "graph.SetSeries(Atlanta; 23; 36; 11; 7)";
pcscript += "graph.SetSeries(Boston; 41; 17; 25; 9)";
pcscript += "title.setText(Hello World)";
myPopChart.pcScript = pcscript;
6-15
.....
PopChart
6
6(5 9(5
Importing Data from Data Files
.I M. . P. .O. .R. T. .I.N. G. . . D. .A. .T.A. . .F.R. .O. .M. . D. .A. .T. A. . .F. I.L. E. .S. . . . . . .
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:
•
•
•
Importing Data Files with PopChart Embedder
Importing Data Files with PCScript
Streaming the Data Directly to PopChart Server
D A T A F O R M A T S T H A T PopChart Server I M P O R T S
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
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:
• The first line is used for category names. A tab separates each name. The first name
should be preceded by a tab, meaning that the first entry is empty (this makes things
easier when using files that have been exported from a spreadsheet program, where the
top left data entry will usually be left blank). Data files for X-Y and Time Plot graphs
will not have this line.
• All subsequent lines are interpreted as series. The first entry will be the series name. All
subsequent entries are treated as data values. All entries should be separated by tabs.
Note:
6-16
If you need to reverse the categories and series in an imported file, you can use the
graph.Transposed() PCScript command.
www.corda.com
User Guide
.....
Example 6.9 shows how the example data from Table 6.1 looks as tab-delimited data.
Example 6.9
Example Data in Tab-Delimited Format
Atlanta
Boston
Arrivals
23
41
Departures
36
17
Unused
11
25
Out of Commission
7
9
COMMA SEPARATED VALUE FILES
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:
• The first line is used for category names. A comma separates each name. The first name
should be preceded by a comma, meaning that the first entry is empty (this makes things
easier when using files that have been exported from a spreadsheet program, where the
top left data entry will usually be left blank). Data files for X-Y and Time Plot graphs
will not have this line.
• All subsequent lines are interpreted as series. The first entry will be the series name. All
subsequent entries are treated as data values. All entries should be separated by commas.
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
,Arrivals,Departures,Unused,Out of Commission
Atlanta,23,36,11,7
Boston,41,17,25,9
XML DATA FILES
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
the section entitled “Sending Data with PopChart XML” on page 6-5.
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.
6-17
.....
PopChart
6
6(5 9(5
Note:
Example 6.11
By default, most databases will export data in this format, so it may not be necessary for you
to understand this syntax.
XML Data Syntax
<DataSetName>
<SeriesElement>
<SeriesNameTag>Series Name</SeriesNameTag>
<CategoryName1>Data</CategoryName1>
<CategoryName2>Data</CategoryName2>
...
</SeriesElement>
<SeriesElement>
...
</SeriesElement>
...
</DataSetName>
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
<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>
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.
6-18
www.corda.com
User Guide
.....
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.
HTML TABLES
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.
Example 6.13
Example Data in an HTML Table
<table title="Spreadsheet">
<tr>
<td> </td>
<td>Arrivals</td>
<td>Departures</td>
<td>Unused</td>
<td>Out of Commission</td>
</tr>
<tr>
<td>Atlanta</td>
<td>23</td>
<td>36</td>
6-19
.....
PopChart
6
6(5 9(5
<td>11</td>
<td>7</td>
</tr>
<tr>
<td>Boston</td>
<td>41</td>
<td>17</td>
<td>25</td>
<td>9</td>
</tr>
</table>
FILTERING ROWS AND COLUMNS
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)
FIGURING OUT A TABLE NUMBER
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/?@_SHOWTABLES
FROMURLurl
6-20
www.corda.com
User Guide
.....
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” on page 3-37.
I M P O R T I N G D A T A F I L E S W I T H PopChart Embedder
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?” on page 6-6) into which you wish to load the data. The
6-21
.....
PopChart
6
6(5 9(5
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.co
m/?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:
6-22
www.corda.com
User Guide
.....
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
myPopChart.PCScript = "title.setText(Hello World)";
myPopChart.loadData("graph","examples/data/data1.xml");
IMPORTING DATA FILES WITH PCSCRIPT
You can also import data files using PCScript LoadFile() method. The syntax is very
similar to that discussed “Importing Data Files with PopChart Embedder” on page 6-21.
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:
6-23
.....
PopChart
6
6(5 9(5
graph2.loadFile(http://www.myserver.com/stats.html,rep
lace,data2)
You would then send your PCScript command to PopChart Server using its pcScript
attribute, as discussed in “Sending PCScript Via PopChart Embedder” on page 6-12.
S T R E A M I N G T H E D A T A D I R E C T L Y T O PopChart
Server
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” on page 6-21. 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><Departur
es>36</Departures><Unused>11</Unused><Out_of_Commiss
ion>7</Out_of_Commission></CityInventory><CityInvent
ory><City>Boston</City><Arrivals>41</Arrivals><Depar
tures>17</Departures><Unused>25</Unused><Out_of_Comm
ission>9</Out_of_Commission></CityInventory></CarSta
tus>");
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.
6-24
www.corda.com
User Guide
.....
Importing Data Directly from Databases
IMPORTING DATA DIRECTLY FROM
DATABASES
..................................................
Perhaps one of the most exciting new features of PopChart Server 4.0 is the ability to
import data directly from a JDBC or ODBC driven database. All you have to do is specify a
database driver, name, and SQL query, and PopChart Embedder will automatically
execute the query and import the resulting data.
Note:
This documentation assumes you are already familiar with your database and SQL queries.
If you are not, you will probably need to brush up on these subjects before you can import
database data into PopChart Server.
IMPORTING FROM A DATABASE IN JAVA
Before you import data in Java, you should check to see that you have a JDBC driver for
your database. Some installations of Java (for instance, the JRE that is installed
automatically with PopChart Server on Microsoft Windows) already contain certain
drivers. However, if your Java installation does not contain the appropriate driver, you must
make sure that you include your JDBC driver in the classpath for your Java program,
servlet, or web application server. You would do this in the exact same manner that you
added the PopChartEmbedder.jar file to your classpath in “Including the
PopChartEmbedder.jar File in Your Classpath” on page 5-46.
Once you have done this, you can use the setDBQuery() method to import data. The
setDBQuery() method accepts a number of parameters. The syntax is as follows:
myPopChart.setDBQuery(graphname,databasedriver,databas
eURL,user,password,SQLquery);
The first parameter, graphname, is the name of the graph object (see “What is my Object
Named?” on page 6-6) into which you want to import the data. The second parameter is the
full name of your JDBC driver. This is not the file or archive that contains the driver, but
rather the Java class itself. In other words, com.oracle.jdbc.OracleDriver would be valid,
while classes12.zip would not be valid.
The third parameter is the actual name of the database. Typically, your database URL will
be in the form jbdc:driver:name (e.g. jdbc:odbc:mydata, jdbc:oracle:mydata). Be
sure that this database is accessible from the computer running PopChart Embedder.
The fourth and fifth parameters are the user name and password for this database,
respectively. If no user name or password is required, you should pass an empty String. The
last parameter is your SQL query. This documentation assumes that you already know
enough about SQL to build this query yourself.
Example 6.15 shows how you would use this method to import data into the PopChart
image we created in Example 5.4. It assumes that your graph object is named graph, that
6-25
.....
PopChart
6
6(5 9(5
you are using the sun.jdbc.odbc.JdbcOdbcDriver, that your user name and password are
user and password, that your database is located at jdbc:odbc:bcdemos, and that your
SQL query is “Select Description, OnHand from parts order by Description”. If you
have access to a database, you could easily replace these values with valid parameters and
actually generate a PopChart image containing your data.
Example 6.15
Importing from a DataBase in Java
myPopChart.setDBQuery("graph",
//name of graph
"sun.jdbc.odbc.JdbcOdbcDriver",//database driver
"jdbc:odbc:bcdemos", //database URL
"user",
//user name
"password",
//password
"Select Description, OnHand from parts order by
Description");
//SQL Query
String PCHTML = myPopChart.getEmbeddingHTML();
Note:
Both Example 6.15 and Example 6.16 use Sun’s JDBC-ODBC bridge, which is a
database driver that is automatically installed with JRE for Windows. Thus, we do not have
to worry about adding anything to our classpath.
U S I N G SetResultSet()
If you’d like to query the data using your own method, you can take advantage of the Java
PopChart Embedder’s setResultSet(String,ResultSet) method, which
allows you to import data from a resultSet object.
You pass setResultSet() two parameters. The first is a String containing the name of
the graph object into which you want to import the data. The second is a resultSet
object. Example 6.16 below shows how you might use this method. It assumes you have
already imported the java.sql library (with the statement import java.sql.*). Note that it
achieves the exact same results as the setDBQuery() method call in Example 6.15.
Example 6.16
Using SetResultSet()
Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
6-26
www.corda.com
User Guide
.....
Connection con= DriverManager.getConnection("jdbc:odbc:bcedemos",
"user", "password");
Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery("Select Description, OnHand from
parts order by Description");
myPopChart.setResultSet("graph",rs);
IMPORTING FROM A DATABASE WITH COM
New in PopChart Server 4.0.1
Using the COM version of the PopChart Embedder, you can import data from any ODBC
data source that has been set up on the computer that is generating your web pages.
On Windows NT/2000/XP systems, you can view your ODBC data sources by selecting
Administrative Tools > Data Sources from the Control Panel. This will bring up the
ODBC Data Source Administrator. The PopChart Embedder can access any
database listed under the User DSN, System DSN, and File DSN tabs. However, in
most cases you will only want to use data sources listed under the System DSN tab, as
other data sources will not be available when the current user logs off of the system.
Note:
You can add a database to this list by clicking on the Add button. For this documentation,
we assume that you have already successfully added the database you wish to access.
6-27
.....
PopChart
6
6(5 9(5
The screenshot below shows what you might see in your ODBC Data Source
Administrator. In this particular example, the database that we want to use is bcdemo.
Once you have figured out which database you want to connect to, you can use the
setDBQuery() method to import data. The setDBQuery() method accepts a number
of parameters. The syntax is as follows:
myPopChart.setDBQuery(graphname,"",databaseName,user,p
assword,SQLquery);
The first parameter, graphname, is the name of the graph object (see “What is my Object
Named?” on page 6-6) into which you want to import the data.
The second parameter is not used in the COM version of setDBQuery() and should be
set to an empty string.
6-28
www.corda.com
User Guide
.....
The third parameter is the actual name of the database, which you can identify in the
ODBC Data Source Administrator (e.g. bcdemo). Be sure that this database is
accessible from the computer running PopChart Embedder.
Note:
You can also make a DSN-less connection to a database. In this case, in place of a database
name, you would enter a string containing all of the parameters necessary to identify your
database. The actual syntax will depend on the database, but may look something like this:
Provider=SQLOLEDB.1;Password=MyPassword;Persist
Security Info=True;User ID=MyUserID;Initial
Catalog=Northwind;Data Source=MyDataServer
The fourth and fifth parameters are the user name and password for this database,
respectively. If no user name or password is required, you should pass an empty String. The
last parameter is your SQL query. This documentation assumes that you already know
enough about SQL to build this query yourself.
Example 6.17 shows how you would use this method to import data into the PopChart
image we created in Example 5.4. It assumes that your graph object is named graph, that
your user name and password are user and password, that your database is named
bcdemo, and that your SQL query is “Select Description, OnHand from parts order by
Description”. If you have access to a database, you could easily replace these values with
valid parameters and actually generate a PopChart image containing your data.
Example 6.17
Example Code for Importing from a DataBase in an ASP
set myPopChart = Server.CreateObject("PopChart.Embedder");
myPopChart.setDBQuery "graph", "", "bcdemo", "user", "password",
"Select Description, OnHand from parts order by
Description"
6-29
.....
PopChart
6
6-30
6(5 9(5
www.corda.com
I NTERACTIVE AND S PECIAL E FFECTS
T
.....
...................................
7
his chapter discusses interactive and special effects that you can incorporate into your
PopChart image. It will show you how to create and use these effects in PCScript and, in
many cases, PopChart XML.
Note:
Most of the issues discussed in this chapter are considered to be post-processing issues—i.e.
things that you add to your PopChart image after you’ve already formatted (created an
appearance file) and sent data to it.
The first two sections of this chapter, “PopChart Script Review” and “About PopChart
XML in this Chapter,” will review what you need to know to create these effects. It is
assumed that you already know how to embed a PopChart image into a web page (see
Chapter 4, “Embedding PopChart Images in a Web Page,” if you do not).
The remainder of this chapter discusses the following effects:
• Data Labels
• PopChart Notes
• PopUp Text
• Drill-down Effects
• Changing Colors and Styles Dynamically
• Changing Scale Formatting Dynamically
• Scale Markers
• HTML Data Tables
• Legends
• Text Boxes
• Imported Graphics
Note:
Many of the examples in this chapter can be applied directly to the example PopChart
image that we have been creating throughout this documentation (see Example 4.7 on
page 4-19). A good way to learn these features would be to plug them into the example and
see what happens.
7-1
.....
PopChart
7
6(5 9(5
INTERACTIVE AND SPECIAL EFFECTS
PopChart Script Review
.P. O. .P. .C. H. .A. .R. T. . .S. C. .R. .I .P. T. . R. . E. .V. I. E. .W. . . . . . . . . . . . . . . . . .
In the last chapter, we introduced PopChart Script (PCScript). Most of the effects that we
discuss in this chapter are generated with PCScript. In case you skipped the last chapter, you
might want to read “Introduction to PCScript” on page 6-10. We will also briefly review
PCScript here.
PCSCRIPT COMMAND FORMAT
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.
Every PCScript command that you send to PopChart Server will be in the following
format:
object.method(paramater1,parameter2,...)
Objects are created and named in the PopChart appearance file (see “About Appearance
Files” on page 1-6 of the PopChart Builder User Guide). PCScript commands use the
object names specified in the appearance file. For more info on object names, refer to “What
is my Object Named?” on page 6-6.
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.
PCSCRIPT COMMAND STRINGS
PCScript commands are sent to PopChart Server 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 7.1 demonstrates a valid PCScript command strings.
7-2
www.corda.com
User Guide
.....
PopChart Script Review
Example 7.1
graph.setCategories(Apples)textbox.setText(Apple Graph)graph.setSe
ries(Andy,10;Julie,14;Bryan,11)graph.addPopupText(1,
1-3,Apples are Good)graph.DDEnable(1,1-3,http://www.
applepies.com)
U S I N G P C S C R I P T W I T H T H E PopChart Embedder
You can send your PCScript command string via the pcScript attribute.
This attribute should be set to your PCScript command string. The code below illustrates the
use of the pcScript attribute in Java.
Example 7.2
Setting the PCScript Command String in PopChart Embedder
String pcscript="textbox.setText(Hello
World)graph.setCategories(Apple)graph.setSeries(And
y;10)setSeries(Joe;15)setSeries(Jenny;20)";
graphImage.pcScript = pcscript;
PCSCRIPT AND POPCHART XML
PCScript is perfectly compatible with PopChart XML. Your object names in PCScript will
be the same as your element names in PopChart XML. PCScript is processed after all
PopChart XML has been read.
7-3
.....
PopChart
7
6(5 9(5
About PopChart XML in this Chapter
ABOUT POPCHART XML IN THIS
CHAPTER
..................................................
Most PCScript commands have a PopChart XML equivalent. We will show you the
PopChart XML equivalent for some of those commands in this chapter. There are also
several things that you can do with PopChart XML that you can’t do in PCScript.
When we show you how to do something in PopChart XML, we will simply show you the
appropriate PopChart XML elements or attributes to add or use. It will be up to you to get
your PopChart XML to PopChart Server, through either an appearance file or the
loadPCXML(String) and addPCXML(String) PopChart Embedder methods. You
should probably read Chapter 10, “Using PopChart XML,” to learn how to use PopChart
XML.
In general, we will not include the Chart element in our examples. Be aware, though, that
all PopChart XML elements that you send to PopChart Server must be surrounded by the
Chart tag, as that is the top level element in a PopChart XML document.
In the future, PopChart Server will move more towards PopChart XML as the standard
way for customizing your PopChart image. As we do that, the examples for PopChart XML
will become more and more frequent, as well as easier to use.
7-4
www.corda.com
User Guide
.....
Data Labels
.D. A. .T. .A. .L. .A. B. .E. L. .S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you’ve viewed the example PopChart image that we’ve been customizing throughout this
documentation (see Example 4.7 on page 4-19) in a web browser, you probably noticed
that the values for each bar appear in a box above the bar as you move your mouse over that
bar.
This small box is called a data label. Data labels help indicate the value(s) of certain data
items. Any graph can have them. And now, with PopChart Server 4.0.5, you have
complete control over what exactly appears in the data label box.
Note:
If you need a box to pop up over just one or a few data items, you should use PopUp text
(refer to “PopUp Text” on page 7-12).
TURNING DATA LABELS ON
Most of the time, you will turn data labels on in your appearance file. In fact, by default,
rollover data labels are turned on automatically for any graph that you create in PopChart
Builder. To turn them on or off, you can right click on a graph, select Data Labels, and
choose an appropriate setting for Show Data Labels.
You can also turn them on or off in PopChart XML. To do so, use the DataLabels
element. Set its Visible attribute to True to enable them, or False to disable them. If
there is no DataLabels tag, or there is no Visible attribute, data labels are assumed to
be on.
<DataLabels Visible="True" />
ROLL-OVER VERSUS ALWAYS ON
There are two ways of displaying data labels: always on, and roll-over. Always on means
that the data labels will always be visible over every data item. Roll-over means that a data
label will appear only as a user “rolls” his or her mouse over the data item it is associated
with. Rollover data labels is the default setting.
7-5
.....
PopChart
7
6(5 9(5
Data Labels
You can select the data label display method in the Show Data Labels box of PopChart
Builder.
You can select the data label display method in PopChart XML by setting the
ShowOnRollover attribute of the DataLabels element. Setting it to true sets the
display method to rollover (default), and setting it to false sets the display method to always
on, as is the case with the following tag.
<DataLabels ShowOnRollover="False" />
Note:
Rollover data labels is supported in GIF and PNG images via image maps. There are
several consequences of this. First of all, you cannot use rollover data labels in GIF or PNG
images without the PopChart Embedder. Also, feedback for rollover data labels in GIF
and PNG images may be slow no matter how you embed your PopChart images. Finally,
you will be unable to customize the appearance of your rollover data labels.
CHANGING THE DATA LABEL FORMAT
A new feature in PopChart Server 4.0.5 is the ability to customize the format of your data
labels.
Data Labels can now be customized using macros. For example, in previous versions you
only had one option for displaying data labels: the number only. Now, using macros, instead
of having a data label that says 43, you can have one that says Price: $43. When combined
with showing data labels on rollover, customized data label formatting may virtually
eliminate the need for PopUp Text.
7-6
www.corda.com
User Guide
.....
Data Labels
Macros are text keywords that stand for a data-specific value, such as a series or category
name, or a data value. By using macros, you can make it so that each data label contains
information pertinent only to the data item it is associated with.
Table 7.2 lists the available data label formatting macros.
TABLE 7.2 Data Label Macros
....................................................
Macro
Description
Graphs
%_CATEGORY_NAME
The name of the category that the data item
belongs to.
All, except
X-Y and
Time Plot
%_CATEGORY_TOTAL
The sum of all data values in the category to
which the data item belongs.
Area, Bar,
Line, Pareto,
Pie, Radar
%_CLOSE_VALUE
The close value for a high-low data item.
Stock
%_GRAPH_TOTAL
The sum of all data values in a bar, line, pie, or
radar graph.
Area, Bar,
Line, Pareto,
Pie, Radar
%_HIGH_VALUE
The high value for a high-low data item.
Stock
%_LOW_VALUE
The low value for a high-low data item.
Stock
%_OPEN_VALUE
The open value for a high-low data item.
Stock
%_PERCENT_OF_CAT
EGORY
The data value represented as a percentage of the
sum of all data values in its category.
Area, Bar,
Line, Pareto,
Pie, Radar
%_PERCENT_OF_TOT
AL
The data value represented as a percentage of the
sum of all data values in the graph.
Area, Bar,
Line, Pareto,
Pie, Radar
%_SERIES_NAME
The name of the data series that the data item
belongs to.
All
%_TIME_VALUE
The time value for a Time Plot data item.
Time Plot
%_VALUE
The value of the data item.
Area, Bar,
Line, Pareto,
Pie, Radar
%_XVALUE
The x value for an X-Y data item.
X-Y
%_YVALUE
The y value for an X-Y or Time Plot data item.
X-Y, Time
Plot
PopChart Builder
To customize your data labels in PopChart Builder, select a graph, right click on it, and
select Data Label Properties. The Data Label Format (All Graphs Except Pie)
text box lets you change the data label format. A list of available macros is shown below the
Value keywords pull-down menu below. You can insert any of these macros into the text
box by selecting the macro and clicking on the Insert button.
7-7
.....
PopChart
7
6(5 9(5
Data Labels
In PopChart Builder, you can also change the data label format for an individual data
series. Simply edit the value in the Data Label Format text box of the Series
Properties > Data Labels pane.
PCSCRIPT
To customize your data label with PCScript, use the graph.SetDataLabelFormat()
method. This method accepts a string of text and macros.
For example, by default the data label format is simply %_VALUE. This will display only
the data value in the data label. If you wanted the data label to display the data series name,
followed by a colon, followed by a dollar sign, followed by the data value (e.g Price: $43),
you could change the data label format to %_SERIES_NAME: $%_VALUE. The PCScript
command below sets this format for you:
graph.setDataLabelFormat(%_SERIES_NAME: $%_VALUE)
POPCHART XML
You can also customize your data label in PopChart XML by setting the FormatString
attribute of the DataLabels element, as shown below.
<DataLabels FormatString="%_SERIES_NAME: $%_VALUE" />
7-8
www.corda.com
User Guide
.....
PopChart Notes
.P. O. .P. .C. H. .A. .R. T. . .N. O. . T. .E. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A new feature in PopChart 4.0.5 is PopChart Notes. Notes are a combination of text boxes
and PopUp text (in fact, another name for them is Sticky PopUp). Like PopUp text, they are
attached to a specific data item. However, like text boxes they are always visible. Notes
"call-out" from the data item—there is a leader line from the data item to the note box.
Example 7.3 below shows a PopChart image that uses notes. The appearance file for this
image is located in chart_root/examples/apfiles/notetest.pcxml.
PopChart Note
Example 7.3
DYNAMIC POPCHART NOTES
PopChart Notes can be added dynamically to a graph. You can change the way that dynamic
Notes look in the Graph Properties > Notes dialog pane.
PCSCRIPT
To add a note dynamically in PCScript, simply pass the following parameters to an
graph.AddNote() method: the category number or name, the series number or name,
and the text of the note. So, for example, to add the note Here is the Highest Point to the
data item in the first category and the second series, you could use this method call:
7-9
.....
PopChart
7
6(5 9(5
PopChart Notes
graph.addNote(1,2,Here is the Highest Point)
The next example illustrates two points: you can add multiple notes in the same
AddNote() call by separating each note by a semi-colon, and you can use the actual name
of a category or series to identify a data item. This line of PCScript will add both of the
yellow notes that you see in Example 7.3.
graph.addNote(Under-Water Basket
Weaving,Attendance,Here is the Highest Point; RocksPaper-Scissors,Profit,Here is the Lowest Point)
For graphs that do not have categories (X-Y and Time Plot), you should specify the number
of the data item instead of the category. In other words, if the data item is the fifth in a data
series, you would specify 5 as the first parameter.
Warning:
Do not use the Sort Data feature of X-Y or Time Plot graphs when you use notes—
if you do, your Note may be associated with the wrong data item.
POPCHART XML
You can also add a note to a data item by setting the Note attribute of the Data element in
PopChart XML, as shown below. Adding a note in PopChart XML must be done when you
send your data to PopChart Server.
<Data Value="34" Note="Here is the Lowest Point" />
ATTACHING POPCHART NOTES TO TEXT BOXES
Another interesting feature of PopChart Notes is that you can attach them to a text box.
When you do this, the text box becomes the PopChart Note. This allows you greater control
over the placement of a note. It is also useful when you want several notes that have
different formats than dynamically generated notes, such as the Note that reads Neither
High nor Low in Example 7.3.
When you attach a Note to a text box, you may want to set the text box so that it will only
appear if it is attached to a Note. This way, if you decide not to attach a Note to the text box,
the text box will be invisible. To do this, go to the General pane of the Text Box
Properties dialog and check the Only Display Textbox as a Note box. Or, in
PopChart XML, set the IsNoteTextbox attribute of a text box’s Properties tag to
True.
If you are creating text boxes for the sole purpose of using them as PopChart Notes, you
may also want to consider creating static PopChart notes in PopChart Builder, which allow
you to better see how the text box would look as a PopChart note, as well as set the Only
Display Textbox as a Note option for you. See “Using Static PopChart Notes” on
page 1-17 of the PopChart Builder User Guide.
7-10
www.corda.com
User Guide
.....
PopChart Notes
PCSCRIPT
You can attach a note to a textbox in PCScript by setting a parameter in your
graph.AddNote() method. This fourth parameter should be the name of the text box
associated with the note. For example, if the textbox were named notebox1, we would
attach a note to it using the following PCScript command:
graph.AddNote(2,2,Neither High Nor Low,notebox1)
POPCHART XML
You can also attach a note to a textbox using the NoteTarget attribute of the PopChart
XML Data element. Simply set the value of this attribute to the name of the associated text
box.
7-11
.....
PopChart
7
6(5 9(5
PopUp Text
.P. O. .P. .U. P. . .T. E. .X. T. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Popup text is used to display additional or supplemental information about an item (bar, pie
wedge, or x-y point) in a graph. PopUp text is called PopUp text because it “pops” up as the
user places his or her mouse over an item in a graph.
Popup Text looks a lot like a roll-over data label, but it is assigned to a specific data item,
like a Note. Like PopChart Notes, PopUp text is useful when you want to call someone’s
attention to an important fact about a specific data item.
Note:
If you would like your PopUp text to show data values or series names for every data item in
the graph, you should use PopChart Server’s new custom data label feature instead (refer
to “Changing the Data Label Format” on page 7-6).
The image below shows a Pie Chart that uses PopUp text. The appearance file for this image
is located at examples/apfiles/piepopup.pcxml.
Note:
7-12
PopUp text is supported in GIF and PNG images via image maps. There are several
unfortunate consequences of this. First of all, you cannot use PopUp text in GIF or PNG
images without the PopChart Embedder. Also, feedback for PopUp text in GIF and PNG
images may be slow no matter how you embed your PopChart images. In Netscape®
browsers, you may be unable to get PopUp text without also enabling a drill-down effect for
www.corda.com
User Guide
.....
PopUp Text
the specified data item. Finally, you will be unable to customize the appearance of your
PopUp text.
ADDING POPUP TEXT
You can add PopUp text to your graph dynamically with PCScript or PopChart XML.
Note:
You can change the format of your PopUp text in the Graph Properties > PopUp
dialog pane of PopChart Builder.
PCSCRIPT
To add popup text to a graph use the graph.AddPopupText() method in PCScript. The
first parameter of the graph.AddPopupText() method is the name, or number of the
category. The second parameter is the name or number of the series. The third parameter is
the text that will be shown.
The following PCScript generated the PopUp text in the above:
Graph.AddPopupText(1, 2, Pretzel Sales were Low Due to
Inadequate Supply)
For graphs that do not have categories (X-Y and Time Plot), you should specify the number
of the data item instead of the category. In other words, if the data item is the fifth in a data
series, you would specify 5 as the first parameter.
Warning:
Do not use the Sort Data feature of X-Y or Time Plot graphs when you use PopUp
text—if you do, your PopUp text may be associated with the wrong data item.
POPCHART XML
You can also add PopUp text to a data item by setting the Popup attribute of the Data
element in PopChart XML, as shown below. Adding PopUp text in PopChart XML must be
done when you send your data to PopChart Server.
<Data Value="34" Popup="This is PopUp Text" />
7-13
.....
PopChart
7
6(5 9(5
Drill-down Effects
.D. R. .I.L. L. .-.D. O. . W. . N. . .E. .F.F. E. .C. .T. S. . . . . . . . . . . . . . . . . . . . . . . .
Using PopChart Server’s drill-down capabilities, you can associate URL links or
JavaScript functions with data items in your PopChart image. This functionality is referred
to as drill-down because it is most often used to allow a user to navigate from PopChart
image to PopChart image. The user can click on a data item such as a bar or pie wedge in a
graph on one web page and be brought to a graph on a different web page that expands upon
the data item.
For example, suppose a PopChart image on your web site contains a graph that represents
the annual sales for each product that your company offers. Each bar in that graph contains a
link to another web page on your site with a PopChart image that breaks down the sales for
the corresponding product. The user can access the link, view the more detailed
information, and return back to the original graph.
Note:
Drill-down is supported in GIF and PNG images via image maps. There are several
unfortunate consequences of this. First of all, you cannot use drill-down effects in GIF or
PNG images without the PopChart Embedder. Also, feedback for drill-down effects in
GIF and PNG images is limited to the mouse pointer changing into a hand.
For an example of drill-down in action, see the drill-down example in the Dynamic HTML
version of the PopChart Examples book.
INDIVIDUAL DRILL-DOWN EFFECTS
Like PopUp Text or Notes, you can associate drill-down effects with individual data items.
PCSCRIPT
To enable a data item for drill-down effects in PCScript, use the graph.DDEnable()
method. The first parameter of the graph.DDEnable() command is the name or number
of the category. The second parameter is the name or number of the series. The third
parameter is either a URL or a JavaScript function call. An optional fourth parameter is the
name of the target in the web page.
For example, if you wanted users to drill-down to the website http://mycompany.com
whenever they clicked on the data item in category number one and series number two, you
would use the following PCScript command:
Graph.DDEnable(1,2,http://mycompany.com)
If you know what the category and series are named, you could refer to them instead. For
example, you could have the data item in the Boston series and the Departures category
drill-down to http://mycompany.com/bostonrentals.html with the following PCScript
command.
7-14
www.corda.com
User Guide
.....
Drill-down Effects
Graph.DDEnable(Departures,Boston,http://mycompany.com/
bostonrentals.html)
If you wanted to drill-down to a pre-defined JavaScript function, all you have to do is
specify the URL for your JavaScript function. This is done by inserting javascript: before
the function. For example, if you have defined a JavaScript function called
replaceImage() in your web page, you could drill-down to it with the following
PCScript command:
Graph.DDEnable(11,7,javascript:replaceImage())
POPCHART XML
You can also add a drill-down effect to a data item by setting the DrilldownURL attribute
of the Data element in PopChart XML, as shown below. Adding a drill-down effect in
PopChart XML must be done when you send your data to PopChart Server.
<Data Value="34" DrilldownURL="http://mycompany.com" />
GLOBAL DRILL-DOWN EFFECTS
Like data labels, drill-down effects can take advantage of macros to yield data-specific drilldown effects for each data item in the graph. This new feature allows you to create a global
drill-down destination—for example, a context-sensitive web application that generates a
new PopChart image based upon the category and series of the data item that the user
clicked on. For most users, this may eliminate the need for setting individual drill-down
effects.
For example, you could set your global drill-down destination to
morestats.jsp?%_SERIES_NAME. If a user clicks on any data item in the Blue series,
PopChart Server will drill-down to the address morestats.jsp?Blue.
Table 7.3 lists the available drill-down macros.
TABLE 7.3 Drill-down Macros
...................................................
Macro
Description
Graphs
%_CATEGORY_NAME
The name of the category that the data
item belongs to.
All, except X-Y
and Time Plot
%_CATEGORY_NUMBER
The number of the data series that the
data item belongs to.
All, except X-Y
and Time Plot
%_POINT_NUMBER
The number of the data item in the data
series (e.g, the first plot point=1).
X-Y and Time
Plot
%_SERIES_NAME
The name of the data series that the
All
7-15
.....
PopChart
7
6(5 9(5
Drill-down Effects
TABLE 7.3 Drill-down Macros
...................................................
Macro
Description
Graphs
%_SERIES_NUMBER
The number of the data series that the
All
PopChart Builder
You can set a global drill-down address for your appearance file in PopChart Builder.
Simply edit the Drill-down URL text box of the Graph Properties > Drill-down
dialog pane.
PCSCRIPT
In PCScript, instead of a category or series number, you can specify a range of categories or
series. A range is indicated by the number of the starting category or series, followed by a
hyphen, followed by the number of the ending category or series.
For example, if you want an effect to occur on data items in series two through seven, you
would specify 2-7 instead of a series number. The code below creates a drill-down effect for
any data item that is in categories 6-9 and in series 5-8.
graph.DDEnable(6-9,5-8,drilldown.html)
Thus, to add or change a graph’s global drill-down destination, simply set the value of
category and series parameters in the graph.DDEnable() method to ranges that include
every data item in the graph. With most data sets, 1-99 will suffice, but if you’re inputting a
large amount of data, you may need to use a larger range (the range can be greater than the
actual number of categories or series).
For example, the following line of code creates the morestats.jsp drill-down link from the
beginning of this subsection.
graph.DDEnable(1-99,1-99,morestats.jsp?%_SERIES_NAME)
Similarly, if you just wanted to have a drill-down effect for one series, you could specify a
range of 1-99 for the categories, and then specify the name or number of the series that you
want this effect to apply to. The example below would add an effect just to the Atlanta
series.
graph.DDEnable(1-99, Atlanta, javascript:alert(The
number of cars in the %_CATEGORY_NAME category is
%_VALUE))
POPCHART XML
To set a global drill-down effect, simply change the MetaString attribute of the
Drilldown subelement of a graph object, as shown below.
7-16
www.corda.com
User Guide
.....
Drill-down Effects
<Graph Name="graph"><Drilldown
MetaString="morestats.jsp?%_SERIES_NAME" /></Graph>
7-17
.....
PopChart
7
6(5 9(5
Changing Colors and Styles Dynamically
CHANGING COLORS AND STYLES
DYNAMICALLY
..................................................
There are many dynamic changes you can make to the colors and styles of the data items in
your graph, including:
•
• Changing the Color of a Data Series
• Changing Colors for Individual Data Items
• Changing Data Series Styles
CHANGING THE COLOR THEME
Color themes specify colors for up to sixteen data series. These colors will be used for any
bars, lines, symbols, pie wedges, and filled areas in the series. You can change a color theme
for a graph in PopChart Builder by going to the Graph Properties > Colors dialog
pane and selecting a new color theme from the Select a Color Theme pull-down menu.
PopChart 4.0.5 comes with several predefined color themes, including:
• Default
• Standard 16
• Pastel
• Southwest
• Everglades
• Ocean
• Subdued
• Standard Translucent
You can also create new color themes. For information on how to do this, refer to
Chapter 11, “Color Themes,” in the PopChart Server Reference manual.
PCSCRIPT
You can change the color theme for a graph in PCScript with the
graph.UseColorPalette() method. This method accepts as an argument the name
of a color theme. For example, to use the ocean color theme, you would add the following
PCScript command:
graph.useColorpalette(Ocean)
7-18
www.corda.com
User Guide
.....
POPCHART XML
New in PopChart Server 4.0.1
You can change the color theme for a graph in PopChart XML by setting the Name attribute
of the graph’s ColorPalette subelement to the name of the color theme that you want to
use. For example, the tag below changes the graph’s color theme to Subdued.
<Graph Name="graph"><ColorPalette
Name="Subdued" /></Graph>
CHANGING THE COLOR OF A DATA SERIES
You can change the colors of your data series dynamically.
PCSCRIPT
PCScript uses special commands to override the colors of various items (such as a series,
symbol, line, bar, etc.). The override command for color is CLR_. This command should be
followed by a six or eight digit hexadecimal color code (e.g. FF0000 for red, FF000088 for
translucent red). There should not be a pound sign before the color.
Color override commands are used in the graph.SetSeries() and
graph.SetCategories()methods. They should be placed in parenthesis in front of
the item they apply to. So, to change the color for an entire data series to green, you would
place (CLR_00FF00) in front of the series name in the graph.SetSeries() method,
as done in the following example:
graph.setSeries((CLR_00FF00)Atlanta; 23; 36; 11; 7)
There are many other override commands, including ones that allow you to override area fill
colors, bubble colors, and outline colors. For a complete list of these override commands,
refer to Table 5.8 on page 5-33 of the PopChart Server Reference manual.
POPCHART XML
In PopChart XML, to change a series color, you will need to override its series definition
tag. You can do this by changing the Color attribute of a graph’s SeriesDefinition
subelement for the series whose color you want to change. For example, the tag below
changes the color of the fifth series to green.
<Graph Name="graph"><SeriesDefinition Number=’5’
Color=’#00FF00’ /></Graph>
7-19
.....
PopChart
7
6(5 9(5
CHANGING COLORS FOR INDIVIDUAL DATA
ITEMS
Sometimes, you may want to change the colors of an individual data item dynamically. For
example, perhaps you want to emphasize a single data item in your graph by changing its
color to red. In the image below, we have changed the color of one of the bars in the
PopChart image from Example 4.7.
Hello World
PCSCRIPT
PCScript uses special commands to override the colors of various items (such as a series,
symbol, line, bar, etc.). The override command for color is CLR_. This command should be
followed by a six or eight digit hexadecimal color code (e.g. FF0000 for red, FF000088 for
translucent red). There should not be a pound sign before the color.
Color override commands are used in the graph.SetSeries() and
graph.SetCategories()methods. They should be placed in parenthesis in front of
the item they apply to. So, to change the color for an individual data item to red, you would
7-20
www.corda.com
User Guide
.....
place (CLR_FF0000) in front of the series name in the graph.SetSeries() method,
as done in the following example:
graph.setSeries(Atlanta; 23; 36; (CLR_FF0000)11; 7)
There are many other override commands, including ones that allow you to override area fill
colors, bubble colors, and outline colors. For a complete list of these override commands,
refer to Table 5.8 on page 5-33 of the PopChart Server Reference manual.
POPCHART XML
You can also change the color of a data item by setting the Color attribute of the Data
element in PopChart XML, as shown below. Changing a data item’s color in PopChart XML
must be done when you send your data to PopChart Server.
<Data Value="34" Popup="This is PopUp Text" />
CHANGING DATA SERIES STYLES
For certain graphs, including Line, X-Y, Time Plot, Area, Bubble, and Radar, you can
change some or all of the following settings: line width, symbol type, area fill, and bubble
type.
PCSCRIPT
To change these settings in PCScript, you should use the graph.SetSeriesStyle()
method. For information about this method, you should refer to page 5-34 of the PopChart
Server Reference manual.
POPCHART XML
To change these settings in PopChart XML, you should override a graph’s
SeriesDefinition element for the series that you are changing. The following
attributes may be of interest to you: LineWidth, SymbolType, AreaFill, and
BubbleType.
7-21
.....
PopChart
7
6(5 9(5
Changing Scale Formatting Dynamically
CHANGING SCALE FORMATTING
DYNAMICALLY
..................................................
When you create your appearance file in PopChart Builder, you are able to customize the
general appearance of your scales in the various scale properties dialogs. In most cases, you
will provide the appearance file with several preferences regarding the appearance of your
scale labels, and then elect to have PopChart Server automatically format your scale
labels.
Most of the time, PopChart Server will automatically format your scales and scale labels
in such a manner as to keep them meaningful and visually appealing. In certain situations,
though, you may want to manually format your scale labels.
ABOUT SCALES
Scales appear along the sides and bottom of your graph area. They help identify data items
and their values. Along each scale are several tick marks, which correspond to gridlines in
the area behind the graph. At each major tick mark (the larger ones), there will be a scale
label.
Note:
There are also a number minor tick marks between each major tick mark. You cannot
control the format of minor tick marks dynamically.
Gridlines
Value Scale
Major Tick Mark
Minor Tick Mark
Category Scale
Scale Label
7-22
www.corda.com
User Guide
.....
There are two main types of scales: category scales and value scales.
The category scale is almost always along the bottom of the graph (the exception being
Horizontal Bar graphs). Scale labels and tick marks along category scales, of course,
correspond to categories. You cannot format a category scale dynamically—however, you
can customize the behavior of your category scale in PopChart Builder (see “Scale Label
Adjustments” on page 1-22 of the PopChart Builder User Guide).
Value scales are used to indicate the value of a certain data item. In graphs that use
categorical data, there will be one value scale, either on the left or right of the graph. Line
Bar graphs also have a secondary value scale for the scale that appears on the right. In plot
graphs, there are two value scales: one on the bottom and one on the side. Dual y scale
graphs also have a y2 scale opposite of the main value scale.
The range of your value scales greatly affects the look of your graph, as the size of your data
items depend upon the scale range. For example, a bar value of 78 in a scale range of 0-80
would go almost to the top of the graph, while in a scale range of 50-500 it would barely be
visible. Likewise, a bar with the value of 40 would be invisible in a range of 50-500, while it
would be cut off in a range of 0-30.
PCSCRIPT SCALE NAMES
When you adjust the formatting of a value scale in PCScript, you will use the
graph.SetScale() method. The first parameter of this method will always be the name
of the scale that you want to dynamically adjust. These names are pre-set, and are as
follows:
value
Main value scale.
svalue
Secondary value Scale
x
X Scale
y
Y Scale
y2
Secondary y scale
time
Time scale
AUTOMATICALLY SETTING THE SCALE RANGE
Automatic scaling is a convenient feature that is turned on by default in most appearance
files. But for those who always like to know what PopChart Server is doing, it can be
somewhat confusing.
When your scale range is set to automatic, PopChart Server looks for the highest and
lowest data item and makes sure that the scale is at least n percent higher and n percent
lower than those data items (n is set by the appearance file, and is usually 10). By default,
most graphs are set so that the base of the scale is zero, unless there is a negative data
7-23
.....
PopChart
7
6(5 9(5
item.You can adjust these settings in your appearance file with Scale Properties menus
in PopChart Builder.
PopChart Server will also adjust the starting and ending points, as well as the scale labels,
so that they are on nice, even numbers, such as multiples of ten or twenty or one hundred.
The exact numbers it chooses will depend on the overall range for your data.
When you use the graph.SetScale() in conjuction with automatic scaling, you can
provide PopChart Server with a few other preferences that affect the way it determines
scales. You can send it a maximum and minimum value for the scale range, as well as a limit
to how many tick marks should be shown. PopChart Server will set the scale so that it is
no smaller than the range you provided with the maximum and minimum values. It will still
try to even out the range so that the scale labels are still nice, round numbers. It will ignore
the maximum or minimum value if the size of the scale would have been larger without the
specified maximum or minimum value. PopChart Server will also make sure that there are
no more tick marks than the number you specified, although there may be less.
PCSCRIPT
To use automatic scaling in PCScript, simply set the second argument of
graph.SetScale() to auto. The third parameter you specify should be the maximum
value for the scale. The fourth parameter, which is optional, should be the minimum value.
The fifth parameter, which is also optional, should be the maximum number of ticks.
For example, to tell PopChart Server to use automatic scaling on the y scale with a
maximum value for the scale range of 195, a minimum value of 95, and a maximum number
of ticks value of 8, you would use the following command.
graph.setScales(y, auto, 195, 95,8)
POPCHART XML
To use automatic scaling, set the value of the SetScaleValues attribute in your graph’s
ValueScale element to Automatically. Then set the following attributes:
MinimumValue, MaximumValue, and MaximumMajorTicks. You may also be
interested in these attributes: PercentUnderMinValue, PercentOverMaxValue,
and SetScaleBaseToZero.
MANUALLY SETTING THE RANGE
You can also manually set the range of your scales. Fortunately, PopChart Server’s
behavior in this case is much more intuitive. The values you set for maximum, minimum,
and number of ticks is exactly what PopChart Server will end up using.
PCSCRIPT
To manually set the range of a scale, you will set the second parameter of
graph.SetScale() to manual and the third parameter to the maximum value of the
7-24
www.corda.com
User Guide
.....
scale range. If you want to set a minimum value for a range, simply include a fourth
parameter specifying the minimum value. To set the number of major ticks in your graph,
you can also set a fifth parameter.
For example, to set the maximum value of your value scale range to 1000, you would use
the following command.
graph.setScale(value,manual,1000)
If you wanted to set the range of the scale along the x-axis of an X-Y graph to 500-1000,
you would use the following command.
graph.setScale(value,manual,1000,500)
Finally, to set the number of major tick marks that will appear in your graph to 8, you would
use the following command.
graph.setScale(manual,1000,500,8)
POPCHART XML
You can also manually set the range in PopChart XML. To do this, simply override the
MaximumValue, MinimumValue, and ManualMajorTicks attributes of a graph’s
ValueScale element. You will also need to set the SetScaleValues attribute to
Manually, as shown below.
<ValueScale Position="Left" SetScaleValues="Manually"
MaximumValue="1000" MinimumValue="500"
ManualMajorTicks="8" />
7-25
.....
PopChart
7
6(5 9(5
LOGARITHMIC SCALES
A new feature in PopChart Server 4.0.5 is logarithmic scales. These allow you to better
graph large ranges of data values.
You can enable logarithmic scales in an appearance file by selecting Use Logarithmic
Scales from the General pane of a Value Scale Properties dialog.
You can enable logarithmic scales dynamically in PopChart XML by setting the
UseLogScale attribute of your ValueScale element to True.
<ValueScale Position="Left" UseLogScale="True"/>
7-26
www.corda.com
User Guide
.....
Scale Markers
.S. C. .A. .L.E. . .M. A. . R. .K. .E. R. .S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
You can use scale markers to emphasize data items that are above or below a certain level,
or emphasize data items in a certain range.
There are two types of scale markers. The first type is a line scale marker, which is a
horizontal or vertical line drawn over the graph at a certain index along the scale. The
second type is a range scale marker, which appears as a highlighted area behind the graph,
between a maximum and minimum index along the bottom or side scales.
The image below shows a line scale marker (the red line), and two range scale markers (the
red and green areas behind the graph).
ADDING A SCALE MARKER WITH PCSCRIPT
To add a scale marker in PCScript, you should use the graph.AddScaleMarker()
method. The first parameter of this method is the position of the scale that you want to add
the scale to. These names are pre-set, and are as follows:
value
Main value scale.
svalue
Secondary value Scale
x
X Scale
y
Y Scale
y2
Secondary y scale
time
Time scale
The next parameter should be the scale marker type (range or line). The third parameter
will be the low value of the range or the width of the line, depending on your scale marker
7-27
.....
PopChart
7
6(5 9(5
Scale Markers
type. The fourth parameter will be the high value of the range or the index of the line. The
final parameter that you pass will be the color of the scale marker.
For example, to create the green area in the example image at the beginning of this section,
you would use the following command.
graph.addScaleMarker(value,range,0,50,99eeaa)
If you don’t know what the maximum or minimum value in your graph is, but want to use
those values in your range, you can use the scaleMax and scaleMin entities instead.
For example, the previous line of code could also be:
graph.addScaleMarker(value,range,scaleMin,50,99eeaa)
To create the red line in the same image, you would add this command.
graph.addScaleMarker(value,line,1,25,cc0000)
ADDING A SCALE MARKER WITH POPCHART XML
To add a scale marker in PopChart XML, add a ScaleMarker subelement to your Graph
element. For example, to create the green area in the example image at the beginning of this
section, you would add the following subelement.
<ScaleMarker Position="Value" Type="Range" Low="0"
High="50" Color="#99eeaa" />
To create the red line in the same image, you would add this element.
<ScaleMarker Position="Value" Type="Line" Value="25"
Color="#cc0000" />
7-28
www.corda.com
User Guide
.....
HTML Data Tables
.H. T. .M. .L. .D. .A. T. .A. . T. .A. .B. L. .E. S. . . . . . . . . . . . . . . . . . . . . . . . . . .
A new feature in PopChart Server 4.0.5 is the ability to automatically display an HTML
table of your data below your graph. The HTML table will display the exact same data as
your graph. The image below shows what a web page would look like with the HTML data
table added to the PopChart image from Example 4.7.
You can add an HTML table to your graph simply by adding the
addHTMLTable(String,String) method to your PopChart Embedder code. This
method accepts up to two parameters. The first parameter should be the name of the graph
7-29
.....
PopChart
7
6(5 9(5
HTML Data Tables
that you want to display data for, which is usually graph. The second parameter, which is
optional, is the title of your table.
Note:
This method does not work with the JavaScript PopChart Embedder.
For example, the following line of PopChart Embedder code would tell PopChart
Server to return an HTML table for the example PopChart image above:
myPopChart.addHTMLTable("graph","Car Rental Data");
You can also customize the way your data is translated into an HTML table by modifying
the config/tables.xml file (refer to Chapter 9, “HTML Table Settings,” in the PopChart
Server Reference manual).
7-30
www.corda.com
User Guide
.....
Legends
.L.E. .G. .E.N. .D. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Although most aspects of your legend are controlled by PopChart Server (or by
preferences you set in the appearance file with PopChart Builder), you still control several
aspects of your legends dynamically.
DRILL-DOWN ON A LEGEND ITEM
Items inside of a legend can be enabled for drill-down effects. For example, you could add a
drill-down effect to Atlanta in the legend of the PopChart image that we created in
Example 4.7.
For information about drill-down effects in general, see “Drill-down Effects” on page 7-14.
PCSCRIPT
To add drill-down to an item in the legend with PCScript, you should use the
graph.DDEnable() method, just as you would for a data item in a graph (see
“PCScript” on page 7-14). The only difference is that you add the effect to category 0,
which represents the legend.
For example, to add drill-down to the Atlanta item in a legend, you would use the following
PCScript:
Graph.DDEnable(0, Atlanta, http://mycompany.com)
POPCHART XML
To add drill down for a legend item, you should add a Drilldown attribute to the Series
element that corresponds to the legend item (Series is a subelement of GraphData). For
example, to enable drill-down for the Atlanta legend item, the Series tag for Atlanta
would look like this:
<Series Name="Atlanta"
Drilldown="http://www.mycompany.com" />
HIDING A LEGEND
Another useful feature is the ability to hide a legend. If your appearance file already
contains a legend, but you don’t want to show it in certain instances, you can use PCScript
or PopChart XML to turn it off.
7-31
.....
PopChart
7
6(5 9(5
Legends
PCSCRIPT
To hide a legend in PCScript, simply use the legend.Hide() method. For example, if
your legend is named legend, you can make it disappear with the PCScript command
from below.
legend.Hide()
POPCHART XML
To hide a legend in PopChart XML, simply override its Visible attribute to false. For
example, if your legend is named legend, you could hide it with the following PopChart
XML.
<Legend Name="legend" Visible="False" />
ADDING A LEGEND WITH POPCHART XML
If your appearance file does not contain a legend, but you would like to add one, you can
add a legend by declaring a new legend item in PopChart XML. For example, if you wanted
to add a legend for the graph named graph, you could do it with the following tag:
<Legend Name="legend" GraphName="graph" Top="400"
Left="10" Width="400" Height="50" />
Important:
7-32
When you add a legend, be sure to associate it with a graph. You do this by setting the
GraphName attribute to the name of the graph with which that the legend is associated.
Also, be sure to give your legend a distinct name (one that is not already being used).
www.corda.com
User Guide
.....
Text Boxes
.T.E. .X. T. . .B. O. . X. .E. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Although the formatting of an appearance file is set in PopChart Builder and cannot be
changed dynamically (unless you override its PCXML), there are several aspects of text
boxes that you can change dynamically, including setting the text, enabling drill-down, and
hiding a text box.
SETTING THE TEXT IN A TEXT BOX
One of the most useful things to do with a text box dynamically is to change its text.
PCSCRIPT
In PCScript, you can change the text inside of a text box using the textbox.SetText()
method. For example, if you have a title text box, you could change its text to Car
Inventory using the following command.
title.setText(Car Inventory)
Note:
It is useful to have a textbox named title in your appearance file. This way, PopChart
Server knows what to name your PopChart image when it generates descriptive text. For
more information, refer to the section entitled “Setting the Title of Your Descriptive Text”
on page 8-8.
POPCHART XML
In PopChart XML, you can change the text inside of a text box by changing the value of the
Textbox element itself. For example, if you have a title text box, you could change its text
to Car Inventory using the following tag.
<Textbox Name="title">Car Inventory</Textbox>
DRILL-DOWN FOR A TEXT BOX
You can also enable drill-down effects for a text box. For information about drill-down
effects in general, see “Drill-down Effects” on page 7-14.
PCSCRIPT
To add a drill-down effect to a text box, simply use the textbox.DDEnable() method.
For example, to add a drill-down link from a text box named textbox to
http://mycompany.com, you would use the following PCScript command:
textbox.DDEnable(http://mycompany.com)
7-33
.....
PopChart
7
6(5 9(5
Text Boxes
POPCHART XML
To add a drill-down effect to a text box with PopChart XML, simply add a
DrilldownURL attribute to the Text subelement of your Textbox element, as shown in
the example below.
<Textbox Name="textbox"><Text
DrilldownURL="http://mycompany.com" /></Textbox>
HIDING A TEXT BOX
Another useful feature is the ability to hide a text box. If your appearance file already
contains a text box, but you don’t want to show it in certain instances, you can use PCScript
or PopChart XML to turn it off.
PCSCRIPT
To hide a text box in PCScript, simply use the textbox.Hide() method. For example, if
your textbox is named title, you can make it disappear with the PCScript command from
below.
title.Hide()
POPCHART XML
To hide a text box in PopChart XML, simply override its Visible attribute to false. For
example, if your text box is named title, you could hide it with the following PopChart
XML.
<Textbox Name="title" Visible="false" />
ADDING A TEXT BOX WITH POPCHART XML
If your appearance file does not contain a text box, but you would like to add one, you can
add a text box by declaring a new Textbox item in PopChart XML. For example, if you
wanted to add a textbox containing the text This is a Textbox, you could do it with the
following tag:
<Textbox Name="title" Top="400" Left="10" Width="400"
Height="50"><Text>This is a Textbox</Text></Textbox>
Important:
7-34
Be sure to give your text box a distinct name (one that is not already being used).
www.corda.com
User Guide
.....
Imported Graphics
.I M. . P. .O. .R. T. .E. .D. .G. .R. .A. P. .H. .I C. .S. . . . . . . . . . . . . . . . . . . . . . . . .
Another new feature in PopChart Server 4.0 is the ability to import graphics into an
appearance file. This can be useful if you want to have an image as the background of your
graph, or if you want to use a logo in all of your PopChart images.
You can import graphics from the following formats: GIF and JPEG.
Note:
Warning:
JPEG images do not import well into PopChart XML 4.0. You will need to save your
appearance files in PopChart XML 4.0.1 format to take full advantages of imported JPEG
images. To do this, go into PopChart Builder, select Edit > Preferences > Save and
check the Save Using Latest PCXML Format box. You must be running both
PopChart Server 4.0.1 and PopChart Builder 4.0.1 for this to work.
If the image file that you import is extremely large, it can seriously decrease
PopChart Server’s performance.
ADDING IMPORTED GRAPHICS TO YOUR
APPEARANCE FILE
You can import a graphic into your appearance file using PopChart Builder. Simply click
on the Add an image icon and locate the image you want to import. You can resize it, set
its transparency, and add a border in the PopChart Builder interface.
Note:
Because PopChart Builder must encode your image, you cannot dynamically add an image
object to your appearance file. The best you can do is create a separate appearance file
containing just your image and then overlay it (refer to “Adding Objects to Your
Appearance File” on page 10-13). An alternative strategy is to import a placeholder image
into the appearance file. You could change its source dynamically, or you could hide it if you
end up not needing it.
CHANGING THE GRAPHIC SOURCE
You can change the source of an image using the bitmap.LoadFile() PCScript
command. This command accepts one parameter—the source of the new graphic. You can
load a graphic from a local file, or from a URL.
Important:
In order for PopChart Server to load any image, it must be given permission to read data
from the specified path or domain. See “Setting Path Permissions” on page 3-37 for more
information.
Assuming you have an graphic named bitmap, you could change its source to the
cordalogo.gif file from the examples/images directory using the following PCScript:
bitmap.loadFile(examples/images/cordalogo.gif)
7-35
.....
PopChart
7
6(5 9(5
Imported Graphics
Note:
You cannot change the source of an image using PCXML.
DRILL-DOWN FOR A TEXT BOX
You can also enable drill-down effects for an image. For information about drill-down
effects in general, see “Drill-down Effects” on page 7-14.
PCSCRIPT
To add a drill-down effect to an image, simply use the bitmap.DDEnable() method.
For example, to add a drill-down link from a text box named textbox to
http://mycompany.com, you would use the following PCScript command:
bitmap.DDEnable(http://mycompany.com)
POPCHART XML
To add a drill-down effect to an image with PopChart XML, simply add a Drilldown
attribute to your Image element, as shown in the example below.
<Image Name="bitmap" Drilldown="http://mycompany.com"
/>
HIDING A GRAPHIC
Another useful feature is the ability to hide a graphic. If your appearance file already
contains an imported graphic, but you don’t want to show it in certain instances, you can use
PCScript or PopChart XML to turn it off.
PCSCRIPT
To hide a graphic in PCScript, simply use the bitmap.Hide() method. For example, if
your image object is named bitmap, you can make it disappear with the PCScript
command shown below.
bitmap.Hide()
POPCHART XML
To hide a graphic in PopChart XML, simply override its Visible attribute to false. For
example, if your image object is named bitmap, you could hide it with the following
PopChart XML.
<Image Name="bitmap" Visible="false" />
7-36
www.corda.com
D ISPLAYING 508 C OMPLIANT D ESCRIPTIVE T EXT
T
.....
...................................
8
his chapter discusses PopChart Server’s ability to generate descriptive text for the
PopChart images that it generates. Descriptive text allows visually impaired readers to
“view” a PopChart image through a textual description of the data in the graph. This
functionality is compliant with Section 508 of the Rehabilitation Act.
This chapter is divided into the following sections:
• Corda Technologies and Descriptive Text
• Why Do I Need Descriptive Text?
• “Viewing” Descriptive Text
• Generating Descriptive Text
• Controlling How PopChart Server Describes a PopChart Image
• Customizing the Descriptive Text Template
8-1
.....
PopChart
8
6(5 9(5
D I S P L A Y I N G 5 0 8 C O M P L I A N T D E S C R I P T I V E TE X T
Corda Technologies and Descriptive Text
.Corda
. . . . . .Technologies
. . . . . . . . . . . . .A. .N. D. . .D. .E. S. .C. .R. I.P. .T. I.V. .E. .T. E. .X. .T. .
As the global leader in interactive data visualization, Corda Technologies recognizes the
importance of providing equal access to information for users who are visually impaired.
Corda Technologies is the first and only company to provide multiple charting and
graphing solutions that create accessible, 508 compliant charts and graphs with descriptive
text. The descriptive text is available for a screen reader device to audibly describe the chart
or graph so a visually impaired user can understand the graphical information. Corda
Technologies has included the descriptive text feature in all of the PopChart family of
charting and graphing solutions to facilitate inclusion of 508 compliant charts and graphs in
all Web content.
PopChart’s charts and graphs are interactive for all users, including the visually impaired.
Interactive graphs enable all users to drill down to more in-depth information. Sighted users
receive additional information by drilling down to another chart. Non-sighted users access
the same additional information by going from one chart with descriptive text to another
chart with descriptive text. As the data changes, the chart and the descriptive text
automatically change to match the new data. This fulfills the requirements of Section 508 of
the Rehabilitation Act.
8-2
www.corda.com
User Guide
.....
Why Do I Need Descriptive Text?
.W. .H. Y. . .D. .O. . I. .N. .E. E. .D. . D. .E. .S. C. .R. .I P. .T. I. V. .E. . T. .E. X. .T. ?. . . . . . .
There are an estimated 800,000 visually impaired persons currently using the Web. It is
projected that there are 6.5 million Americans age 55 or older that experience severe vision
loss; by 2030 this number will double.
On August 7, 1998, the President signed into law the Workforce Investment Act of 1998,
Public Law 105-220. Title IV of the Act is the Rehabilitation Act Amendments of 1998.
Subsection 408(b) amended section 508 of the Rehabilitation Act of 1973 (29 U.S.C. 794d).
Subsection 508(a)(1) requires that when Federal departments and agencies develop,
procure, maintain, or use Electronic and Information Technology (EIT), they shall ensure
that the EIT allows Federal employees with disabilities to have access to and use of
information and data that is comparable to the access to and use of information and data by
other Federal employees. Section 508 also requires that individuals with disabilities, who
are members of the public seeking information or services from a Federal department or
agency, have access to and use of information and data that is comparable to that provided
to the public without disabilities.
This law went into effect June 21, 2001. For additional information about this law, see the
Federal IT Accessibility Initiative at
http://www.section508.gov/index.cfm?FuseAction=Content&ID=75.
The implications of this law regarding graphics on the web are tremendous. Essentially, it
means that all your charts and graphs must be simultaneously offered in a text format that
can easily be interpreted by a screen-reader such as JAWS®, and IBM® Home Page
Reader. Corda Technologies provides the only charting and graphing solution that allows
you to quickly and easily generate such text.
Although this law applies only to federal organizations, many private organizations are also
realizing the need to provide a method for visually impaired users to access important data.
8-3
.....
PopChart
8
6(5 9(5
“Viewing” Descriptive Text
.“.V. I. E. .W. .I.N. .G. ”. . D. . E. .S. C. .R. .I .P. T. .I V. .E. . .T.E. .X. T. . . . . . . . . . . . . .
When you enable descriptive text, a link will appear either next to the bottom right corner of
your PopChart image, or below it. By default, this link is a blue underlined letter d. Clicking
on it will take the user to a web page containing a textual description of the chart.
As a screen reader reads over this link, it will indicate to the user that descriptive text is
available for the image. The user then has the option of having the screen reader read the
description of the PopChart image.
For an example of how people will view descriptive text, consider the following PopChart
image.
d
8-4
www.corda.com
User Guide
.....
“Viewing” Descriptive Text
You can tell that a descriptive link is enabled for this graph because of the link that appears
at the bottom right corner. Clicking on the d will take you to a page (which resides on
PopChart Server) that looks much like the one in the next image.
Descriptive Text Example
Example 8.1
)RRG6DOHV
Text boxes
are listed at
the end.
Title of PopChart
image.
Each drill-down item will appear
with the link right next to it, so
users will still be able to drill-down.
%DUFKDUWZLWKJURXSVZLWKLWHPVSHUJURXS
*URXS6DOHV
,WHP3URGXFH'HWDLOIRU6DOHV3URGXFH
,WHP*UDLQV&HUHDOV'HWDLOIRU6DOHV*UDLQV&HUHDOV
,WHP'DLU\0LONLV*RRG'HWDLOIRU6DOHV'DLU\
*URXS6DOHV
,WHP3URGXFH'HWDLOIRU6DOHV3URGXFH
,WHP*UDLQV&HUHDOV'HWDLOIRU6DOHV*UDLQV&HUHDOV
,WHP'DLU\0LONLV*RRG'HWDLOIRU6DOHV'DLU\
:H)HHG7KH:RUOG
EDFN
Users can go back to the page they came from
after they are done reading the descriptive text.
Descriptive Text will
indicate which items
had PopUp Text.
This data is fully interactive. What would appear as PopUp text in a graphical PopChart
image appears as text right beside the description for each item. Likewise, drill-down links
appear next to each item that is enabled for drill-down effects. Visually impaired users are
able to drill-down from this descriptive text to another PopChart image with D-link
descriptive text. Thus, navigation through large amounts of data is simple, fast and
convenient.
Note:
At this point in time, drill-down to custom JavaScript functions or named destinations
within the original web page is not supported in PopChart Server’s descriptive text output.
You may be able to circumvent the JavaScript limitation, however, by customizing the
descriptive text template so that it includes a predefined JavaScript library of the functions
you need to access.
8-5
.....
PopChart
8
6(5 9(5
Generating Descriptive Text
.G. E. .N. .E. R. .A. .T. I.N. .G. . D. .E. .S. C. .R. .I P. .T. .I V. .E. . T. .E. X. .T. . . . . . . . . . .
Generating descriptive text is simple, especially when you use the PopChart Embedder.
The PopChart Embedder will automatically insert the d link, complete with the reference
to the descriptive text on PopChart Server, into the embedding HTML.
G E N E R A T E D E S C R I P T I V E T E X T W I T H PopChart
Embedder
To instruct PopChart Server to return a link to descriptive text along with the PopChart
image that it embeds, simply set the returnDescriptiveLink attribute to true, as
illustrated below.
myPopChart.returnDescriptiveLink = true;
Some users may also want to customize the language of their descriptive text. To do this, set
the PopChart Embedder language attribute to the two-character encoding for your
language. For example, to set the language to English, use the following command.
myPopChart.language = "EN";
Of course, since English is the default language, this line of code is unnecessary.
Note:
Make sure that the descriptive text settings for your language are defined in the descriptive
text template. By default, the template only contains settings for English. You will have to
add settings for other languages (see “Adding Support for Additional Languages” on
page 8-7 of the PopChart Server Reference manual).
BUILDING AN HTTP REQUEST FOR DESCRIPTIVE
TEXT
If you are requesting your images directly through HTTP requests to PopChart Server,
you will have to build your descriptive link manually.
Note:
For more information about requesting PopChart images directly through HTTP requests,
refer to Chapter 11, “Getting PopChart Images with HTTP Requests.”
To do this, first of all append the @_TEXTDESCRIPTION command to your server
command string. This command requires that a two character language code follow it. If
you are showing your text description in English, this code is EN. Thus, you would add
@_TEXTDESCRIPTIONEN to your server command string.
For example, suppose that the server command string to request your PopChart image is
8-6
www.corda.com
User Guide
.....
Generating Descriptive Text
@_FILEapfiles/bar.pcxml@_LOADPCXMLpcxml/data1.pcxml
Your server command string to request a text description would be:
@_FILEapfiles/bar.pcxml@_LOADPCXMLpcxml/data1.pcxml
@_TEXTDESCRIPTIONEN
Then, after the object, embed, or image tag that you use to embed your PopChart
image, insert a hyperlink tag whose source is the HTTP request that results from your server
command string.
For example, using the server command string shown above, we would embed a GIF image
and a descriptive text link with the HTML in Example 8.2.
Example 8.2
HTML for Descriptive Text Link
<img src="@_FILEapfiles/bar.pcxml@_LOADPCXMLpcxml/data1.pcxml@_GIF
">
<a href="@_FILEapfiles/bar.pcxml@_LOADPCXMLpcxml/data1.pcxml@_TEXT
DESCRIPTIONEN"><font color="blue">d</font></a>
8-7
.....
PopChart
8
6(5 9(5
Controlling How PopChart Server Describes a PopChart Image
C O N T R O L L I N G H O W PopChart Server
DESCRIBES A POPCHART IMAGE
..................................................
Besides data, there are three aspects of descriptive text that you can dynamically control—
the title, an object’s manual description paragraph, and whether or not certain features (like
drill-down and PopUp) or objects are translated into descriptive text. If you are more
adventurous, you can also customize PopChart Server’s descriptive text template. This is
discussed in the next section.
SETTING THE TITLE OF YOUR DESCRIPTIVE
TEXT
When PopChart Server generates descriptive text, it looks for a text box named title.
The contents of this textbox will be used for the title that appears at the top of the descriptive
text page. If you add a title box using the PopChart Wizard, this box will be set
automatically. Otherwise, you will need to change the object name of the text box that
contains the title of your PopChart image.
Instructions on setting the title box can be found in “Title Text Box” on page 1-19 of the
PopChart Builder User Guide.
Of course, you can change the contents of your title box in PCScript at any time using the
title.SetText() method. For example, to set the title to Interesting Data, you would
use the following command.
title.setText(Interesting Data)
If you cannot, or do not wish to set a title box, or if you wish to override the title box, you
can also use the Main.Title() PCScript command. For example, to set the title for your
descriptive text to Descriptive Text for Interesting Data, you would use the following
command.
Main.title(Descriptive Text for Interesting Data)
MANUALLY ADDING A DESCRIPTION
PARAGRAPH TO AN OBJECT
Sometimes, you may want to offer your visually impaired viewers additional information
about an object. In such circumstances, you can manually add descriptive text using the
main.Description(), graph.Description(), and
textbox.Description() PCScript commands. These commands add a paragraph of
text immediately above the automatically generated description for your PopChart, graph,
or text box, respectively.
8-8
www.corda.com
User Guide
.....
Controlling How PopChart Server Describes a PopChart Image
For example, suppose you wanted to add the following text above the automatically
generated description for your graph object: This bar graph compares sales statistics
for the period between May 12th and June 30th. You could add this text with the
following command.
graph.Description(This bar graph compares sales
statistics for the period between May 12th and June
30th)
SUPPRESSING OBJECTS ARE SPECIAL EFFECTS
You can suppress all automatically generated text description for any graph or text box by
using the graph.SuppressAutoDescription() and
textbox.SuppressAutoDescription() commands respectively. You can also
suppress automatically generated descriptive text for the entire PopChart with the
Main.SuppressAutoDescription() command.
Note:
When you suppress automatically generated text description for an object, text entered via
the object’s Description() method will still be shown.
By default, PopChart Server will generate descriptive text for PopUp text and drill-down
effects. If you need to suppress the description for these items, you can use
graph.SuppressDescriptionItem() and
textbox.SuppressDescriptionItem().
For example, if you wanted to suppress descriptive text for all drill-down effects in a graph,
you could use the following PCScript command.
graph.SuppressDescriptionItem(_Drilldown_)
You can pass as a parameter to this function any of the following values: _Drilldown_,
_Popup_, _CatDrilldown_, _SeriesDrilldown_. Choosing _CatDrilldown_
will suppress descriptive text for drill-down effects on category labels. Choosing
_Drilldown_ will suppress descriptive text for all drill-down effects. Choosing
_PopUp_ will suppress descriptive text for PopUp text. Choosing
_SeriesDrillDown_ will suppress descriptive text for drill-down effects on series
labels.
8-9
.....
PopChart
8
6(5 9(5
Customizing the Descriptive Text Template
CUSTOMIZING THE DESCRIPTIVE TEXT
TEMPLATE
..................................................
PopChart Server uses a descriptive text template to control how it describes various
graphs and data items. This file, dlink.xml, is located in the config directory of your
PopChart root directory.
When you modify this template, you can change settings for the default language, or you
can add settings for other languages. For more information about editing this template, refer
to Chapter 8, “Descriptive Text Settings,” of the PopChart Server Reference manual.
8-10
www.corda.com
P OP C HART F ONTS
T
.....
...................................
9
his chapter will discuss PopChart fonts and the PopChart Font Converter. It is divided
into the following sections:
• “About PopChart Fonts”
• “Importing Custom Fonts”
9-1
.....
PopChart
9
6(5 9(5
POPCHART FONTS
About PopChart Fonts
.A. B. .O. .U. .T. .P. O. . P. .C. .H. A. .R. .T. .F. O. . N. .T. S. . . . . . . . . . . . . . . . . . . .
PopChart Server uses a special font format that allows it to generate images in different
languages and formats. These fonts reside in the lib/fsfiles folder of your PopChart
installation. They have an extension of either .fsf or .fsd.
One great feature new to PopChart Server 4.0 is full support for double-byte characters.
This means, for example, that you can use Asian fonts natively with PopChart Server.
Because of the wide variety of fonts available, PopChart Server comes installed with only
a small number of commonly used fonts.
However, if you have a font you would like to use with PopChart Server, you may be able
to convert that font to the PopChart Font format. This process is explained in the next
section, “Importing Custom Fonts.”
Note:
9-2
The Times, Helvetica, and Courier font sets may support some international characters, but
there are no guarantees. PopChart Server supports a much broader range of international
characters when using the pre-installed Lucida font set, but there is no Asian or double-byte
character support in this font set. If you need full double-byte character support, you should
import custom fonts.
www.corda.com
User Guide
.....
POPCHART FONTS
.I M. . P. .O. .R. T. .I.N. G. . . C. .U. .S. T. .O. M. . . F. .O. N. . T. .S. . . . . . . . . . . . . . . . .
You can import fonts into PopChart Server using the PopChart Font Converter. This
small utility is installed in any PopChart installation. If you have chosen to install shortcuts,
you should see one for the PopChart Font Converter, otherwise, you can start this utility
by running the bin/FontConverter program.
Note:
The PopChart Font Converter is base on the TrueType to SVG font converter developed by
Steady State Software Limited (http://www.steadystate.com/). The source code for the
font converter is available and released under the GNU Lesser General Public License (see
docs/other/gnulicense.html). To obtain source code, contact Corda Technologies at
support number listed at the front of this manual.
PopChart Font Converter can convert fonts that meet these requirements:
1
The font must be a Windows True Type font.
2
The font must have one of the following character mappings:
• Unicode
• Shift JIS (MS932) (for Japanese)
• Big5 (MS950) (for Traditional Chinese)
• GBK (aka PRC) (MS936) (for Simplified Chinese)
• Wansung (MS949) (for Korean)
3
The font must not create characters by combining multiple glyphs from the font. (The
conversion will complete successfully, but the characters will not display correctly).
Because of the True-Type Font requirement, you will most likely need to run this program
on a Microsoft Windows system (since they use True-Type Fonts). If you need to import
the fonts on another platform, skip to “Installing Custom Fonts on Non-Windows
Platforms” below. Otherwise, continue to the next section.
CONVERTING TRUE TYPE FONTS WITH THE
PopChart Font Converter
Converting fonts is a pretty straightforward process. You can convert any True-Type Font
files that you have access to from the system containing your PopChart installation by
following these steps.
9-3
.....
PopChart
9
6(5 9(5
POPCHART FONTS
T o c o nv e r t a f on t i n t he PopChart Font Converter
1
Start PopChart Font Converter.
If you selected to install the shortcuts when you installed PopChart Server, you will
have a shortcut for the PopChart Font Converter. Otherwise, you can run the
PopChart Font Converter by starting the bin/FontConverter program.
2
In the Fonts box, enter in the path to the True Type Font you want to convert, or click
on the Browse button to the right of the box to locate the folder.
If you are converting a system font—that is, you can use it in programs like Microsoft
Word—they will be located in your %SYSTEM%\Fonts folder, where %SYSTEM%
is the directory where Microsoft Windows is installed (e.g. C:\Winnt or C:\Windows).
If this is your first time running the PopChart Font Converter, the location you see in
the Font Folder box should be that of your system fonts. Otherwise, it will be the
location of the last font you converted.
Once a valid folder is selected, the font names should appear in the list box.
3
If necessary, enter into the Output Folder the location where you want to save the
converted fonts.
You shouldn’t have to change the output folder. All converted fonts should be saved in
the lib/fsfiles folder of your PopChart installations, and it should be set to this by
default.
4
Select the font you want to convert from the Fonts box.
The Preview box allows you to see what the font looks like.
5
Under Conversion Options, check the boxes of the font styles (i.e. Plain, Bold, Italic,
and Bold Italic) that you want to convert.
Many True-Type Fonts (but not all) contain information about several different styles of
the font. Most of the time, these styles are plain, italic, bold, and bold italic.
However, each style of a PopChart font is stored in a separate file, so you are given the
option of specifying which styles should be converted. By default, the PopChart Font
Converter assumes you want to convert all of the styles, but if this is not the case, you
should uncheck any styles that you don’t want to convert.
6
Choose a name for the converted font by typing it into the Display Name box.
By default, the converted font will have the exact same name as the True-Type Font.
However, you can change this name to whatever you want it to be. PopChart Server
will only know the font by the name that you give it.
7
Click on the Convert button.
After you click on this button, PopChart Font Converter will begin converting the
font. The Status box will indicate the progress of the conversion process. When it says
Conversion Process Completed successfully, the conversion process is done.
9-4
www.corda.com
User Guide
.....
POPCHART FONTS
If the Status box reads Conversion Process Failed, PopChart Font Converter was
for some reason unable to convert the specified font. You should try a different font.
Unless you specified otherwise, the converted font files will be located in the lib/fsfiles
folder. The files will have a .fsd extension. Their names will be eight characters long,
and will be some combination of the font style and the name you gave your font in step
6.
8
If you want to convert more fonts, return to step 2. Otherwise, exit the PopChart Font
Converter by clicking the Exit button.
9
The new font will be available for use in any PopChart applications on the local
computer upon restarting that application.
INSTALLING CUSTOM FONTS ON NON-WINDOWS
PLATFORMS
Unless the True-Type Fonts you want to convert are already located on your non-Windows
machine you will need to do to one of the following:
• Copy or download the fonts that you want to convert from a machine running Microsoft
Windows to the machine running PopChart Server and then follow the procedure
outlined above in “Converting True Type Fonts with the PopChart Font Converter.”
• Install the PopChart Font Converter on the Microsoft Windows system that has the
True-Type Fonts you want to convert, convert the fonts following the procedure outlined
above in “Converting True Type Fonts with the PopChart Font Converter,” then
follow the procedure outlined below in “Installing Fonts that Have Already Been
Converted.”
INSTALLING FONTS THAT HAVE ALREADY BEEN
CONVERTED
If you have fonts that have already been converted to the PopChart Font format, you can
install these fonts by going to the Files > Upload Font Files screen in the
Administration Console. Alternatively, you can follow this procedure:
T o in s t al l p re - c on v e rt e d f on t s
1
Locate the pre-converted fonts.
These fonts are contained in files with a .fsd extension. If you are importing fonts that
you converted on a different PopChart installation, you will find them in the lib/fsfiles
folder of that installation.
9-5
.....
PopChart
9
6(5 9(5
POPCHART FONTS
2
Copy these fonts to the lib/fsfiles folder of your current PopChart installation.
3
Restart any PopChart programs that you are running.
Upon restart, the fonts will be available for use.
9-6
www.corda.com
User Guide
.....
POPCHART FONTS
Using Custom Fonts
.U. S. .I.N. G. . .C. .U. S. .T. .O. M. . . F. .O. N. .T. .S. . . . . . . . . . . . . . . . . . . . . . .
Once you have imported a custom font using the steps outlined in “Importing Custom
Fonts” on page 9-3, you can then use that custom font in any of your appearance files.
Simply start PopChart Builder, open the Font Properties dialog for any text item, and
select the font that you imported from the Font list.
Note:
Unless PopChart Server is running on the same machine that you ran the Font Converter
on, you will need to upload your custom font to PopChart Server before it can use an
appearance file containing this font. To do this, follow the steps outlined in “Installing
Fonts that Have Already Been Converted” on page 9-5.
9-7
.....
PopChart
9
9-8
6(5 9(5
POPCHART FONTS
Using Custom Fonts
www.corda.com
U SING P OP C HART XML
T
.....
...................................
10
his chapter discusses the use of PopChart XML. PopChart XML (PCXML) is a new
XML (eXtended Markup Language) format that allows you to control all aspects of a
PopChart, including its appearance and data.
If you’ve been reading this manual thoroughly, you’ve probably caught on to many aspects
of PopChart XML. In Chapter 6 we discussed how you could use it to send dynamic data
to PopChart Server. In Chapter 7 we showed how you could use it to add special effects
to your graph.
This chapter simply conceptualizes a lot of things that you’ve already been doing
throughout this documentation. It will discuss some of the key concepts of PopChart XML.
It first of all offers you a basic Introduction to the PCXML Format. Then it introduces and
discusses three main ways that you can use PopChart XML. These uses are as follows:
• Appearance Files
• Data
• PCXML Transformations
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” on page 1-7 of the PopChart
Server Reference manual for a brief overview of XML.
10-1
.....
PopChart
10
6(5 9(5
USING POPCHART XML
PopChart and XML
.P. O. .P. .C. H. .A. .R. T. . .A. N. . D. . .X. M. . L. . . . . . . . . . . . . . . . . . . . . . . . . .
Saying that your product supports XML can be a very ambiguous statement. There are
hundreds of thousands of XML document types, each with a different purpose. Thus, it is
important to know what exactly “XML support” means.
PopChart Server supports XML in two ways:
PopChart XML (PCXML) is an XML document type
capable of describing every aspect of a PopChart, including its appearance and data.
All of your appearance files are saved in PopChart XML. You can also send
PopChart XML to PopChart Server when you request a PopChart image. This
allows you to dynamically change the appearance of your graph, as well as set its
data.
POPCHART XML
Most
databases are capable of exporting data in a standard XML data format. PopChart
Server can import XML data in this format. This format is entirely different from
PopChart XML. For information on importing XML data into a PopChart, refer to
“Importing Data from Data Files” on page 6-16.
IMPORTING XML DATA GENERATED BY A DATABASE
10-2
www.corda.com
User Guide
.....
USING POPCHART XML
.I N. . T. .R. O. . D. .U. .C. T. .I .O. N. . .T. O. . .T. H. . E. . .P. C. .X. .M. L. . .F. O. .R. .M. .A. T. . .
The current version of PCXML document type is 4.0.5 (to maintain consistency with
PopChart Server).
RESOURCES
Besides this chapter, you may also wish to examine Chapter 7, “PopChart XML,” in the
PopChart Server Reference manual. Currently, this chapter has a complete list of all
PCXML elements and attributes. In the future, it may contain descriptions of these elements
and attributes, as well.
Probably your best resource for PopChart XML is PopChart Builder. PopChart Builder is
a graphical user interface for creating appearance files. Since it saves appearance files in the
PCXML format, you can learn a lot about how things are done in PCXML by creating
appearance files with PopChart Builder and viewing the PCXML it creates.PopChart
Builder can also validate your PopChart XML documents. Simply open your PopChart
XML document in PopChart Builder, and PopChart Builder will tell you if there are any
errors in the document.
Note:
Not everything you can do with an appearance file will be apparent through PopChart
Builder—for interactive features, you will have to view the file with PopChart Server to see
the effect.
We are currently in the process of completing it’s formal document type definition (DTD).
Pay attention to the Corda Technologies website over the next few months for more
information.
COMPATIBILITY BETWEEN VERSIONS
Many elements and attributes have been added or renamed since the 4.0 version of PCXML.
To maintain backwards compatibility, PopChart Builder saves appearance files in the
PCXML 4.0 format by default. Unless you change this behavior, you will be unable to take
advantage of many of the latest PCXML features.
You can change the PCXML format that PopChart Builder uses to save its appearance files
by selecting Edit > Preferences > Save and checking the Save Using Latest
PCXML Format box. However, be aware that you cannot use appearance files saved in
the latest PCXML format with previous versions of PopChart Server. The current version
of PopChart Server supports previous versions of PCXML.
If you are manually creating your PCXML documents, be sure to specify the version of
PCXML you are using by setting the Version attribute of the Chart tag. This ensures
that PopChart Server will properly parse your PCXML.
10-3
.....
PopChart
10
6(5 9(5
USING POPCHART XML
MAIN ELEMENTS
The top level element in a PCXML document is <Chart>. One important attribute of
<Chart> is Version. Be sure to include this attribute so that if future versions of
PCXML differ significantly from the current version, PopChart Server will know how to
act when it sees your file. The current version is 4.0.5.
The main subelements of <Chart> are <Graph>, <GraphData>, <Textbox>,
<Legend>, and <Image>. All of these subelements contain a Name attribute, which is
essential, since this element helps PopChart Server identify what element it should apply
dynamic data or formatting options to. Other important universal attributes include Top,
Left, Anchor, Height, and Width, which control the size and position of the element,
and Visible, which hides or shows the element (these attributes are not in <GraphData>).
The <Graph> element represents a graph. A graph’s type is specified by its Type and
Subtype attributes. There are many attributes and subelements for <Graph>, and they
cannot all be listed in this section. You’ll probably want to experiment with the element in
PopChart Builder to learn more.
The same applies for <Textbox>, <Legend>, and <Image> (the objects that these
elements represent should be fairly obvious).
The <GraphData> element is used to store data. It will be associated with the <Graph>
element of the same name. In other words, <GraphData Name="graph"> is associated with
<Graph Name="graph">.
Because appearance files in PopChart Builder contain sample data, the <GraphData>
will also appear in appearance files. However, it is not necessary. Its main function is to
store dynamic data that will be sent to PopChart Server. For more information about the
<GraphData> tag, refer to “Sending Data with PopChart XML” on page 6-5.
EXAMPLE DOCUMENT
Example 10.1 shows a typical PopChart XML file.
Example 10.1
Typical PopChart XML Document
<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>
<Chart Version=’4.0’ BGColor=’#4a6b80’>
<Graph Name=’graph’ Top=’37’ Left=’32’ Width=’475’
Height=’235’ Type=’Line’ SubType=’Basic’>
10-4
www.corda.com
User Guide
.....
USING POPCHART XML
<GridColors BackColorTransparent=’False’
BottomColorTransparent=’False’ BottomColor=’#85a9df’
SideColorTransparent=’False’ SideColor=’#85aadf’/>
<ColorPalette Color1=’#9f2727’ Color2=’#4249a9’
Color3=’#757a75’ Color4=’#00750e’ Color5=’#b750fc’
Color6=’#ccda52’ Color7=’#e06557’ Color8=’#57df64’
Color9=’#53d1e1’ Color10=’#d8a455’ Color11=’#cdb4ca’
Color12=’#996433’ Color13=’#0fa187’ Color14=’#dbeabc’
Color15=’#8b7caa’ Color16=’#85b705’/>
<ValueScale Position=’Left’ Font=’Color:White;’
MinorFont=’Size:10;’/>
<CategoryScale Font=’Name:Lucida Bright; Style:Bold;
Color:White;’/>
<Legend Name=’legend_graph’ Top=’280’ Left=’90’
Width=’363’ Height=’45’>
<Properties UseTransparentFill=’No’/>
</Legend>
</Graph>
<GraphData Name=’graph’ Method=’Replace’>
<Categories>
<Category Name=’Group 1’/>
</Categories>
<Series Name=’Item 1’>
</Series>
</Series>
10-5
.....
PopChart
10
6(5 9(5
USING POPCHART XML
</Series>
</GraphData>
<Textbox Name=’textbox’ Top=’7’ Left=’92’>
<Text>Sample Text</Text>
</Textbox>
</Chart>
Note:
10-6
It is necessary to place the <?xml version=’1.0’ encoding=’ISO-8859-1’
?> tag at the top of your PopChart appearance files. This identifies the document as being
in XML For other PopChart XML documents, this tag is not required. However, we strongly
recommend using it in all XML documents.
www.corda.com
User Guide
.....
USING POPCHART XML
Appearance Files
.A. P. .P. .E.A. .R. A. . N. .C. .E. .F. .I L. .E. S. . . . . . . . . . . . . . . . . . . . . . . . . . .
The primary function of PopChart XML is to tell PopChart Server what a PopChart image
should look like—in other words, how PopChart Server should translate data into a
PopChart image.
You can create an appearance file either using PopChart Builder, or by building the
PopChart XML yourself. Although the former method is highly recommended, you can
create appearance files on the fly when you build them yourself.
You will probably have PopChart Server load your appearance file in one of three ways:
• As a file in PopChart Server’s document root directory.
• As a file on a web server.
• As a dynamically generated file generated by a web application server.
Important:
You should tell PopChart Server where to find the appearance file by setting either the
appearanceFile PopChart Embedder attribute, or the @_FILE server command. For
example, if you wanted to set the appearance file to examples/apfiles/pareto.pcxml, you
would use the following line of code with the PopChart Embedder:
"examples/apfiles/pareto.pcxml";
Note:
This example, as well as all examples in this chapter, assume our PopChart Embedder
object is named myPopChart.
Or, you would add the following to the server command string:
@_FILEexamples/apfiles/pareto.pcxml
As another example, suppose you are generating your appearance file dynamically by
means of a web application at http://webapp.mycompany.com/apfiles?graph=bar1.
Assuming your security permissions have been properly set, you could have PopChart
Server load this appearance file with this PopChart Embedder command:
"examples/apfiles/pareto.pcxml";
By declaring this file as the appearance file, you are telling PopChart Server to use the
PopChart XML from that file as the basis for the PopChart image it generates. Any other
piece of PopChart XML that you send to PopChart Server by other means will be applied
to or will override the appearance file.
10-7
.....
PopChart
10
6(5 9(5
USING POPCHART XML
Data
.D. A. .T. .A. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
After you have sent the appearance file to PopChart Server, you will usually want to
override its data. You can do this by sending a segment of PopChart XML to PopChart
Server that contains nothing but a Chart element with GraphData element(s).
The format of PopChart XML data (as well as much of the information in this section) is
available “Sending Data with PopChart XML” on page 6-5.
You will need to generate this PopChart XML yourself. Most people will generate their
PopChart XML data in one of four ways:
• Build a server application that creates a PopChart XML data file at regular intervals (i.e.
every 5 minutes or every day—however frequently you need to update your data to keep
it up to date). This file can be saved to PopChart Server’s document root, or can be
stored on a web server.
• Build a web application that, when it receives a request, queries a data source, retrieves
the data, and formats it as PopChart XML. It then returns this data to the requesting
client (which will be PopChart Server).
• Integrate the afore-mentioned process into the web application that generates your
appearance file. You simply include a <GraphData> element with all of your data in
the initial appearance file that you send PopChart Server. If you are doing this, ignore
the following instructions on loading your PopChart XML data (but please read “Using
Data Specific Special Effects”).
• Integrate the afore-mentioned process into the web application that is building their
current web page. The web application streams the data directly to PopChart Server.
You can only do this with the Java, JavaBean, and COM versions of the PopChart
Embedder.
Important:
In the first two scenarios, you will need to tell PopChart Server the source of the PopChart
XML data that it should load into the graph using either the loadPCXML(String)
PopChart Embedder method, or the @_LOADPCXML server command. For example, to
load data from http://database.mycompany.com/sales?Month=May, you would use the
following line of code in the PopChart Embedder.
myPopChart.loadPCXML("http://database.mycompany.com/sa
les?Month=May");
Or, you would add the following command to your server command string:
@_LOADPCXMLhttp://database.mycompany.com/sales?Month=May
10-8
www.corda.com
User Guide
.....
USING POPCHART XML
Data
If you want to test this out, there is a directory containing sample PopChart XML data at
chart_root/examples/pcxml. There are several files containing data suitable for the bar
graph that we have been building throughout this documentation. One of those is
p_medals.xml. By adding this line to the code form Example 4.7, you could have
PopChart Server load the data from this file the example PopChart image.
myPopChart.loadPCXML("examples/pcxml/p_medals.xml");
Medal Count
In the last scenario, you would use PopChart Server’s addPCXML(String). This
accepts a string containing PopChart XML. The following statement streams a small
segment of PopChart XML data to PopChart Server.
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
10-9
.....
PopChart
10
6(5 9(5
USING POPCHART XML
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:
Both of these methods will override any data in your appearance file. If you instead wish to
append data to the appearance file (or to any data that has already been loaded using
loadPCXML(String), you should place a Method="Append" attribute in your
GraphData tag.
USING DATA SPECIFIC SPECIAL EFFECTS
If you intend to use data-specific special effects, like drill-down or PopUp text on key data
items, you will probably want to combine the process of generating these effects with the
process of translating your data to PopChart XML. For example, if you have a PopUp text
box that needs to be displayed for the highest and lowest data values retrieved, the only way
to do this without using PCScript is to include a PopUp attribute in the actual Data elements
for highest and lowest data values (see “PopUp Text” on page 7-12).
10-10
www.corda.com
User Guide
.....
USING POPCHART XML
PCXML Transformations
.P. C. .X. .M. L. . .T. R. .A. .N. S. .F. O. . R. .M. .A. .T.I.O. .N. S. . . . . . . . . . . . . . . . . .
After you’ve loaded your appearance file and data, you may want to make additional
modifications to your PopChart image. For example, these modifications could include
adding or hiding a new text box, changing the colors or symbols for a certain data series, or
adding a logo to the PopChart image. We refer to the strategy of making on-the-fly
appearance file modifications as PCXML Transformations.
You will probably want to generate these PCXML transformations in much the same
manner as you generate your dynamic data. You even send these transformations using the
exact same commands (loadPCXML(String), addPCXML(String), and
@_LOADPCXML).
CUSTOMIZING OBJECTS FROM YOUR
APPEARANCE FILES
One type of PCXML transformation is to customize or override settings for objects already
in your appearance file. You can do this by creating a PCXML element that is named
exactly the same as the object you wish to customize. Then, you can specify the attributes or
subelements that you wish to modify or override. You can even add subelements and
attributes.
For example, suppose that you have set your appearance file to
examples/apfiles/bar.pcxml and that you want to dynamically change the type of your
graph to Line. You could do this by sending another Graph element named graph to
PopChart Server, containing only a Type attribute, which is set to Line.
<Graph Name="graph" Type="Line"></Graph>
Note:
When changing graph types, be sure to change to a graph type that is in the same data class
(see Chapter 12, “Data Organization,” in the PopChart Server Reference manual).
Another common transformation is to change the formatting for a data series. To do this,
you simply override the SeriesDefinition tag for the data series we want to modify.
For example, having changed the graph in the examples/apfiles/bar.pcxml file to a Line
graph, suppose you also want to add symbols to and change the color of the second data
series. You could do this by changing the Color and SymbolType attributes of its
SeriesDefinition tag.
Example 10.2 shows the resulting PCXML.
Example 10.2
PCXML Template to Change a Graph Type, Color, and Symbol
<Chart>
<Graph Name=’graph’ Type=’Line’>
10-11
.....
PopChart
10
6(5 9(5
USING POPCHART XML
<SeriesDefinition Number=’2’ Color=’#FF0000’
SymbolType=’Square’/>
</Graph>
</Chart>
This PCXML template is saved as examples/pcxml/linetransform.pcxml. You could have
PopChart Server load this transformation with the loadPCXML(String) PopChart
Embedder method, as shown below.
myPopChart.loadPCXML("examples/pcxml/linetransform.pcx
ml");
If applied to the example code from Example 4.7, this command would render the
following image:
Sample Text
10-12
www.corda.com
User Guide
.....
USING POPCHART XML
ADDING OBJECTS TO YOUR APPEARANCE FILE
Another type of PCXML transformation is to add a new object to your appearance file.
Note:
When adding objects to your appearance file, be sure to give them distinct names (names
that are not already being used).
For example, suppose that you have a logo that always we want to include at the top left
corner of your appearance files. You’ve saved the PCXML for this logo to
examples/images/companylogo.pcxml in your PopChart Server document root. To
have PopChart Server add this logo to any PopChart image you create, simply add the
following line to your PopChart Embedder code:
myPopChart.loadPCXML("examples/images/logo.pcxml");
Note:
The logo.pcxml file actually exists, so you can copy this line into your example code and
have the logo appear.
Sample Text
10-13
.....
PopChart
10
6(5 9(5
USING POPCHART XML
As another example, suppose you want to add a timestamp to all the PopChart images you
display. If you’ve put the timestamp into a String called timestamp, you could create a
new textbox with the timestamp with the following PopChart Embedder command:
myPopChart.addPCXML("<Chart><Textbox Name=’timestamp’
Top=’20’ Left=’420’ Height=’40’
Width=’100’><Text>"+timestamp+"</Text></Textbox>");
Note:
You can also dynamically add new graphs—in effect it is possible to create your appearance
file entirely on the fly. As you do this, though, remember to send the data for a graph AFTER
you have created it. In other words, you need to swap the order of your PCXML
transformations and your loading of PCXML data. Fake data will be inserted into any
graph for which PopChart Server does not have a <GraphData> element.
For more ideas on PCXML transformations for your graphs, read Chapter 7, “Interactive
and Special Effects.”
10-14
www.corda.com
G ETTING P OP C HART I MAGES WITH HTTP R EQUESTS
T
.....
...................................
11
his chapter discusses how to request PopChart images directly from PopChart Server
using HTTP requests, and also how to embed those requests in HTML tags.
The strategies discussed in this chapter represent an alternative to the PopChart
Embedder approach of communicating with PopChart Server. Prior to the 4.0 release,
the HTTP request strategy, often referred to as the Image-URL method, received
considerably more attention. Now, however, we are encouraging PopChart users to move
to the PopChart Embedder.
This chapter is divided into the following sections:
• “HTTP Request Method Overview”
• “Request Format”
• “Server Commands”
• “URL Encoding”
• “Embedding a FLASH PopChart Image”
• “Embedding an SVG PopChart Image”
• “Best Image Fallback”
• “Overcoming the URL Length Restriction”
11-1
.....
PopChart
11
6(5 9(5
GETTING POPCHART IMAGES WITH HTTP REQUESTS
HTTP Request Method Overview
.H. T. .T. P. . .R. E. .Q. .U. E. .S. .T. .M. .E. .T.H. .O. D. . .O. .V. E. .R. .V. I. E. .W. . . . . . . .
You can request images from PopChart Server directly using HTTP requests. For
example, if you’re currently sitting at a computer that’s running PopChart Server, you can
request one of the example PopChart images by entering the following URL into the address
line of your browser:
http://localhost:2001/?@_FILEexamples/apfiles/bar.pcxml
By making this URL the source of an <img>, <object>, or <embed> tag (depending on
the format of the image you want to display), you can easily embed the image into any web
page. For this reason, using HTTP requests to communicate with PopChart Server is often
referred to as the Image-URL method.
For any HTTP request to PopChart Server, there are two important parts: the address of
the server (in this case http://localhost:2001) and the query string (which begins with
@_FILE). The query string contains a list of server commands, such as @_FILE, which
instruct PopChart Server on how to format the image it returns.
On the surface, this method of communicating with PopChart Server may appear simpler
than the PopChart Embedder. However, when you start trying to use some of the more
advanced features of PopChart Server, such as Best-Image Fallback and descriptive text,
using this method can result in some very complicated and confusing HTML. Additionally,
some functionality, such as integrated database-querying, HTML tables, and image maps, is
only available using the PopChart Embedder.
We highly recommend that you use the PopChart Embedder method of communicating
with PopChart Server. However, we also support using HTTP requests. In fact, there may
be certain situations where HTTP requests are more appropriate than the PopChart
Embedder.
There are two distinct strategies for embedding a PopChart image in a web page when
requesting images via the HTTP request method:
CLIENT-SIDE SERVER COMMANDS
You can place all of the server commands necessary to generate your PopChart image
directly in your web page. When a client views this web page and requests the appropriate
image from PopChart Server, PopChart Server will find all of the information it needs
to generate the image directly in the HTTP request.
11-2
www.corda.com
User Guide
.....
Example 12 illustrates a typical process flow when using this strategy.
HTTP Request Process Flow
Example 12
1
The Web Application Server retrieves data from the database.
2
The Web Application Server builds an HTML page that will embed the PopChart image.
All of the data and commands needed to create the graph are will be included in the
HTML page within either the image tag or JavaScript code.
3
4
PopChart Server. All of the data and commands are embedded in the image source
URL.
5
PopChart Server uses the commands and data from the HTTP request to create a graph
image and sends it back to the browser.
6
SERVER-SIDE SERVER COMMANDS
Rather than have the client send all of the server commands directly to PopChart Server, it
is often more convenient to have the client send PopChart Server a server-side location
where it can find the necessary server commands. You can store the server commands
directly on PopChart Server (Server-Side Command File) or have PopChart Server
request the commands from another application server (App Server Call Back).
11-3
.....
PopChart
11
6(5 9(5
Note:
Server-side command files and app server call back can also be used with PopChart
Embedder, but this is not often the case.
Example 13 illustrates a typical process flow when using this strategy with App Server
Call Back:
App Server Call Back Process Flow
Example 13
1
The Web Application Server builds an HTML page that will embed the PopChart image.
Within the embedding image tag there will be a server command that informs PopChart
Server of the Application Server call back URL.
2
3
PopChart Server. The request includes the Application Server call-back URL.
4
PopChart Server “calls back” to the specified Application Server to get the data and
commands needed to create the PopChart image.
11-4
5
The Application Server retrieves data from a database.
6
The data and commands are sent to PopChart Server.
7
PopChart Server creates an image and sends it back to the browser.
8
www.corda.com
User Guide
.....
Request Format
.R. E. .Q. .U. E. .S. .T. .F. O. . R. .M. .A. .T. . . . . . . . . . . . . . . . . . . . . . . . . . . .
When you use an HTTP request to request an image from PopChart Server, your request
will be in the following format:
serveraddress/?servercommandstring
You should replace serveraddress with the hostname or address of the machine
running PopChart Server, followed by the server port (which, by default, is port 2001). If
you are using an HTTP redirector, you should instead give the address of the redirector,
without the server port (refer to “Using HTTP Redirection” on page 12-2).
Note:
This corresponds to the externalServerAddress attribute of the PopChart
Embedder. When you use the HTTP request method, you will not use a comm port.
Your server command string will consists of commands that tell PopChart Server about
the PopChart image you want to generate. For example,
@_FILEexamples/apfiles/bar.pcxml@_FLASH is a valid server command
string. The server command string will be discussed in more detail in the next section.
For example, if your server address were http://popchart.mycompany.com:2001, and
you were to use the server command string from the previous paragraph, you could request
an image from PopChart Server with the following HTTP request:
http://popchart.mycompany.com:2001/?@_FILEexamples/apf
iles/bar.pcxml@_FLASH
You may want to try this out yourself. Just change the server address to match that of your
server (if you are running PopChart Server with the default settings on your local
machine, use http://localhost:2001), and enter this URL into the address line of your web
browser.
11-5
.....
PopChart
11
6(5 9(5
Request Format
As long as your browser supports FLASH, you should see the following image:
11-6
www.corda.com
User Guide
.....
Server Commands
.S. E. .R. .V.E. .R. . C. .O. .M. .M. .A. N. .D. .S. . . . . . . . . . . . . . . . . . . . . . . . . .
Server commands are one way to communicate with PopChart Server. They can be
included in the query string of an HTTP request to PopChart Server, or in a separate
server command file.
SERVER COMMAND FORMAT
All server commands begin with the characters @_. They are also all capitalized. Examples
of server commands include @_FILE, @_PCSCRIPT, and @_GIF.
Each server command takes either zero or one arguments. If a command takes an argument,
the argument should immediately follow the command. The argument should not be in
parentheses, nor should there be a space or any other character between the command and
the argument.
For example, the @_FILE server command takes one argument, a file name. If the filename
is apfles/graph1.pcxml, the full server command with the argument would be:
@_FILEapfiles/graph1.pcxml
SERVER COMMAND STRINGS
Server commands are issued to PopChart Server via a server command string. The server
command string consists of any number of server commands, all joined together in one long
and unbroken line. In a URL or HTTP request, each command should follow the previous
without any sort of interruption (i.e. no semi-colon, period, space, line-break, etc.). In a
server command file, white space is not a problem. For example, if we wanted to issue the
commands @_FLASH, @_SAVEimage1.swf, @_DONTCACHE, and @_PWpass, we
could use the following command string:
@_PWpass@_SAVEimage1.swf@_DONTCACHE@_FLASH
Note:
The order of the commands does not matter.
COMMON SERVER COMMANDS
The following is a list of common server commands. For a complete server command
reference, refer to Chapter 6, “Server Commands,” in the PopChart Server Reference
manual.
..........................................................
Command
Purpose
@_FILEapfile
Specifies an appearance file.
11-7
.....
PopChart
11
6(5 9(5
Server Commands
..........................................................
Command
Purpose
@_FLASH
Specifies that the image format should be FLASH.
@_GIF
Specifies that the image format should be GIF.
@_HEIGHTheight
Specifies a height for the generated image.
@_LOADPCXMLfile
Instructs PopChart Server to load the specified PopChart XML file.
@_LOADREQUESTfile
Instructs PopChart Server to load the specified server command
file.
@_PCSCRIPTpcscript
Specifies a PCScript command string.
@_SVG
Specifies that the image format should be SVG.
@_WIDTHwidth
Specifies a width for the generated image.
URL ENCODING
Only alphanumerical [0-9, a-z, A-Z] characters, special characters such as $-_.,!*’(), and
reserved characters used for their reserved purposes may be used unencoded within a URL.
This means that if your HTTP request includes any of the following characters: ; / ? : @ =
& space < > # % { } | \ ^ ~ [ ] ‘ , it may not work properly.
Many of these characters are commonly included in the PCScript section of your server
command string. To overcome this obstacle, you should make it a habit to URL encode your
pcscript statements. When you do this, non-permissible characters are translated to
permissible character sequences (e.g. %20 for the space character) so that the HTTP request
remains valid. When PopChart Server receives the request, it will decode your server
command string.
Note:
Important:
If you are not yet familiar with PCScript, you should probably read “PopChart Script
Review” on page 7-2. PCScript is a very important aspect of dynamically generated
PopChart images, especially when you don’t have access to the PopChart Embedder.
PopChart Embedder automatically URL Encodes your PCScript. You do not need to
worry about URL Encoding with the PopChart Embedder.
You can URL encode your PCScript by hand, or you can pass it through a JavaScript
function that will do this automatically for you. We recommend the latter.
Such a JavaScript function is the urlEncode() function shown in Example 11.1.
Example 11.1
URL Encode Function
<script language="javascript">
function urlEncode(str) {
var ms = "%25#23 20?3F<3c>3E{7B}7D[5B]5D|7C^5E~7E‘60"
11-8
www.corda.com
User Guide
.....
Server Commands
var msi = 0
var i,c,rs,ts
while (msi < ms.length)
{
c = ms.charAt(msi)
rs = ms.substring(++msi, msi +2)
msi += 2
i = 0
while (true)
{
i = str.indexOf(c, i)
if (i == -1) break
ts = str.substring(0, i)
str = ts + "%" + rs + str.substring(++i, str.length)
}
}
return str
}
</script>
If you were to include this function in the header of your HTML file, you could encode your
PCScript by passing it through the urlEncode() function before attaching it to your
server command string. Example 11.2 shows how you could do this.
Example 11.2
URL Encoding the PCScript
<script language=javascript>
var pcscript = "Graph.Categories(Group 1, Group 2, Group 3)"
pcscript += "Graph.SetSeries(Item 1;54;75;85)"
document.write("<img src=’http://www.yourserver.com:port/?")
document.write("@_GIF@_FILEapfiles/Untitled@_PCSCRIPT")
document.writeln(urlEncode(pcscript) + "’>")
</script>
Note:
This embeds the HTTP Request in an image tag, a process that is discussed in the next
section.
11-9
.....
PopChart
11
6(5 9(5
Embedding a PopChart Image in an Image Tag
EMBEDDING A POPCHART IMAGE IN AN
IMAGE TAG
..................................................
You can embed a GIF or PNG image in a web page simply by creating an appropriate HTTP
request and making the request the source of an image tag.
You can generate a GIF PopChart image using the @_GIF server command. For example,
the following HTTP request will generate a GIF PopChart image:
http://localhost:2001/?@_FILEexamples/apfiles/bar.pcxm
l@_GIF
Note:
If you have enabled Automatic PNG Detection (see “Automatic PNG Detection” on
page 3-27 of the PopChart Server User Guide), this request will generate a PNG image on
browsers that support PNG. You cannot override this functionality.
If you want to explicitly request a PNG image, you can use the @_PNG command instead.
The following image tag embeds the GIF image we created with the HTTP request above. It
also provides an alternate text description of My PopChart in case the image loads slowly,
or for the visually impaired.
<img src="http://localhost:2001/?@_FILEexamples/apfile
s/bar.pcxml@_GIF" alt="My PopChart" />
T I P : U S I N G PopChart Builder T O G E N E R A T E H T M L
Just like you can use PopChart Builder to create example
code for use with the PopChart Embedder, you can also
use it to create example code for embedding a PopChart
using HTTP Requests. Simply load or create an
appearance file, select File > Sample Code, and
choose HTML.
The dialog also allows you to specify important variables,
such as PCScript and your server address.
11-10
In some cases, you can cut and paste this example code
directly into a file on your web server and have it work
immediately. Most of the time, though, you’ll want to
customize this code further before publishing your
PopChart image.
Either way, the sample code can save you a lot of time.
And, of course, it’s a great learning tool.
www.corda.com
User Guide
.....
Embedding a FLASH PopChart Image
.E. M. . B. .E. D. . D. .I .N. G. . .A. . .F.L. A. . S. .H. . P. .O. .P. C. .H. .A. R. .T. . I. M. . A. .G. .E. .
You can generate a FLASH PopChart image using the @_FLASH server command. For
example, the following HTTP request will generate a FLASH PopChart image:
l@_FLASH
Flash images can be embedded into web pages using an <object> tag for Microsoft
Internet Explorer browsers, and an <embed> tag for Netscape browsers. You can use the
@_FLASH server command to instruct PopChart Server to generate a Flash image.
The code below demonstrates how you can embed the Flash image you generated with the
above HTTP request. Note that by embedding the <embed> tag within the <object> tag,
the code makes sure that the image will display correctly on both Microsoft Internet
Explorer and Netscape.
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8444553540000"
codebase="http://download.macromedia.com/pub/shockwa
ve/cabs/flash/swflash.cab#version=4,0,0,0"
width="600" height="400">
<param name="MOVIE"
value="http://localhost:2001/?@_FILEexamples/apfiles
/bar.pcxml@_HEIGHT400@_WIDTH600@_FLASH">
<embed type="application/x-shockwave-flash"
pluginspage="http://www.macromedia.com/shockwave/dow
nload/index.cgi?P1_Prod_Version=ShockwaveFlash"
width="600" height="400"
ar.pcxml@_HEIGHT400@_WIDTH600@_FLASH">
</embed></object>
Important:
Be sure to set the height and width attributes inside the <object> and <embed> tag.
11-11
.....
PopChart
11
6(5 9(5
Embedding an SVG PopChart Image
.E. M. . B. .E. D. . D. .I .N. G. . .A. .N. . S. .V. G. . .P. .O. P. .C. .H. A. . R. .T. . I.M. .A. .G. E. . . .
You can generate an SVG PopChart image using the @_SVG server command. For example,
the following HTTP request will generate a SVG PopChart image:
l@_SVG
SVG images can be embedded into web pages using an <embed> tag and the @_SVG
server command. You must also be sure to specify the width and the height attributes
for the image in the <embed> tag.
<embed type="image/svg-xml"
pluginspage="http://www.adobe.com/svg/viewer/install
/main.html" width="600" height="400"
ar.pcxml@_HEIGHT400@_WIDTH600@_SVG">
</embed>
11-12
www.corda.com
User Guide
.....
Best Image Fallback
.B. E. .S. .T. .I .M. .A. G. .E. . F. .A. .L. L. .B. A. .C. .K. . . . . . . . . . . . . . . . . . . . . .
One of the biggest drawbacks of using the HTTP Reqeust method is that there is no easy
way to support Best Image Fallback. Whereas with the PopChart Embedder you can use
the fallback attribute to have PopChart Server automatically return an image in the
best supported image format (refer to “Best Image Fallback” on page 4-13), you have to
use JavaScript to hand-code this functionality into images that you embed using the HTTP
request method.
The basic idea of such code is to use a combination of JavaScript and VBScript to detect the
version of the client’s browser and the plug-ins that browser supports. Based on that
information, you then output a FLASH, SVG, or GIF image, depending on what the browser
supports.
Example 11.3 shows how to create a FLASH image with Best Image Fallback to a GIF
image.
Note:
Example 11.3
The JavaScript code for doing this is not for the faint-hearted. In fact, we hope a simple
glance at the code necessary to do this will convince you to use the PopChart Embedder.
Best Image Fallback with HTTP Request Method

</script>
11-13
.....
PopChart
11
6(5 9(5
Best Image Fallback
<script language="VBScript">

</script>

</script>

11-14
www.corda.com
User Guide
.....
Best Image Fallback
</script>

</script>
11-15
.....
PopChart
11
6(5 9(5
OVERCOMING THE URL LENGTH
RESTRICTION
..................................................
Many web browsers have a limit of two thousand characters for a URL request string. The
embed tag for an SVG object has a limit of 256 characters. Both of these limitations directly
impact the HTTP request method.
Important:
Because of the nature of JavaScript, the JavaScript PopChart Embedder also has this
limitation.
Most of the time, your HTTP request strings will be well under two thousand characters.
However, the SVG limitation can be difficult to get around, especially when you have a
large amount of data. For this reason, we recommend using the PopChart Embedder.
If you are graphing a large amount of data and don’t want to use the PopChart Embedder,
you will need to remove the data from the URL request string. To do this, you can try the
following options: Server Command Files and Loading Data Files.
SERVER COMMAND FILES
A server command file is simply a file that contains nothing but a server command string. It
can reside either on the computer running PopChart Server, or on a separate computer. It
can also be generated dynamically by a web application (this process is known as appserver callback).
Important:
Do not URL-encode a server command file.
You can load a server command file with the @_LOADREQUEST server command. For
example, to load the server command file examples/command/command1.txt, use the
following server command:
@_LOADREQUESTexamples/command/command1.txt
For more information on server command files, refer to “Server Command Files” on
page 6-13.
LOADING DATA FILES
You can also get around the URL length restriction by storing all of your data in data files,
located either on the computer running PopChart Server, or on a separate computer. Your
data files can also be generated dynamically by a web application (this process is known as
app-server callback).
For information about this, read Chapter 6, “Sending Dynamic Data to PopChart
Server.”
11-16
www.corda.com
User Guide
.....
Be sure to use the PCScript graph.LoadFile() method to load data files.
One command not mentioned in that chapter is the @_LOADPCXML server command, which
allows you to load PopChart XML files. For example, to load the
examples/pcxml/pcxml1.xml file, use the following server command:
@_LOADPCXMLexamples/pcxml/p_data1.xml
11-17
.....
PopChart
11
11-18
6(5 9(5
www.corda.com
HTTP R EDIRECTION
.....
...................................
12
M
any web servers allow for special modules that make it possible for the web server to
interact with other applications and servers. The PopChart HTTP Redirector is one such
module.
When installed on a web server, the HTTP Redirector allows the web server to handle
requests from clients for PopChart images. The web server receives the request and
redirects it to PopChart Server. PopChart Server returns the generated image to the web
server, which then redirects it to the client’s browser.
Note:
PopChart Embedder cannot communicate with PopChart Server via HTTP redirection
(except for the JavaScript version). This does not mean that you can’t use HTTP redirection
with PopChart Embedder, though. See “Using HTTP Redirection” on page 12-2 for
details.
There are two major reasons for using HTTP redirection with PopChart Server:
• To avoid exposing a new port through a firewall. If PopChart Server is behind a
firewall on a port other than 80, users outside of the firewall will probably be unable to
see images created by PopChart Server unless you specifically open its port to the
outside world. HTTP redirection allows you to work around this.
• To work with Secure Socket Layer (SSL). If have an SSL web server, you can redirect
requests to PopChart Server through the web server using the HTTP redirector
adapters, thus taking advantage of SSL for communication with PopChart Server.
For general information about using HTTP Redirection, refer to the first section of this
chapter, “Using HTTP Redirection” on page 12-2.
HTTP redirectors for PopChart Server are easy to set up, and are available for the
following web servers:
• Microsoft Internet Information Services
• Apache Web Server
• J2EE Web Application Servers
The last three sections talk about setting up HTTP redirection with these web servers.
12-1
.....
PopChart
12
6(5 9(5
HTTP REDIRECTION
Using HTTP Redirection
.U. S. .I.N. G. . .H. .T. T. .P. . R. .E. D. . I.R. .E. C. .T. I. O. .N. . . . . . . . . . . . . . . . . . .
When you use HTTP redirection, all client communication with PopChart Server is
handled by the web server. From a security standpoint, this means that when you talk to
PopChart Server, you inherit the same security settings that your web server has.
From a development standpoint, the main consequence of this is that all requests to
PopChart Server should be made to the PopChart module on the web server itself.
For example, suppose that you are running PopChart Server on the same machine as your
web server, http://www.mycompany.com. Without a redirector, a client would use this
address to communicate with PopChart Server: http://www.mycompany.com:2001.
With a redirector, a client can request a PopChart image from an address similar to the
following: http://www.mycompany.com/popchart.dll (for the ISAPI redirector for IIS) or
http://www.mycompany.com/servlet/popchart (for the Servlet redirector).
Notice that by using the redirector, we no longer have to use port 2001. To the client, it
appears that PopChart Server is running over the web server port (80). In the PopChart
Embedder, this means that instead of setting your externalServerAddress attribute
to http://www.mycompany.com:2001, you would set it to
http://www.mycompany.com/scripts/popchart.dll, as illustrated in the following line of
code.
"http://www.mycompany.com/scripts/popchart.dll";
Note:
The JavaScript PopChart Embedder does not use externalServerAddress.
Instead, if you are using a redirector, you will request the jsEmbedder (refer to “Importing
the PopChart Embedder Library” on page 4-5) from this address.
This does not affect the internalCommPortAddress, however. The PopChart
Embedder uses a separate port (the comm port, 2002), and cannot communicate with
PopChart Server through a redirector. Since the web application that uses PopChart
Embedder will also be behind the firewall, a redirector is not necessary.
HOW IT WORKS
If you are confused about how the PopChart Embedder works, consider the following
setup. Your web server is located at http://popchart.mycompany.com. On this web server,
you have a web page called stats.asp that uses PopChart Embedder to embed a PopChart
image. PopChart Server is on a machine behind the firewall at 10.0.1.2, using its default
port settings (server port = 2001, comm port = 2002). You have setup the ISAPI PopChart
redirector on your web server.
12-2
www.corda.com
User Guide
.....
HTTP REDIRECTION
Using HTTP Redirection
In this situation, in your PopChart Embedder code, you should set the
externalServerAddress and the internalCommPortAddress attributes as
follows:
myPopChart.externalServerAddress = "http://popchart.my
company.com/scripts/popchart.dll";
internalCommPortAddress = "10.0.1.2:2002";
When a client requests the stats.asp page from the web server, PopChart Embedder will
send an image request to PopChart Server over port 2002 at the address 10.0.1.2.
PopChart Server will generate the image and return to PopChart Embedder the HTML
necessary for the client to request the image. PopChart Embedder will write this to the
web page, and the web server will send the page on to the client.
In the web page, the client will see a tag similar to the following.
<img src= "http://popchart.mycompany.com/scripts/popchar
t.dll?12345"/>
It will then request an image from the address
http://popchart.mycompany.com/scripts/popchart.dll. The web server receives this
request and redirects it to port 2001 at the address 10.0.1.2, which is PopChart Server’s
server port. PopChart Server will see the query string, fetch the image, and send it back to
the web server, which then forwards it on to the client.
12-3
.....
PopChart
12
6(5 9(5
HTTP REDIRECTION
Microsoft Internet Information Services
MICROSOFT INTERNET INFORMATION
SERVICES
..................................................
Using the PopChart ISAPI redirector, you can use HTTP redirection with Microsoft’s
Internet Information Services (IIS). ISAPI (Internet Server Application Program Interface)
is an API created by Microsoft that allows its Internet Information Server (IIS) to
communicate with other applications. The PopChart Server ISAPI module integrates
PopChart with IIS by allowing IIS to server requests for PopCharts to PopChart Server
instead of requiring PopChart Server to receive these requests directly.
T o s e t up th e P o p C h a rt I S A P I R ed i re c to r
1
Copy the popchart.dll and popchart.cfg files from your dev_tools/ISAPI_redirector
folder to the \Inetpub\Scripts directory.
2
If you are running PopChart Server on a machine other than the one running IIS, or on a
port other than the default (2001), modify the port and address in the popchart.cfg file.
The popchart.cfg file tells the redirector where PopChart Server is located. It
consists of just one line, in the following format:
-port popchart.image.server:port
You should replace popchart.image.server with the name or IP address of
the computer on which PopChart Server is running. You should replace port with
the port on which PopChart Server is running. For example, if PopChart Server
is running on port 8080 on a computer with the IP address 12.0.8.10, the
popchart.cfg file should contain the following line:
-port 12.0.8.10:8080
Note that this address must be accessible to the computer running IIS, but does not
need to be visible to the client requesting the PopChart.
Note:
If you change this file after you have already attempted to use the redirector, you will need
to restart IIS so that it can update the settings.
You may also need to change the permissions on the popchart.dll file so that web
clients are able to access it. For instructions on how to do this, refer to your IIS
documentation.
3
Web clients will now be able to request images from popchart.dll on your web server.
For example, if your web server is running at http://www.mycompany.com,
clients will access PopChart Server through the PopChart redirector at
http://www.mycompany.com/scripts/popchart.dll.
You should modify your PopChart Embedder code or HTTP requests to
PopChart Server so that they use the address of the redirector instead of the
12-4
www.corda.com
User Guide
.....
HTTP REDIRECTION
Microsoft Internet Information Services
address of PopChart Server, as described in “Using HTTP Redirection” on
page 12-2.
12-5
.....
PopChart
12
6(5 9(5
HTTP REDIRECTION
Apache Web Server
.A. P. .A. .C. H. .E. . W. . .E. B. . .S. E. .R. .V. E. .R. . . . . . . . . . . . . . . . . . . . . . . .
The PopChart Apache Module (mod_pcis) integrates PopChart with Apache by allowing
Apache to receive requests for PopCharts instead of PopChart Server.
Note:
You can also use the ISAPI redirector for Apache if you are running it on Windows
NT/2000/XP, but this is neither documented or recommended.
This section will help you setup the redirector for Apache. It assumes you are running a
version of Apache that supports the dynamic loading of add-in modules (Apache 1.3 or
above). You should be logged in as root or have administrative privileges to install the
module.
T o in s t al l th e pr e -c o mp i le d mo d _ p c is b i na r y
1
Locate the version of mod_pcis.so that has been built for your specific platform. The
binary files are located in the dev_tools/apache_redirector directory.
If you cannot find a pre-compiled binary for your platform, check the Corda
Technologies website (http://www.corda.com) for additional binaries. If you still
cannot find a pre-compiled version, you will need to compile it yourself (refer to
“To build mod_pcis from the source code” on page 12-8).
2
Locate your Apache server configuration file, httpd.conf. You will need to edit this file
later on.
The location of this file varies based on your platform and the installation of
Apache. It is usually under the /etc./apache or the /etc./httpd/conf directory.
Note:
3
In the folder from which you copied the mod_pcis.so file, you will find an
example_httpd.conf file. This file is an example of what a correctly modified httpd.conf
file might look like.
Copy the mod_pcis.so file to the directory that contains dynamic modules for your
Apache web server.
Usually, this will be the libexec folder inside of your server root directory (e.g.
/usr/apache/libexec). You can verify this location by looking at LoadModule
entries in your httpd.conf file.
4
In your httpd.conf file, find the section containing LoadModule entries. At the bottom of
this section, add the following entry:
LoadModule pcis_module libexec/mod_pcis.so
If you copied the mod_pcis.so file to a different location, you will need to change
this line accordingly.
12-6
www.corda.com
User Guide
.....
HTTP REDIRECTION
Apache Web Server
5
In your httpd.conf file, find the section containing AddModule entries. At the bottom of
this section, add the following entry:
AddModule mod_pcis.c
6
In your httpd.conf file, locate the <Directory> tag section for your web server’s
DocumentRoot (usually <Directory "/home/httpd/html">). In this section, locate
the list of AddHandler entries. At the bottom of this list, add the following entry:
AddHandler pcis .mod
This command instructs the web server to assign the mod_pcis handler to any
request it receives ending with a .mod extension. You can assign this extension to
any value you choose. In fact, if you already have a handler for the .mod extension,
you will have to choose a different extension.
For example, .pcredirector is also perfectly valid. To have the PopChart redirector
handle any requests using a .pcredirector extension, use this statement:
AddHandler pcis .pcredirector
7
Create a subfodler called pcis within the ServerRoot path of your Apache installation
(e.g. /usr/apache/pcis). Locate the popchart.cfg file from the same folder that contained
mod_pcis.so file and copy it to the pcis subfolder.
8
In the popchart.cfg file, specify the name of the machine and port number that
PopChart Server is running on.
The popchart.cfg file tells the redirector where PopChart Server is located. It
consists of just one line, in the following format:
-port popchart.image.server:port
You should replace popchart.image.server with the name or IP address of
the computer on which PopChart Server is running. You should replace port with
the port on which PopChart Server is running. For example, if PopChart Server
is running on port 8080 on a computer with the IP address 12.0.8.10, the
popchart.cfg file should contain the following line:
-port 12.0.8.10:8080
Note that this address must be accessible to the computer running Apache, but does
not need to be visible to the client requesting the PopChart.
You may also need to change the permissions on the mod_pcis.so file so that web
clients are able to access it. For instructions on how to do this, refer to your Apache
documentation.
12-7
.....
PopChart
12
6(5 9(5
HTTP REDIRECTION
Apache Web Server
9
Restart your web server.
You can do this with the apachectl restart command from the bin directory
of your web server’s root directory (you can also restart with the command make
restart from the mod_pcis_src directory).
10
Note:
Web clients will now be able to request images from popchart.mod on your web server.
Actually, they can request a PopChart from anything as long as it has a .mod extension
(e.g. pc.mod, getimage.mod, etc.). If you chose an extension other than .mod in Step 6,
request images from that extension instead (e.g. popchart.pcredirector).
For example, if your web server is running at http://www.mycompany.com,
clients will access PopChart Server through the PopChart redirector at
http://www.mycompany.com/popchart.mod.
page 12-2.
T o b u il d mod_pcis fr o m t h e s o u rc e c o d e
To build mod_pcis, you must have the following: a make utility, C compiler, and PERL.
Most UNIX compatible systems will already have these.
1
Copy all the files in the dev_tools/apache_redirector/mod_pcis_src folder to a
convenient temporary location on your system (e.g. /usr/local/mod_pcis/). The actual
location does not matter.
2
Modify the Makefile file so that the APXS and APACHECTL variables reflect the complete
path to your web server’s bin directory.
For example, if your web server’s bin directory is /usr/apache/bin, you would set
the two macro as follows:
APXS = /usr/apache/bin/apxs
APACHECTL = /usr/apache/bin/apachectl
Alternatively, you could make sure that this directory is defined in your
environment path.
3
Also in Makefile, edit the value of the INC variable to point to the directory to which you
copied the mod_pcis source files.
For example, if you copied the files to /usr/local/mod_pcis, you would set the
INC variable as follows:
INC = -I/usr/local/mod_pics
Make sure that you save Makefile when you are done modifying it.
12-8
www.corda.com
User Guide
.....
HTTP REDIRECTION
Apache Web Server
4
Run the Makefile by entering the command make install (or gmake install).
The Makefile will make the appropriate apxs call to compile the source and copy
the completed module into the Apache install directory. The apxs command in the
Makefile also adds the necessary lines to your web server’s httpd.conf file to load
mod_pcis dynamically when the web server restarts.
Note:
5
Solaris Users: If you installed a binary version of Apache, chances are that Apache’s apxs
script (written in Perl and located in the bin directory of the Apache server root) will not
properly compile mod_pcis. If it does not properly compile, you will have to manually edit
the apxs script file and specify the correct name of your installed C compiler. To do this,
locate the my $CFG_CC variable in the script file and enter your compiler name, (e.g.
gcc). You may also have to tweak with the my $CFG_CFLAGS and my
$CFG_CFLAGS_SHLIB variable values to make it work. Also, make sure that the first line
in the apxs script points to the correct location for your Perl interpreter. We have included
an example apxs file, apxs_example, in the mod_pcis_src directory for your reference.
To set up mod_pcis, follow the steps in “To install the pre-compiled mod_pcis binary”
above, beginning with step 6.
12-9
.....
PopChart
12
6(5 9(5
HTTP REDIRECTION
J2EE Web Application Servers
.J.2. E. .E. . W. . .E. B. . .A. P. .P. .L.I.C. .A. T. .I .O. N. . .S. E. .R. .V. E. .R. .S. . . . . . . . .
One of the many ways you can call the PopChart Server is through the servlet redirector.
By using your web/application server’s servlet invoker with PopChart you will gain the
ability to communicate using Secure Sockets (SSL), and also eliminate the need to expose
another port outside of your firewall. All communication to PopChart Server from the
clients will pass through the servlet redirector.
T o in s t al l th e S er v le t r e di re c t or
1
Locate the folder from which your web application server serves Java Servlets. In some
cases this folder will be called WEB-INF. In other cases it will be called servlet. We will
refer to this folder as the web application server’s servlet folder.
If you do not know where this folder is, consult the server’s documentation. The
location for some of the more common web application servers are discussed later
in this section.
2
Copy the pcRedirector.jar file from the dev_tools/servlet_redirector folder to the lib
subdirectory of the servlet folder.
The pcRedirector.jar file contains the PopChart redirector Servlet.
3
Register the servlet with your web application server.
You will need to register the popchart class.
The procedure for registering a servlet is different for each web application server.
You should consult your web application server’s documentation for details. The
procedures for some of the more common web application servers are mentioned
later in this section.
4
Set the initialization parameters for the servlet.
The PopChart servlet has one possible initialization parameter,
PopChartServer. This parameter is optional, but unless you are running
PopChart Server on the localhost over port 2001, you will need to set the
PopChartServer parameter.
You should set the value of this parameter to the address and port that your
PopChart Server is running on. For example, if PopChart Server is running over
port 2001 on the machine at the address 10.0.0.53, you would set this parameter as
follows:
PopChartServer=10.0.0.53:2001
This IP address and port needs to be accessible from the machine where the
PopChart servlet is running. The address can be to a computer behind a firewall, as
long as that computer is visible to the web server where the servlet is running. You
can also specify a computer name instead of an IP address, as long as the name can
be resolved to an IP address.
12-10
www.corda.com
User Guide
.....
HTTP REDIRECTION
The procedure for initializing a parameter is different for each web application
server. You should consult your web application server’s documentation for details.
The procedures for some of the more common web application servers are
mentioned later in this section.
5
Restart your web application server.
6
Test your servlet by hitting it directly. It should return version information.
For many web application servers, you can “hit” the PopChart redirector servlet by
going to the address http://mycomputer/servlet/popchart, where mycomputer is
the address of the web application server. For other web application servers, such as
Tomcat, you will need to go the address
http://mycomputer/default/servlet/popchart. Consult your web application
server for more information if neither of these addresses work.
7
Web clients will now be able to request images from the address that you tested in the
previous step.
page 12-2.
NOTES FOR WEBLOGIC
For Weblogic, your servlet folder will probably be /myserver/servlet/lib/.
To register the servlet with Weblogic, you will need to modify the weblogic.properties
file and add the following line:
weblogic.httpd.register.popchart = popchart
To set the initialization parameter, add the weblogic.httpd.initArgs.popchart
variable in this file. For example, if your initialization parameter (see step 4) is
PopChartServer=10.0.0.53:81, you would add the following line to
weblogic.properties:
weblogic.httpd.initArgs.popchart =
PopChartServer=10.0.0.53:81
NOTES FOR TOMCAT
The servlet folder on Tomcat will be tomcat/webapps/default/WEB-INF, where tomcat
is the install directory for Tomcat, and default is the name of the application that you are
adding the servlet to. For example, if you are using the default web-application, you would
12-11
.....
PopChart
12
6(5 9(5
HTTP REDIRECTION
add the popchart.class to the following location: tomcat/webapps/default/WEBINF/lib/pcRedirector.jar.
To register a servlet in the Tomcat environment, you will need to create a file named
web.xml (if it doesn’t already exist) in the WEB-INF directory for your application. Below
is an example of what you will need to include in this file. If the file already exist, then just
add the portion between the <servlet> tags.
Example 12.1
Registering the Servlet redirector with Tomcat’s web.xml File
<web-app>
<servlet>
<servlet-name>
popchart
</servlet-name>
<servlet-class>
popchart
</servlet-class>
<init-param>
<param-name>PopChartServer</param-name>
<param-value>localhost:2001</param-value>
</init-param>
</servlet>
</web-app>
To properly set the initialization parameter, you should change the value in the <paramvalue> tag to match the address and port of the machine running PopChart Server.
NOTES FOR JRUN
On JRun, servlets usually go in the <application>/WEB-INF/lib/ directory, where
<application> is the JRun install directory. For example, if you are using the JRun Default
Server, then you would want to put the popchart.class file in the following location on
UNIX: /usr/JRun/servers/default/default-app/WEB-INF/lib/pcRedirector.jar. On
Microsoft Windows, this location might be: D:\JRun\servers\default\default-app\WEBINF\lib\pcRedirector.jar.
To register a servlet in the JRun environment, you will need to start the management
console (JMC) and select Application > Servlet Definitions. For example, if you are
installing the servlet under the Default Server, select JRun Default Server > Web
Applications > Default User Application > Servlet Definitions from the left
sidebar.
From here, you can add the definition for the PopChart Servlet. You will need to set the
Name value to popchart, the Class Name value to popchart, and the Init Argument
12-12
www.corda.com
User Guide
.....
HTTP REDIRECTION
to your initialization parameter (see step 4). Click on Update and restart the JRun Default
Server when you are done.
TROUBLESHOOTING
If the servlet is not functioning properly, you will most likely either receive an error
message when you try to test the servlet (step 6) or see a message displayed on the web
server’s console. Below are two common errors that you might find:
JAVA.LANG.NOCLASSDEFFOUNDERROR: POPCHART
(WRONG NAME: POPCHART)
This error will most likely occur if you have not put the pcRedirector.jar file in the correct
directory structure, or you haven’t restarted the web application. The .jar file must be in the
right directory for servlets, and must also be registered with your web application server.
Refer to your web applications server’s documentation and the section to correct this
problem.
ERROR: POPCHART IMAGE SERVER DOES NOT APPEAR TO
BE RUNNING AT 127.0.0.1 PORT :2001.
This error will show up in your browser if the servlet cannot contact PopChart Server
running on the localhost port 2001. You may need to create an PopChartServer init
parameter for your environment (see step 4 of the installation procedure). The directions
listed in the browser with this error should help to correct this problem.
12-13
.....
PopChart
12
12-14
6(5 9(5
HTTP REDIRECTION
www.corda.com
C LUSTERING
.....
...................................
13
T
his chapter discusses how to set up PopChart Server for clustering. Clustering is
available only in PopChart Server Enterprise.
If the applications you are developing are mission critical or will be under extreme load,
then you may wan to consider taking advantage of the clustering capabilities built in to
PopChart Server Enterprise.
Clustering of two or more PopChart Servers is useful in situations where you need high
redundancy and/or greater throughput. Clustering allows a group of servers to share
information about PopChart images that are being requested and served. When servers are
clustered, a hardware or software failure on one server does not prevent the image being
delivered to the requesting browser. Clustering also allows a group of PopChart Servers to
scale throughput by dividing request processing and image generation across multiple
servers.
Note:
Due to the nature of clustering, this is a highly technical chapter. You may need a good
understanding of network administration to be able to follow along.
The first three sections will help you get ready to setup clustering for PopChart Server:
• Requirements
• About the pcClusterMonitor
• Determining Your Network Architecture
The last four chapters will help you set up different aspects of PopChart Server for
clustering:
• Enabling PopChart Server for Clustering
• PopChart Embedder Configuration
• HTTP Redirector Configuration
• pcClusterMonitor Configuration
Important:
Please read all of these sections carefully, even if you think they might not apply to you.
13-1
.....
PopChart
13
6(5 9(5
CLUSTERING
Requirements
.R. E. .Q. .U. I. R. .E. .M. E. .N. .T. S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
• Two or more PopChart Server Enterprise systems on the same network.
• Applications must be developed using either the Java, COM, or .NET version of the
PopChart Embedder.
• So that all of the servers have access to the same data and appearance files, your
PopChart document root directory must be mirrored on all of the servers.
Note:
Another option would be to have all the servers use a shared document root directory. If you
are using a shared directory, though, be sure that the shared folder resides on a high
redundancy server, as a failure here would undermine the redundancy of PopChart Server.
• We strongly recommend that the servers be configured exactly the same. If you make
changes to one server, you should make those changes to all of your servers.
You may even want to copy the following files from the config directory of a properly
configured server to the config directory for other your other servers to make sure that the
servers are all configured properly: pcagent.cfg, pccolors.xml, dlink.xml, table.xml, and
path.xml.
13-2
www.corda.com
User Guide
.....
CLUSTERING
About the pcClusterMonitor
.A. B. .O. .U. .T. .T. H. .E. . P. .C. .C. L. .U. .S. T. .E. R. .M. .O. .N. I. T. .O. .R. . . . . . . . . .
Some clustering configurations may require the use of the pcClustermonitor. This is a utility
very similar to the HTTP redirector, available as a java Servlet or ISAPI dll.
The pcClusterMonitor is designed to run on the same physical server as your web
Application server. It facilitates communication between the PopChart Embedder and
multiple PopChart Servers in a PopChart cluster.
It will usually be used with PopChart Embedder when PopChart Server is not running
on the same machine as the web application sever, and there is no load balancing between
the web application server and the PopChart Server cluster.
When using the pcClusterMonitor with PopChart Embedder, PopChart Embedder uses
the clusterMonitorAddress attribute to identify where the pcClusterMonitor is
running. PopChart Embedder will make a call to the pcClusterMonitor, which returns a
comm port address and server address for a server in the PopChart Cluster. PopChart
Embedder use the returned addresses to set the internalCommPortAddress and
externalServerAddress. If the externalServerAddress attribute has already
been set, PopChart Embedder does not change it.
If the connection fails when PopChart Embedder actually tries to talk to the specified F, it
will notify the pcClusterMonitor of the failure and will receive a new set of addresses. The
pcClusterMonitor checks with the PopChart Cluster every so often to make sure it has a
current set of valid addresses.
It is recommended that each Application Server machine run its own copy of the
pcClusterMonitor. This way the Application Servers are not relying on another machine for
Cluster information.
For details about how to specify your cluster monitor address in PopChart Embedder,
refer to “Configuring the ClusterMonitor Address” on page 13-13. For information about
setting up the pcClusterMonitor, refer to “pcClusterMonitor Configuration” on
page 13-16.
13-3
.....
PopChart
13
6(5 9(5
CLUSTERING
Determining Your Network Architecture
DETERMINING YOUR NETWORK
ARCHITECTURE
..................................................
Our customers use PopChart Server with a wide variety of network configurations, often
involving firewalls, hardware or software load balancers, and web servers which front end
the application servers.
We have designed PopChart clustering to work with multiple network architectures and
implementations. Before configuring clustering for your PopChart Server, you will need
to understand how PopChart Server will be integrated into your network architecture.
Examine the diagrams on the following pages (Example 13.1 through Example 13.6) and
determine which implementation most closely matches your setup. The diagrams will help
you figure out how to set up clustering in your configuration. Particularly, it will help you
figure out whether or not you need the pcClusterMonitor, as well as what values you will
need to give your PopChart Embedder attributes. The remaining sections of this chapter
will refer to these diagrams.
After you have done that, read the rest of this chapter for instructions on setting up different
aspects of PopChart Server for clustering.
DEFINITIONS
Client
A web browser which requests a web page or
PopChart image.
PopChart Server
A server from which the client requests a
web page, possibly including those being generated by the
Application server.
External firewall
Web Server
A server that is dynamically
generating web pages or content for web pages. The
applications running on this server contact PopChart
Server through the PopChart Embedder to get
embedding HTML for PopChart images. Sometimes the
Web server and the Application server are the same, but in
these diagrams they are mentioned individually.
Application Server
13-4
A server that dynamically generates
PopChart images for delivery to client browsers.
A firewall between the client and the
Web server.
Internal firewall A firewall between the Web server and
the Application server.
Load Balancer
A hardware or software based load
balancer.
Round Robin DNS A type of software load balancing
that returns a different IP address each time a DNS lookup
is made, or which may resolve to another DNS in a round
robin fashion in order to load balance multiple servers.
www.corda.com
User Guide
.....
CLUSTERING
Example 13.1
13-5
.....
PopChart
13
6(5 9(5
CLUSTERING
Example 13.2
13-6
www.corda.com
User Guide
.....
CLUSTERING
Example 13.3
13-7
.....
PopChart
13
6(5 9(5
CLUSTERING
Example 13.4
13-8
www.corda.com
User Guide
.....
CLUSTERING
Example 13.5
13-9
.....
PopChart
13
6(5 9(5
CLUSTERING
Example 13.6
13-10
www.corda.com
User Guide
.....
CLUSTERING
Enabling PopChart Server for Clustering
E N A B L I N G PopChart Server F O R
CLUSTERING
..................................................
The first step in configuring your PopChart Server cluster is to enable clustering on all of
the servers. There are two ways of placing PopChart Server into a cluster: Auto-cluster
and Declared Clusters.
These settings will need to be applied to each server individually.
AUTO-CLUSTER
Auto-clustering is, of course, the most convenient way of enabling clustering. When you
auto-cluster, PopChart Server will scan through the entire 255.255.255.0 subnet for other
clustering-enabled servers. For example, if PopChart Server’s address is 10.0.1.28 and
you enable auto-clustering, PopChart Server will cluster with any server whose address is
10.0.1.x (e.g. 10.0.1.1, 10.0.1.2, etc.). In order for this to work, all PopChart Servers
must be using the same comm port number.
If PopChart Server is on the same subnet and has the same port and commport settings for
all servers, you can enable autoclustering simply by going to the Settings > Clustering
page in your Administration Console, checking Enable Clustering, and selecting the
Auto Cluster radio button. Each PopChart Server in the cluster will need to be restarted
after Applying the changes.
DECLARED CLUSTERS
If your servers are on different subnets, or if they do not use the same comm port number,
you will be unable to use auto-clustering. However, you can still declare your cluster
manually.
For example, suppose you want to cluster instances of PopChart Server running at
134.12.16.32 with a commport of 2002, 168.15.45.24 with a commport of 4008, and
192.63.21.250 with a commport of 7007.
You can enable clustering manually for each server by going to the Settings >
Clustering page in the Administration Console, checking Enable Clustering, and
selecting the Manual Cluster radio button.
You then need to list the IP addresses and ports for each server in you cluster, separated by a
comma, in the Cluster Server List box. For our example setup, you would enter the
following: 134.12.16.32:2002, 168.15.45.24:4008, 192.63.21.250:7007.
Not all three addresses would be required. In fact, you may only need to list one address, as
once a server finds one server in the cluster, it can find all of the servers in the cluster. For
redundancy, however, it is a good idea to list two or three addresses.
13-11
.....
PopChart
13
6(5 9(5
CLUSTERING
PopChart Embedder Configuration
.PopChart
. . . . . . . . .Embedder
. . . . . . . . . . C. .O. .N. F. .I.G. .U. R. .A. .T. I.O. .N. . . . . . . . . . .
Another important step in setting up your cluster is figuring out how to use the PopChart
Embedder. Specifically, clustering may affect the values of up to three attributes in your
PopChart Embedder code: externalServerAddress,
internalCommPortAddress, and clusterMonitorAddress.
PopChart Embedder interfaces between your web applications and PopChart Server.
All communication between PopChart Embedder and PopChart Server is done through
the communications port (commport). This address is set using the
internalCommPortAddress attribute of the PopChart Embedder. Meanwhile,
images are served to the client from the PopChart Server’s main port, set by PopChart
Embedder’s externalServerAddress attribute. By default the main port is 2001 and
the commport is 2002.
The main port may be exposed directly, however it is common to use one of the PopChart’s
HTTP redirectors to redirect http requests on port 80 on the web server to PopChart
Server’s main port. Refer to Chapter 12, “HTTP Redirection,” for details.
The PopChart Server commport should not be exposed outside of your firewall. However,
this IP and port needs to be visible to the application using the PopChartEmbedder.
CONFIGURING THE COMMPORT ADDRESS
The value that you set for the comm port address (internalCommPortAddress) will
depend on your network architecture.
N E T W O R K A R C H I T E C T U R E I S S I M I L A R T O Example 13.1
T H R O U G H Example 13.5.
If PopChart Server is running on the same physical server as your Application Server
(each Application Server has a 1:1 mapping to a PopChart Server), then you can set the
comm port address to your local computer, as in the following line of code:
myPopChart.internalCommPortAddress= "127.0.0.1:2002"
This, of course, assumes that the comm port is 2002.
If you want your Application Servers to be able to talk to several PopChart Servers in the
cluster, but the Application Server will talk to them directly (not through a load balancer),
then you need to use a pcClusterMonitor (refer to “Configuring the ClusterMonitor
Address” on page 13-13). If this is the case, you will not use
internalCommPortAddress. The same is true if your applications are running on
different machines than your PopChart Servers, and the applications are talking directly to
the PopChart Servers (not through a load balancer). This situation could be possible in a
network architecture similar to that of Example 13.2 through Example 13.5.
13-12
www.corda.com
User Guide
.....
CLUSTERING
N E T W O R K A R C H I T E C T U R E I S S I M I L A R T O Example 13.6
If a load balancer is exposing a virtual IP:port combination to your Application Servers for
the PopChart Cluster commport, then you would want to set your comm port address to the
virtual address being exposed by your load balancer. For example, if your load balancer
maps the virtual address 100.10.20.50:2002 to your PopChart Cluster (i.e. it randomly picks
a PopChart Server to forward communication to), you would assign your comm port as
follows:
CONFIGURING THE SERVER ADDRESS
The value of your server address (externalServerAddress) will also depend on your
network configuration.
SERVER ADDRESS WITH HTTP REDIRECTION
If you are using a redirector, set the server address to point to the address of the redirector.
Refer to Chapter 12, “HTTP Redirection,” for details.
N E T W O R K A R C H I T E C T U R E S I M I L A R T O Example 13.1
In Example 13.1, applications running on server 1 would set their server address to the
redirector running on server 1, while applications running on server 2 would set their server
address to the redirector running on server 2, and so on. This is because each server is its
own web server and requires its own redirector.
N E T W O R K A R C H I T E C T U R E S I M I L A R T O Example 13.2 T H R O U G H
Example 13.6
In these examples, the server address will be the same for all of the Application Servers.
This is because there is only one web server or virtual web server, and therefore only one
HTTP redirector address.
SERVER ADDRESS WITHOUT HTTP REDIRECTION
In most configurations without a redirector, you will use a load balancer. This is the case in
Example 13.2 and Example 13.6 (Example 13.3-Example 13.5 require a redirector). In
this case, set the server address to the virtual IP address and port that the load balancer
assigns to the PopChart Cluster.
CONFIGURING THE CLUSTERMONITOR ADDRESS
If you are using the pcClusterMonitor, you should never set the comm port address
(internalCommPortAddress).
13-13
.....
PopChart
13
6(5 9(5
CLUSTERING
If you are running on Windows and have IIS installed, you can use the ISAPI version of the
pcClusterMonitor. You would set the monitor address in PopChart Embedder with this
line of code:
myPopChart.clusterMonitorAddress =
"http://localhost/scripts/pcClusterMonitor.dll/";
If you are using a Java-based Application Server you can use the servlet version of
pcClusterMonitor. You would set the monitor address in PopChart Embedder with this
line of code:
myPopChart.clusterMonitorAddress =
"http://localhost/servlet/pcClusterMonitor/";
Note:
13-14
These examples assume the cluster monitor is running on the same system as the web
application server, which is highly recommended.
www.corda.com
User Guide
.....
CLUSTERING
HTTP Redirector Configuration
.H. T. .T. P. . .R. E. .D. .I .R. E. .C. .T.O. .R. . C. .O. .N. .F.I.G. .U. R. .A. .T. I.O. .N. . . . . . .
The PopChart HTTP redirectors are often an integral part of PopChart Cluster
implementations. For the most part, configuration of the redirectors is covered in greater
detail in Chapter 12, “HTTP Redirection.” However, clustering may affect the value that
you set the server address to in the initialization parameters or the configuration file.
When using the PopChart Cluster, PopChart Embedder will encode a primary and backup
PopChart Server address into the image request that it embeds in a web page. When the
redirector sees this request for an image, instead of forwarding it to the address in its
configuration settings, it first tries to contact the primary PopChart Server. If that request
fails, then it makes the request to the backup server. Only when both the primary and backup
servers fail will it try to forward the request to the address specified in its configuration
settings.
Still, it is important that you set the server address in the HTTP redirector settings properly.
If a load balancer is between the redirector and the PopChart Cluster, then the address and
port you should use for configuring the redirector is the virtual IP and port exposed by the
load balancer (see the next section for important information about load balancing and
HTTP redirection).
If there is not a load balancer, or if the redirector has direct access to the PopChart Servers
in the PopChart Cluster without going through the load balancer, then you need to configure
the redirector with the address of one of the PopChart Servers.
USING LOAD BALANCING WITH HTTP
REDIRECTION
When you use a load balancer to create a virtual IP address for your PopChart cluster and an
PopChart HTTP redirector is used between the client and the load balancer (i.e. the
redirector forwards requests to the virtual IP address) you must check the Using a
Software/Hardware Load Balancer box on the Settings > Clustering page of the
If you do not turn this on, then the redirector will try to talk to one of thePopChart Servers
on the other side of the load balancer using its real IP address. Most load balancers will not
direct communication, and thus the request will fail.
13-15
.....
PopChart
13
6(5 9(5
CLUSTERING
pcClusterMonitor Configuration
.P. C. .C. .L.U. .S. T. .E. R. . M. .O. .N. .I T. .O. .R. . C. .O. .N. F. .I.G. .U. R. .A. .T. I.O. .N. . . .
Note:
You can ignore this section if you don’t need to use a pcClusterMonitor. To find out if you
need a pcClusterMonitor, you should read through “About the pcClusterMonitor” on
page 13-3 and “Determining Your Network Architecture” on page 13-4.
Currently there are only two versions of the pcClusterMonitor. The ISAPI version and the
servlet version.
Configuring the pcClusterMonitor is very similar to configuring the HTTP redirectors. For
the most part, you should follow the steps outlined in the HTTP redirection installation
directions (refer to “Microsoft Internet Information Services” on page 12-4 or “J2EE
Web Application Servers” on page 12-10), making, of course appropriate substitutions of
files and names.
The only other significant difference in the setup process is the configuration of the
initialization parameter in the servlet, or of the configuration file in ISAPI.
In both cases, your configuration file or parameter will need to list the addresses of several
servers in the cluster. It only has to be able to contact one of these servers, as it will
download the addresses of the rest of the servers in the cluster from that server. Technically,
you only need to set one address, but this does not ensure redundancy. The addresses should
be listed in the following syntax: IP:commport,IP:commport.
ISAPI VERSION
The redirector file is located at dev_tools/isapi_cluster_monitor/pcClusterMonitor.dll.
Its configuration file is called pcClusterMonitor.cfg in that same directory.
Your pcClusterMonitor.cfg file should contain a single line listing several servers in the
cluster (e.g. 10.0.1.52:2002,10.0.1.45:2002).
SERVLET VERSION
The jar file for the redirector servlet is located at
dev_tools/isapi_cluster_monitor/pcClusterMonitor.jar.
The initialization parameter is called ClusterAddress. You should set the value of this
parameter to the list of servers in the cluster monitor (e.g.
10.0.1.52:2002,10.0.1.45:2002).
13-16
www.corda.com
T ROUBLESHOOTING PopChart Server
T
.....
...................................
14
his section contains troubleshooting tips for PopChart Builder. It is divided into the
following sections:
• Updating PopChart Server
• Known Issues
• Running PopChart Server in Debug Mode
• Installation Problems
• Setup Problems
• Administration Console Problems
• Image Generation Problems
• Network, Clustering, and HTTP Redirection Problems
• PopChart Embedder Problems
14-1
.....
PopChart
14
6(5 9(5
TR O U B L E S H O O T I N G PopChart Server
Updating PopChart Server
.U. P. .D. .A. T. .I .N. G. . .PopChart
. . . . . . . . . Server
...........................
Corda Technologies provides frequent updates to PopChart Server. These updates both
enhance existing features and resolve issues in the previous versions. Often times, your
problem can be solved simply by updating to the latest version of PopChart Server.
Note:
If you are not having any problems with PopChart Server,and you are not interested in any
of the new features of the update, you should probably not update your PopChart Server,
as updating might have unforeseen and negative consequences.
You can automatically check for updates by clicking on the Check for Updates shortcut
that was installed with PopChart Server. If you chose not to install the shortcuts, please
visit the Corda Technologies website (http://www.corda.com) regularly for the latest
patches and updates.
14-2
www.corda.com
User Guide
.....
Known Issues
.K. N. .O. .W. .N. . I. S. .S. U. . E. .S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The following is a list of known issues with PopChart Server on various platforms.
GENERAL
• If your default Java VM is version 1.4 and you view the HTML version of the
documentation, you will be unable to scroll the table of contents pane if you expand a
tree that is larger than the size of the pane.
• You will get poor results when you overlap imported images with graph objects if you
are generating a PDF or EPS image.
• In some instances, the PopChart installer will not run when your display resolution is set
to 16 colors. Change your resolution to 256 colors or higher.
• Because of a bug in Macromedia’s Flash Player, objects that stretch too far outside of
the appearance file (typically at a distance greater than 1000 pixels) cannot be displayed
correctly.
WINDOWS
• ColdFusion MX currently does not allow access to the component object model. This is
apparantly a bug in ColdFusion. Because of it, the COM version of the PopChart
Embedder will not work with ColdFusion MX. You should use the Java version
instead.
MAC OS X
• PopChart Server will quit when a user logs out, even if you have chosen a Production
install. Apple is aware of this bug, and will address it in the future.
• When you double-click on an appearance (.pcxml) file, it will launch PopChart
Builder, but PopChart Builder will not open to the file. It will, however, open to the file
if you double-click the file again. Apple is aware of this bug, and will address it in the
future.
SOLARIS
There are no know issues at this time.
14-3
.....
PopChart
14
6(5 9(5
Known Issues
LINUX
There are no known issues at this time.
14-4
www.corda.com
User Guide
.....
Running PopChart Server in Debug Mode
.R. U. .N. .N. I. N. .G. . .PopChart
. . . . . . . . .Server
. . . . . . .I .N. . D. .E. B. . U. .G. . M. . O. . D. .E. . .
When diagnosing problems with PopChart Server, it is often useful turn on debug mode.
Debug mode outputs helpful information about the images that PopChart Server is
generating, such as size and output format. Also, if you select verbose debug mode,
PopChart Server outputs every request string it receives to the console.
Debug information will be output to the Administration Console, and can be viewed by
selecting Files > View Console Output.
You can turn on debug mode by checking the Enable Debug Mode box on the Settings >
Debug page of the Administration Console. You can switch between normal and verbose
debug mode with the Normal and Verbose radio buttons.
Warning:
Request strings can be very large. Since console output is stored in a text file on
your server, running PopChart Server in debug verbose mode for an extended
period of time can create a very large console output file. Therefore, you should run
PopChart Server in debug verbose mode only for very limited periods of time.
R U N N I N G PopChart Server I N C O N S O L E M O D E
When debugging PopChart Server, it is often useful to run PopChart Server in console
mode. When in this mode, PopChart Server will run from a console, not in the background
as it usually does. You will be able to see any output from PopChart Server in its console.
To run PopChart Server in console mode, just click on the PopChart Server with
Console icon. Alternatively, you can run the bin/PopChartConsole executable.
Note:
Even if you are not running in console mode, you can still see console output by going to the
Files > View Console Output page of the Administration Console.
14-5
.....
PopChart
14
6(5 9(5
Installation Problems
.I N. . S. .T. A. .L. L. .A. .T.I.O. .N. . P. .R. .O. B. .L. .E.M. .S. . . . . . . . . . . . . . . . . . .
This section contains troubleshooting tips for problems that occur during the installation of
PopChart Server.
There are no troubleshooting tips at this time.
INSTALLATION PROGRAM DOES NOT RUN
In some instances, the PopChart installer will not run when your display resolution is set to
16 colors. Change your resolution to 256 colors or higher.
14-6
www.corda.com
User Guide
.....
Setup Problems
.S. E. .T. U. .P. . P. .R. .O. B. . L. .E. M. . S. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
This section contains troubleshooting tips for problems that occur during the setup of
PopChart Server.
LAUNCHANYWHERE ERROR: COULD NOT LOAD
jvm.dll
See “Unable to Run PopChart Server with Java 1.4 VM on Windows” on page 14-7.
U N A B L E T O R U N PopChart Server W I T H J A V A 1 . 4 V M
ON WINDOWS
On Windows, if the Java 1.4.0 VM was selected during installation, you will see the
following error message when trying to launch any PopChart program (PopChart Server,
FontConverter, and PopChart Builder).
The error message alert window reads:
******************************************************************
LaunchAnywhere Error
Can’t Launch Executable.
Could not load jvm.dll
Try re-installing the Java VM or change the Java VM used by the
application.
******************************************************************
This is a known problem with our installation software. We are currently working on a
resolution. Until then, try the following workaround.
PopChart Server points to a file called jvm.dll in the jre/bin/classic of your selected Java
installation. This directory does not exist in JRE 1.4. You can solve this problem by creating
a classic directory and copying the contents of the jre/bin/client directory into it.
D O N ’ T K N O W W H A T P O R T PopChart Server R U N S O N
By default, PopChart Server runs on port 2001.
If you have changed this port and forgotten what you changed it to, you can find this
information in the config/PCAgent.cfg file. In the [PCISStartupArgs] section of this
file, you will find a line similar to the following line:
14-7
.....
PopChart
14
6(5 9(5
Setup Problems
-port 2001
The number at the end of this line is your server port (in this case, 2001). You can change
this port by changing this number and restarting PopChart Server.
PopChart Server S E R V I C E S T O P S W H E N U S E R L O G S
OFF OF SYSTEM
To install PopChart Server as a service on Windows, you must be logged into your
computer as a user with Administrative privileges. If you were not logged in as a user with
administrative privileges when you installed the service, the PopChart Server service will
stop whenever you log off. To fix this problem, log in as the Administrator and reinstall
PopChart Server.
C A N ’ T R U N 3 . X P C I S E M B E D D E R A N D 4 . X PopChart
Embedder F O R C O M O N T H E S A M E S Y S T E M
The COM PopChart Embedder is not backwards compatible with PopChart Server 3.x.
If you need to run the 3.x PCISEmbedder and the 4.x PopChart Embedder
simultaneously on the same system, please contact our technical support staff for a solution.
14-8
www.corda.com
User Guide
.....
Administration Console Problems
.A. D. .M. .I.N. I. S. .T. R. .A. .T. I.O. .N. . C. . O. .N. .S. O. .L. .E. .P. .R. O. .B. .L. E. .M. .S. . .
This section contains troubleshooting tips for problems that occur with PopChart Server’s
UNKNOWN OR FORGOTTEN ADMINISTRATION
CONSOLE PASSWORD
When you install PopChart Server, your password defaults to password.
If you have changed your password and forgotten it, you can locate your password by
examining the contents of the config/PCAgent.cfg file. In the [PCISStartupArgs]
section of this file, you will find a line similar to the following line:
-pw password
The string that follows -pw is your password (in this case, the word password). You can
also change your password by changing this string.
14-9
.....
PopChart
14
6(5 9(5
Image Generation Problems
.I M. . A. .G. .E. . G. . E. .N. E. .R. .A. T. .I.O. .N. .P. .R. O. . B. .L. E. .M. .S. . . . . . . . . . . .
This section contains troubleshooting tips for problems that occur with image generation.
CAN’T GENERATE GIF IMAGES WITH JVM 1.4
The Pure Java AWT is automatically included with Java VMs 1.4 and higher. Because of
this, if you are using Java VM 1.4 or higher, you must disable PopChart Server’s Pure
Java AWT in the Administration Console.
For more information on the Pure Java AWT, refer to “Using the Pure Java AWT and
Custom Fonts” on page A-2
PopChart Server I S U N A B L E T O L O A D A D A T A F I L E ,
APPEARANCE FILE, SERVER COMMAND FILE,
HTML TABLE, OR DATA FROM A DATABASE
In order for PopChart Server to load or read a file or data source of any kind, it must be
given permission to read data from the specified path or domain. By default, the only
location that PopChart Server has permission to read from is anything in the document
root directory (chart_root), or anything running on the localhost.
For more information on adding access permissions, see “Setting Path Permissions” on
page 3-37.
PopChart Server P O S I T I O N S M Y G R A P H , L E G E N D ,
AND TEXT BOX OBJECTS DIFFERENTLY THAN
H O W I P O S I T I O N E D T H E M I N PopChart Builder
Since data that you send to PopChart Server can be dramatically different than the data
that was in an appearance file, PopChart Server will automatically resize objects and/or
the appearance file in order to prevent overlap. If you want to make sure that an object stays
anchored to the same place that you put it in PopChart Builder, you should use PopChart
Builder’s anchoring feature (see “Anchored Objects” on page 1-24 of the PopChart
Builder User Guide).
You can also disable automatic resizing in the actual appearance file. The following
attributes of the PopChart XML Chart element allow you to control resizing for an
appearance file: AutoResize, FitInBounds, and CollisionProtection. For
example, the following Chart element disables all of PopChart Server’s resizing
capabilities:
14-10
www.corda.com
User Guide
.....
<Chart Version=’4.0’ AutoResize=’No’ FitInBounds=’No’
CollisionProtection=’No’>
Alternatively, you can disable automatic resizing in your appearance file through PopChart
Builder. For more information, see “Dynamically Resizing the Appearance File” on
page 1-19 of the PopChart Builder User Guide.
TROUBLE DISPLAYING INTERNATIONAL
CHARACTERS IN HELVETICA, TIMES, OR
COURIER FONTS
PopChart Server supports international characters only when using the pre-installed
Lucida font set. The Times, Helvetica, and Courier font sets may support some international
characters, but there are no guarantees. If you need international character support, you
should either import custom fonts or use the Lucida fonts.
For information about custom fonts, refer to Chapter 9, “PopChart Fonts.”
CERTAIN CHARACTERS SHOW UP AS A BOX IN
PopChart Server O R PopChart Builder
Some fonts are unable to display certain characters. Helvetica, for example, is limited in the
number of characters beyond 255. Change the font that is selected for that text to another
font, such as Lucida Sans. With international characters, you may need to create a custom
font for PopChart by using the Font Converter. This will also help with double-byte
characters.
For information about custom fonts, refer to Chapter 9, “PopChart Fonts.”
I UPDATED AN APPEARANCE FILE OR IMAGE
B U T I T L O O K S L I K E PopChart Server U S E D M Y O L D
FILE
Check to see if you have enabled the appearance file cache (refer to “Appearance File
Caching” on page A-3). If you have, you either need to flush the cache or restart PopChart
Server before it will read your new appearance file.
You can flush the cache by clicking on the Clear Cache button in the Server > Home
page of the Administration Console, or by using the @_FLUSH server command. If you are
using the PopChart Embedder, you can flush the cache with the following line of code:
myPopChart.extraPCSCommands = "@_FLUSH";
14-11
.....
PopChart
14
6(5 9(5
Note:
After setting this attribute, you must call the getEmbeddingHTML() method before the
cache will flush.
NO DRILL-DOWN / POPUP / ROLL-OVER DATA
LABELS WITH GIF OR PNG IMAGES
These features are supported in GIF and PNG images via image maps. Because of this,
feedback for these features in GIF and PNG images may be slow no matter how you embed
your PopChart images. You will be unable to customize the appearance of your rollover data
labels and PopUp text. In Netscape browsers, you may be unable to get PopUp text
without also enabling a drill-down effect for the specified data item.
In the past, the JavaScript PopChart Embedder has not supported these features. The
4.0.5 version of the JavaScript PopChart Embedder supports drill-down, PopUp, and
roll-over data labels. Make sure that you have upgraded to it.
If you are using the HTTP Request method, you will be unable to use any of these features.
UNABLE TO OUTPUT HTML DATA TABLES
HTML data table output is only supported in PopChart Server Enterprise.
HTML data table output is not supported in the JavaScript PopChart Embedder or using
the HTTP request method.
UNABLE TO LOAD FILES FROM ABSOLUTE
PATHS ON UNIX COMPATIBLE SYSTEMS
In order to load appearance, PCXML, or data files from absolute paths on UNIX systems,
you must place an extra slash in front of the path. For example, to load the file
/home/mydirectory/myfile.txt, you would have to specify
//home/mydirectory/myfile.txt as the file name.
This applies to PopChart Embedder methods and attributes (e.g. loadData(),
appearanceFile) as well as PCScript and server commands (e.g. @_FILE,
@_LOADREQUEST, graph.LoadFile())
SLOW GENERATION TIME OR LARGE FILE SIZE
WHEN IMPORTING JPEG IMAGES
JPEG images do not import well into PopChart XML 4.0. You will need to save your
appearance files in PopChart XML 4.0.1 format to take full advantages of imported JPEG
14-12
www.corda.com
User Guide
.....
images. To do this, go into PopChart Builder, select Edit > Preferences > Save and
check the Save Using Latest PCXML Format box. You must be running both
PopChart Server 4.0.1 and PopChart Builder 4.0.1 for this to work.
14-13
.....
PopChart
14
6(5 9(5
Network, Clustering, and HTTP Redirection Problems
NETWORK, CLUSTERING, AND HTTP
REDIRECTION PROBLEMS
..................................................
This section contains troubleshooting tips for network, clustering, and HTTP redirection
problems.
I CHANGED THE ISAPI REDIRECTOR
CONFIGURATION FILES, BUT THE CHANGES
HAVEN’T BEEN APPLIED
If you change the popchart.cfg file after you have already attempted to use the redirector,
you will need to restart IIS so that it can update the settings.
14-14
www.corda.com
User Guide
.....
PopChart Embedder Problems
.PopChart
. . . . . . . . .Embedder
. . . . . . . . . . P. .R. .O. B. .L. .E. M. .S. . . . . . . . . . . . . . . . . .
This section contains troubleshooting tips for problems that occur when using the
PopChart Embedder.
HAVING TROUBLE FIGURING WHAT VALUES TO
A S S I G N externalServerAddress A N D
internalCommPortAddress
For more information, refer to the section entitled “Setting the Server Information” on
page 4-9.
MICROSOFT VBSCRIPT COMPILATION:
EXPECTED END OF STATEMENT
This problem occurs when you accidentally use a semi-colon at the end of a line in
VBScript. You may run into this problem when using the COM PopChart Embedder with
Active Server Pages (ASPs).
Active Server Pages use VBScript, whose syntax requires that you do not have a semi-colon
at the end of a line of code. Since other languages either require a semi-colon, or are
indifferent, most of the example code in this documentation uses a semi-colon at the end of
each line of code. You should be careful to remove any semi-colons from example code if
you use it in an ASP.
For example, this line of code is invalid in an ASP:
MICROSOFT VBSCRIPT COMPILATION: CANNOT
USE PARENTHESES WHEN CALLING A SUB
This problem occurs when you accidentally use incorrect VBScript syntax for a method that
does not return a value. You may run into this problem when using the COM PopChart
Embedder with Active Server Pages (ASPs).
VBScript syntax requires any functions that do not return a value (void methods) to not
have parenthesis around the parameters.
14-15
.....
PopChart
14
6(5 9(5
For example, we show the addHTMLTable syntax to be:
myPopChart.addHTMLTable("graph","title");
This is perfectly valid in every language except VBScript. So in ASPs, you would need to
use the following syntax:
myPopChart.addHTMLTable "graph", "title"
For most ASP developers this will be a very obvious conversion process.
A METHOD OR ATTRIBUTE DOES NOT WORK IN
JAVASCRIPT
For more information, refer to the section entitled “JavaScript Embedder limitations” on
page 5-6.
PROBLEMS EMBEDDING SVG IMAGES WITH
J A V A S C R I P T PopChart Embedder
Due to the nature of JavaScript, the JavaScript PopChart Embedder is subject to the 256
character URL length limitation when displaying SVG images (refer to “Overcoming the
URL Length Restriction” on page 11-16). To workaround this problem, try importing your
data from a data file or using a server-side command or PCXML file.
PROBLEMS EMBEDDING ANY IMAGES WHEN
USING A LARGE AMOUNT OF PCSCRIPT WITH
T H E J A V A S C R I P T PopChart Embedder
Due to the nature of JavaScript, the JavaScript PopChart Embedder is subject to the 2000
character URL length limitation (refer to “Overcoming the URL Length Restriction” on
page 11-16). To workaround this problem, try importing your data from a data file or using a
server-side command or PCXML file.
JAVASCRIPT ERROR: ‘POPCHARTEMBEDDER’ IS
UNDEFINED
PopChart Server has either not been started, or is not running correctly. Please restart
PopChart Server.
14-16
www.corda.com
User Guide
.....
UNABLE TO LOAD FILES FROM ABSOLUTE
PATHS ON UNIX COMPATIBLE SYSTEMS
In order to load appearance, PCXML, or data files from absolute paths on UNIX systems,
you must place an extra slash in fromt of the path. For example, to load the file
/home/mydirectory/myfile.txt, you would have to specify
//home/mydirectory/myfile.txt as the file name.
This applies to PopChart Embedder methods and attributes (e.g. loadData(),
appearanceFile) as well as PCScript and server commands (e.g. @_FILE,
@_LOADREQUEST, graph.LoadFile())
C O M PopChart Embedder D O E S N O T W O R K W I T H
ColdFusion MX
ColdFusion MX currently does not allow access to the component object model. This is
apparantly a bug in ColdFusion. Because of it, the COM version of the PopChart
Embedder will not work with ColdFusion MX. You should use the Java version instead.
14-17
.....
PopChart
14
14-18
6(5 9(5
www.corda.com
I MPROVING P ERFORMANCE
.....
...................................
T
A
his appendix contains information about settings that affect PopChart Server
performance. The suggestions in this appendix may or may not increase the performance of
PopChart Server—the results will usually depend on your operating environment.
The topics covered in this chapter include:
• Using the Pure Java AWT and Custom Fonts
• Caching
• Increasing or Decreasing the Maximum Number of Connections
• Embedder Session Cache
• Changing Which Java VM PopChart Server Uses
• Increasing Efficiency by Saving and Loading Images
A-1
.....
PopChart
A
6(5 9(5
IMPROVING PERFORMANCE
Using the Pure Java AWT and Custom Fonts
USING THE PURE JAVA AWT AND
CUSTOM FONTS
..................................................
To enable GIF and PNG output on UNIX systems, PopChart 4.0.5 takes advantage of the
Pure Java AWT. This allows GIF/PNG images to be generated on UNIX compatible
systems without the need for installing Xvfb (virtual frame buffer) or XWindows. It also
increases performance by up to 10% over Xvfb and XWindows. However, if you are
serving GIF or PNG images, it requires more RAM (at least 128 Megs for lighter loads, 256
Megs for heavy loads).
You change the amount of RAM that is allocated to PopChart Server in the
Administration Console by going to the Settings > Memory page.
By default, PJA is enabled on UNIX platforms and disabled on Windows platforms. You
can change this setting at the bottom of the Settings > Image Type page of the
Administration Console. You can also control this setting with the -pjafont and -pjawt
configuration settings.
If you would like to achieve Windows-like results with fonts, you can also select Use
Corda Font Set from the Settings > Image Type page of the Administration
Console.
Note:
A-2
PJA is automatically included with Java VMs 1.4 and higher. Because of this, if you are
using Java VM 1.4 or higher, you must disable PopChart Server’s Pure Java AWT in the
www.corda.com
User Guide
.....
Caching
.C. A. .C. .H. I. N. .G. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
You can enable caching in the Settings > Cache / Connections section of the
Administration Console. Simply enter the desired cache size (in images) in the Cache
Size box.
When caching is enabled, PopChart Server stores the server request string and the
generated image in a cache. When the same request is received, PopChart Server sends
back the previously generated image. This is very fast as it doesn’t require disk access or
regeneration of the image.
Even if there is a possibility of thousands of different variations on a certain graph, it is
useful to have a cache size of around 100 to 1000 images if there is a likelihood that certain
graphs will be viewed more frequently than others.
If you load data from a file with either the PopChart Embedder or PCScript while caching
is enabled, PopChart Embedder will check the timestamp of the file that it loads. If the
timestamp hasn’t changed, the cached image will be used. Otherwise, a new image with the
updated data will be generated.
The cache size can be as large as you desire. However, keep in mind that the cache uses
RAM and not disk space. Cache sizes of 100 to 1000 images are typical.
When the cache reaches its maximum capacity, the oldest image will be bumped out.
If the data being graphed is never, or rarely the same, using the cache is not recommended.
You can disable the cache by setting Cache Size to 0. You can also specify that a certain
image is not to be cached by using either the useCache PopChart Embedder attribute,
or the @_DONTCACHE server command (this also instructs the browser not to cache the
image).
APPEARANCE FILE CACHING
A new feature in PopChart Server 4.0.5 is appearance file caching. When this is enabled,
PopChart Server will store the most recently accessed appearance files in RAM. If you
use the same appearance files often, this will help cut down on disk-access times. However,
it requires more RAM.
To enable the appearance file cache, check the Enable Appearance File Caching box
on the Settings > Cache / Connections page in the Administration Console.
Note:
Use this setting carefully. After PopChart Server caches an appearance file, it will never
load it again, even if there is a newer version available.For more information, refer to the
section entitled “I Updated an Appearance File or Image but it Looks Like PopChart
Server Used my Old File” on page 14-11.
A-3
.....
PopChart
A
6(5 9(5
Increasing or Decreasing the Maximum Number of Connections
INCREASING OR DECREASING THE
MAXIMUM NUMBER OF CONNECTIONS
..................................................
Like any server, PopChart Server can only accept a certain number of client connections
at any given moment. When the number of connected clients has reached a maximum value,
it starts placing client requests in a queue, and responds to them as soon as another
connection becomes available. Most of the time you don’t notice this behavior because
PopChart Server rarely spends more than 50 milliseconds dealing with a client request.
In some cases, you may find that you want to increase the maximum number of connections
so that clients spend less time waiting in PopChart Server’s queue. In other cases, if the
responsiveness of your site is decreasing, you may actually benefit from decreasing the
maximum number of connections. The reason for this is PopChart Server will spend less
time managing connections and more time generating images.
You can change the maximum number of connections in the Settings > Cache /
Connections section of the Administration Console. Simply enter the desired value in the
Maximum Connections box.
The default setting allows PopChart Server to accept an unlimited number of connections.
You should tweak with this setting only if you are experiencing performance problems. We
suggest you start by allowing 25 connections, and then raise or lower this number until you
see the best performance results.
A-4
www.corda.com
User Guide
.....
Embedder Session Cache
.E. M. . B. .E. D. . D. .E. R. . .S. .E. S. .S. I. O. .N. . C. . A. .C. .H. E. . . . . . . . . . . . . . . . .
The embedder session cache stores data and other information that the PopChart
Embedder sends over the comm port. By storing this information in the key cache,
PopChart Server is able to return a PopChart image to a browser more quickly when it is
requested.
The information will remain in the embedder session cache for a certain period of time,
known as its session time, after it is stored. The implications of this behavior are: 1) the
information will disappear after a certain time even if it is not requested, and 2) if the
information is requested multiple times during this period, each request will be sped up by
using the embedder session cache. By default the session time is twenty minutes.
PopChart Server sets aside a certain amount of RAM for the embedder session cache. By
default, the cache will use ten megabytes of RAM. If the embedder session cache ever
grows beyond this size, it will begin using disk space to store the embedder session cache.
Older objects will be moved from RAM to disk to make room for newer objects. By default,
the embedder session cache is located in the cache_root/keycache directory.
You can change embedder session cache settings in the Administration Console on the
Settings > Embedder Session page.
The exact effects of changing the embedder session cache are hard to predict, and will vary
greatly depending on server load and system specifications. However, changes generally
will not have a significant effect on PopChart Server performance.
CIRCUMVENTING THE EMBEDDER SESSION
CACHE
PopChart Server uses an embedder session cache to store information (such as data and
appearance files) about each image that the PopChart Embedder embeds into a web page
By default, PopChart Embedder only embeds an embedder session ID within the actual
web page. When a browser requests an image with this ID, PopChart Server looks up this
ID in the embedder session cache and retrieves the appropriate information.
Note:
The JavaScript PopChart Embedder does not use the embedder session cache. It will
always make a full request.
For example, the code below shows how PopChart Embedder would typically embed a
GIF image. @_CPRBB_Phjd_gBSy is the embedder session ID.
<img src="http://popchart.mycompany.com:2001/?@_CPRBB_
Phjd_gBSy@_GIF>
Alternatively, PopChart Embedder can embed all of the information about a PopChart
within the actual web page. In other words, the web page contains the full request for the
PopChart image. In this case, the same embedded image might look something like this:
A-5
.....
PopChart
A
6(5 9(5
Embedder Session Cache
<img src="http://popchart.mycompany.com:2001/?@_FILEap
files/bar.pcxml@_PCSCRIPTgraph.setcategories(Red;Yel
low;Green)graph.setSeries(Line1;35;65;12)@_GIF">
Note:
If you are passing a lot of data in PCScript, this request can grow to be quite large.
The advantages of having PopChart Embedder use the embedder session cache are twofold: 1) it decreases the size of your web pages; 2) it circumvents issues that certain
browsers and image formats have with long URLs (refer to “Overcoming the URL Length
Restriction” on page 11-16).
However, in some circumstances—for example, when you are using the PopChart
Embedder to generate static web pages that will be accessed after the embedder session
time has expired—it may be desirable not to use the embedder session cache. If this is the
case, you can disable the embedder session cache by setting the PopChart Embedder
makeFullRequest attribute to true, as illustrated below:
myPopChart.makeFullRequest = true;
You can also instruct PopChart Embedder to use the embedder session cache only when
the full request would be longer than a certain URL length (thus circumventing the URL
length restriction). To do this, set makeFullRequest to true and then set the
maxRequestLength attribute to the maximum request length. For example, to have
PopChart Embedder use the embedder session cache for any images where the full
request would be longer than 2000 characters, you would use the following lines of code:
myPopChart.makeFullRequest = true;
myPopChart.maxRequestLen = 2000;
A-6
www.corda.com
User Guide
.....
Changing Which Java VM PopChart Server Uses
C H A N G I N G W H I C H J A V A V M PopChart Server
USES
..................................................
PopChart Server requires Java VM 1.2.2 or higher. We strongly recommend a 1.3.1 VM if
you will be using PopChart Builder. You may find, however, that you achieve better
performance with a different Java VM.
Warning:
We currently do not support Java VM version 1.4. You may still be able to get it
working, though (see “Unable to Run PopChart Server with Java 1.4 VM on
Windows” on page 14-7 and “Can’t Generate GIF Images with JVM 1.4” on
page 14-10).
To change the Java VM that PopChart Server uses, locate the bin/PopChart.lax file.
Inside of this file you will find a line similar to the following:
lax.nl.current.vm=C:\\Program
Files\\JavaSoft\\JRE\\1.3.0_01\\bin\\java.exe
You should change the lax.nl.current.vm variable to point to the Java VM that you
want to use.
Important:
Because the .lax file uses the backslash as an escape key, you should be sure to use double
backslashes for file paths.
If you need to change the Java VM for Font Converter, PopChart Builder, or PopChart
Server Console Mode, you can do this by following a similar process with the
FontConverter.lax, PopChartBuilder.lax, and PopChartConsole.lax files respectively.
If you are using the UNIX script (pca.sh), you can change the Java VM that PopChart
Server uses by modifying the JAVA_HOME variable in the config/pcs.settings file to
point to the root directory of the Java VM that you want to use (not the bin or jre subfolder).
A-7
.....
PopChart
A
6(5 9(5
Increasing Efficiency by Saving and Loading Images
INCREASING EFFICIENCY BY SAVING
AND LOADING IMAGES
..................................................
If you have a commonly viewed graph that doesn’t change very often, you can decrease the
CPU load by having PopChart Server save the image to disk every time the data changes.
Any time you want to show the image, you can have PopChart Server retrieve the saved
image instead of re-generating it for every request.
If you are using the PopChart Embedder, you can save an image using the
saveImageToPopChartServer(String) method. For example, Example A.1
embeds a PopChart image using the JavaScript PopChart Embedder. It also saves the
image that PopChart Server returns to the location image/180091.swf.
Note:
Example A.1
You can only save to locations that have save permissions in your path.xml file. For more
information, refer to “Setting Path Permissions” on page 3-37. You must also specify a
password to save images. You can do this with the password PopChart Embedder
attribute.
Saving an Image to PopChart Server
myPopChart.appearanceFile = "examples/apfiles/line.pcxml";
myPopChart.saveImageToPopChartServer("images/180102.swf");
You could then load the image with the PopChart Embedder
loadServerSideImage(String) method. For example, Example A.2 loads the
image from Example A.1 and embeds it into in a web page.
Example A.2
Loading a Server-Side Image
myPopChart.loadServerSideImage("images/180102.swf");
Note:
When you load a server-side, any PopChart Embedder attributes and methods that have
to do with dynamic content generation (e.g. appearanceFile, loadData()) will be
ignored.
You can also use the @_SAVE and @_LOAD server commands to save and retrieve images.
With these, you should specify a password using @_PW.
A-8
www.corda.com
User Guide
.....
Important:
This strategy is only effective when you know that your users will be viewing images in the
same format. Be sure that the imageType attribute for the image that you load and the
imageType attribute for the image that you save are the same. You may need to make sure
that fallback is disabled. Likewise, you will probably want to disable Automatic PNG
Detection (refer to “Automatic PNG Detection” on page 3-27), unless you are sure all
clients will support PNG.
A-9
.....
PopChart
A
A-10
6(5 9(5
www.corda.com
U SING T HE P OP C HART W EB S ERVER C ONTROL
T
.....
...................................
B
his appendix discusses the use of the PopChart Web Server Control. This utility is
provided to showcase one of the many creative ways in which you can use the .NET version
of the PopChart Embedder with Microsoft Visual Studio®.NET. It is not intended to be
the standard method for deploying PopCharts in the .NET environment. Rather, it is hoped
that developers will be able to learn from it how to develop their own control, customized
for the particular needs of their environment.
Note:
The PopChart Web Server Control is different than the .NET Embedder. Developers looking
simply for the .NET equivalent of the PopChart Embedder should refer to “ASP.NET” on
page 5-27.
The PopChart Web Server Control is designed to be a standalone application. It is designed
so that most people who use it will be able to do so without having ever read any other piece
of PopChart documentation, besides this chapter.
While the web server control itself offers only basic PopChart functionality, advanced users
will find it easy to extend that functionality by using pre-defined appearance files and the
.NET version of the PopChart Embedder.
This chapter is divided into the following topics:
• About the PopChart Web Server Control
• Installing the Web Server Control
• Creating a PopChart-Enabled Web Application
• Customizing Your PopChart
• Connecting to a Database
• Advanced Customization with PopChart Embedder.NET
Important:
This section assumes you are at least somewhat familiar with Microsoft Visual Studio
.NET. While some users may be able to get by without having used .NET before, it is
strongly recommended that you familiarize yourself with it before continuing.
B-1
.....
PopChart
B
6(5 9(5
U S I N G T H E P O P C H A R T WE B S E R V E R C O N T R O L
About the PopChart Web Server Control
ABOUT THE POPCHART WEB SERVER
CONTROL
..................................................
The PopChart Web Server Control brings web services functionality to data visualization.
Using the Microsoft’s .NET studio, you can easily place PopChart images into your web
pages, without writing a single line of code. You can also create and customize graphs
without the use of PopChart Builder.
To simplify the learning process for beginners, the web server control by default interacts
with Corda Technologies's .NET Web Services server (http://pcws.popchart.com),
which is currently free for developmental use. However, to prevent abuse of this server, it
offers limited functionality.
It is expected that after users become acquainted with the PopChart Web Server Control,
they will modify their settings so that the control interacts with their own PopChart Server
instead. Instructions for doing this can be found in “Changing the Server Location” on
page B-19.
EXTENDING THE WEB SERVER CONTROL
The PopChart Web Server Control is essentially an extension of the .NET PopChart
Embedder. The source code for the web server control is included with the PopChart
installation in the dev_tools/dotnet_embedder/control_source folder. We highly
encourage users who want more functionality in the web server control to extend or rewrite
the web server control as desired.
B-2
www.corda.com
User Guide
.....
Installing the Web Server Control
.I N. . S. .T. A. .L. L. .I.N. G. . .T. H. . E. . W
. . .E. B. . .S. E. .R. .V. E. .R. . C. .O. .N. T. .R. .O. L. .
Installing the PopChart Web Server Control allows you to place a PopChart a PopChart
image on your web page as easily as you would a table or any other web server control. A
PopChart control that you can drag and drop into any web application will be placed in your
toolbox.
T o in s t al l th e P op C h a rt W eb S e rv e r C o n tr ol
1
If necessary, copy the PopChartWebCtl.dll and PCNetEmbedder.dll files to some
location on your machine.
These files are located in the dev_tools/dotnet_embedder folder of your PopChart
installation. Be sure to keep these files in the same location.
2
Start Microsoft Visual Studio.NET.
B-3
.....
PopChart
B
6(5 9(5
3
Select Tools > Customize Toolbox (or open the ToolBox, right click and choose
Customize ToolBox).
4
B-4
Select the .Net Framework Components tab.
www.corda.com
User Guide
.....
5
Using the Browse... button, browse to and select the PopChartWebCtl.dll file.
B-5
.....
PopChart
B
6(5 9(5
6
The PopChart component should be listed in the list of components. Make sure that it
is checked and click OK to continue.
7
You should now have a PopChart object listed in the General tab of your ToolBox (You
can move it to a different tab, such as Web Forms, if you want).
B-6
www.corda.com
User Guide
.....
Creating a PopChart-Enabled Web Application
CREATING A POPCHART-ENABLED WEB
APPLICATION
..................................................
Note:
1
2
The first 4 steps are directions for creating a web application. If you already know how to
create a web application, do so and skip to Step 4.
Create a new project by selecting File > New > Project.
Select Visual C# (or Visual Basic, if you’d prefer to use that language) from the Project
Types list.
3
Under the Templates list, select the icon for the ASP.NET Web Application template.
If you do not see this icon, make sure that you have Visual C# (or Visual Basic)
selected under Project Types.
B-7
.....
PopChart
B
6(5 9(5
4
Assign your web application to an appropriate location by entering it into the Location
box.
For this example, we will use http://localhost/MyPopChart.
5
If your toolbox is not already open, open it by clicking on the Toolbox
icon or
selecting View > Toolbox.
6
From the General tab in your toolbox (or another tab if you have moved it) drag the
PopChart web server control onto your web form.
B-8
www.corda.com
User Guide
.....
7
Connect your PopChart to your data.
To learn how to connect your PopChart to data, refer to “Connecting to a Database”
on page B-20.
8
Customize your PopChart image accordingly.
To learn about how you can customize your PopChart image, refer to “Customizing
Your PopChart” on page B-11.
9
10
Save your web application by selecting File > Save All.
Compile your web application by selecting Build > Build MyPopChart (where
MyPopChart is the name of your web application).
The web application should compile without error.
11
You can preview your web application, with the PopChart in it, by viewing the
WebForm1.aspx file in the location you specified in step 3.
This assumes that you placed your PopChart into the WebForm1.aspx web form,
which is the default form that Visual Studio.NET creates for you. If you inserted your
PopChart into a different web form, you should use the name of that web form instead.
B-9
.....
PopChart
B
6(5 9(5
In this example, the location is http://localhost/MyPopChart/WebForm1.aspx.
B-10
www.corda.com
User Guide
.....
.C. U. .S. .T.O. .M. .I .Z. I.N. .G. . Y. .O. .U. R. . .P. .O. P. .C. .H. A. .R. .T. . . . . . . . . . . .
Using the Properties menu in the Visual Studio.NET interface, you can customize many
aspects of the PopChart web server control, including:
• Specifying a Title
• Adding a Legend
• Changing the Background Color
• Changing the Border
• Changing the Graph Type
• Changing the Graph Color Theme
• Changing the Image Type and Size
• Adding Descriptive Text
• Loading Data
• Using a Pre-defined Appearance File
• Changing the Server Location
Note:
As you customize your graph, you may notice that some of your changes aren’t appearing in
the Visual Studio.NET user interface. However, your customizations will still appear if you
preview your web page.
To learn how to access the Properties menu, read the following instructions.
T o a c ce s s t h e P o p C ha r t P ro p e r ti es me n u
1
Select your PopChart image by clicking on it.
If you have changed the image type to FLASH or SVG, you may have difficulty
selecting the image by clicking on it. Instead, you can use the TAB button to tab through
the different components on your web page until the image is selected. You can also use
the pull-down menu at the top of the Properties menu to switch between objects.
B-11
.....
PopChart
B
6(5 9(5
2
Bring up the Properties window (if it is not already visible) by selecting View >
Properties Window.
Note that the properties are divided into the following groups: Appearance, Behavior,
Data, Image Server, Layout, and Misc.
To edit any property, simply click on the box to the right of the property you want to change
and start typing. Some properties (such as ImageType) have a limited range of values, and
clicking on these will bring up a pull-down menu from which you can choose a pre-defined
value.
B-12
www.corda.com
User Guide
.....
SPECIFYING A TITLE
One of the first things you will want to do is give your graph a title. To do this, simply locate
the Title property (in the Appearance group) and type in the title of your graph.
B-13
.....
PopChart
B
6(5 9(5
ADDING A LEGEND
To add a legend to your graph, simply select one of the following values for the Legend
property (in the Appearance group): Right or Bottom.
If you have a pre-defined appearance file that already contains a legend, but you want to
remove the legend, select None. If you want the legend to stay in the same location as in
the appearance file, select USE_APPEARANCE_FILE.
CHANGING THE BACKGROUND COLOR
To change the background color, simply select a different color for the BackColor
property (in the Appearance group). Clicking on this property will bring up a color menu
from which you can pick a pre-defined color, or select your own custom color.
Note:
Selecting Transparent will preserve the default value from a pre-defined appearance file, if
you are using one.
You can also specify a gradient for your background color. A background gradient begins
with one color (an the top or to the left) and then progressively shifts to another color (at the
bottom or to the right).
B-14
www.corda.com
User Guide
.....
To enable a background gradient, simply choose one of the following values for the
BackGradientDir property (in the Appearance group): LeftToRight or
TopToBottom. This specifies the direction of your gradient.
The background gradient will begin at the top or left of the graph with the color you choose
for the BackColor property. It will end with the color specified in the
BackGradientColor property, which you can change by clicking on and selecting a new
color from the color menu.
CHANGING THE BORDER
You can change several aspects of the border around your PopChart image. First of all, you
can change the border type by selecting one of the following values for the BorderType
property (in the Appearance group): None, Thin, Medium, Thick, DoubleThin,
ThickThin, and ThinThick. Selecting None will remove the border. Selecting
USE_APPEARANCE_FILE will preserve the setting from a pre-defined appearance
file, if you are using one.
You can change the border color by selecting a different value for the BorderColor
property (in the Appearance group). Clicking on this property will bring up a color menu
from which you can pick a pre-defined color, or select your own custom color.
B-15
.....
PopChart
B
6(5 9(5
CHANGING THE GRAPH TYPE
PopChart supports a wide variety of graph types. When you first create a PopChart web
server control, your graph will be a vertical bar graph. By changing the value of the
GraphType property, however, you can create any of the following graph types: Vertical
Bar, Vertical Stacked Bar, Horizontal Bar, Horizontal Stacked Bar, Pie, Line,
Line Bar Combo, XY Line, Stock, Radar, and Pareto.
Note:
For more information about the various graph types, including what kind of data they
support, refer to in Chapter 13, “Graph Types,” of the PopChart Server Reference
manual.
If you are using a pre-defined appearance file, and want to preserve the graph type from the
pre-defined appearance file, you must select USE_APPEARANCE_FILE as the value
of GraphType.
CHANGING THE GRAPH COLOR THEME
You can change the colors that your graph uses by modifying its color theme. To change the
color theme, select one of the following values for the ColorTheme property (in the
Appearance group): None, Default, Standard16, Pastel, Southwest, EverGlades,
Ocean, Subdued, Translucent. None will preserve your settings from a pre-defined
appearance file.
B-16
www.corda.com
User Guide
.....
CHANGING THE IMAGE TYPE AND SIZE
Your PopChart image can be in any of the following formats: FLASH, GIF, SVG, and PDF.
To change the image format, simply select the desired format as the value of the
ImageType property (in the Appearance group).
To learn more about image formats, refer to Chapter 14, “Image Formats,” of the
To change the image size, select one of the corners of the PopChart and drag it in or out,
until the image is the desired size.
ADDING DESCRIPTIVE TEXT
PopChart Server can generate a 508 compliant text description of your graph for the
visually impaired. All you have to do is change the value of the DLinkText attribute to
True.
Note:
If you’re having trouble getting the d link to appear in the right location, you can place the
PopChart image inside of a Panel component, which can be found under the HTML tab in
your Toolbox.
To learn more about descriptive text, refer to Chapter 8, “Displaying 508 Compliant
Descriptive Text.”
LOADING DATA
You can load data to your PopChart Web Server Control in one of the following three ways:
from a Data File, from PCXML, and with PCScript.
Important:
You can only load data from a data file or PCXML if you are retrieving images from your
own PopChart Server. Corda Technologies’ free web services server
(http://pcws.popchart.com), which is the default server for the PopChart Web Server
Control, does not support this functionality. Refer to “Changing the Server Location” on
page B-19 to learn how to make the PopChart Web Server Control use your PopChart
Server.
DATA FILE
You can load data from one of the following file formats: a comma .csv file, a tab-delimited
data file, or an XML data file. You can learn about these formats from “Data Formats that
PopChart Server Imports” on page 6-16.
To load a data file, simply specify the location of your data in the DataFile property of the
Data group. The data source can be located at a location relative to PopChart Server, or
from a URL.
B-17
.....
PopChart
B
6(5 9(5
Note:
You may need to change security permissions so that PopChart Server is allowed to access
your file. For more information, refer to the section entitled “Setting Path Permissions”
on page 3-37.
PCXML
You can also load data from a PCXML data source. You can learn about this format from
“PopChart XML Data Format” on page 6-5.
To load a PCXML file, simply specify the location of your data file in the PCXMLData
property of the Data group. The data file can be located at a location relative to PopChart
Server, or from a URL.
Note:
your file. For more information, refer to the section entitled “Setting Path Permissions”
on page 3-37.
PCSCRIPT
For those familiar with PCScript, you can specify data and other formatting options in
PCScript by changing the value of the PCScript property. PCScript is discussed in detail in
Chapter 5, “PCScript,” of the PopChart Server Reference manual.
USING A PRE-DEFINED APPEARANCE FILE
The PopChart Web Server Control allows you take advantage of only a limited set of
PopChart features. This is to keep it from becoming too complicated for simple use.
However, by using pre-defined appearance files, created by PopChart Builder, you can
take advantage of many advanced layout and appearance features not available in the web
server control.
Important:
You can only use pre-defined appearance files if you are retrieving images from your own
PopChart Server. Corda Technologies’ free web services server
(http://pcws.popchart.com), which is the default server for the PopChart Web Server
Control, does not support this functionality. Refer to “Changing the Server Location” on
page B-19 to learn how to make the PopChart Web Server Control use your PopChart
Server.
To use a pre-defined appearance file, first type in the location of your appearance file as the
value of the Apfile property (in the Appearance group). This location should be either a
URL, or a location relative to PopChart Server.
Note:
your appearance file. For more information, refer to the section entitled “Setting Path
Permissions” on page 3-37.
When you use a pre-defined appearance file, any web server control properties you define
will override the settings from the appearance file. If you want to preserve the settings from
B-18
www.corda.com
User Guide
.....
the appearance file, most settings allow you to select a USE_APPEARANCE_FILE
value. For colors, select Transparent if you want to preserve the appearance file setting.
CHANGING THE SERVER LOCATION
By default, the PopChart Web Server Control retrieves images from Corda Technologies’s
.NET Web Services server (http://pcws.popchart.com), which is currently free for
developmental use.
Warning:
Abuse of this service may require us to change this policy.
To retrieve images from your own server, simply change the Addr and CommAddr
properties in the Image Server group to reflect the location of your server.
The Addr property should be changed to the location of PopChart Server’s main port (i.e.
the external server address, usually something like 10.0.0.1:2001), while the CommAddr
property should be changed to reflect the location of PopChart Server’s comm port (i.e.
the internal comm port address, usually something like 10.0.0.1:2002).
To learn how to figure out what the values of these properties should be, refer to “Setting
the Server Information” on page 4-9.
Note:
Alternatively, you can customize the PopChart Web Server Control so that it always uses
your PopChart Server. To do this, you will need to modify the source code (included in the
dev_tools/dotnet_embedder/control_source folder) and rebuild it with Visual
Studio.NET.
B-19
.....
PopChart
B
6(5 9(5
Connecting to a Database
.C. O. . N. .N. .E. C. .T. I. N. .G. . T. .O. . .A. . D. .A. .T.A. .B. A. .S. .E. . . . . . . . . . . . . .
You can also load data to your PopChart Web Server Control directly from a database.
Your PopChart can be bound to any dataSet, dataTable, or dataView object in your
web form. For instructions on creating a data set, data table, and/or data view, you should
refer to your Visual Studio .NET documentation.
You connect the PopChart Web Server Control to data the same way that you connect a Data
Grid web server control to data (the web server control actually derives from
System.Web.UI.WebControls.DataGrid). Search your .NET documentation for
instructions on using the DataGrid object if the following instructions are insufficient.
After setting up your data, you will need to modify your PopChart’s DataSource property
(in the Data group). Select the appropriate data object from the DataSource pull-down
menu.
Once you’ve selected a DataSource for your PopChart Web Server Control, be sure to fill
in the dataSet and bind the dataSet to your web control. You can do this by calling the
Fill method on your data adapter object, and then calling the DataBind method on your
B-20
www.corda.com
User Guide
.....
Connecting to a Database
PopChart web server control. This will all need to be done in your ASP.NET page’s class
file.
So, for example, if your data adapter were named OleDbDataAdapter, your data set
named DataSet1, and your PopChart web server control named PopChart1, you would
need to add the following code under the Page_Load section in the class file:
Example B.3
Filling in the Data Set and Binding the Data
{
OleDbDataAdapter1.Fill(DataSet1);
PopChart1.DataBind();
}
CODING DATA CONNECTIVITY
Experienced programmers might find it easier to simply code in their data source. The
following example code shows one way you could load data into your PopChart using C#
code. It assumes your PopChart web server control has been named PopChart1 (the default
name). All of the code is placed inside of the Page_Load method for your web form.
Note:
Example B.4
This code loads data from an XML data source.
Data Connectivity with the PopChartServerControl
{
// To load the graph from an XML Document
DataSet ds = new DataSet();
ds.ReadXml("..\\..\\sales.xml", XmlReadMode.Auto);
PopChart1.DataSource = ds;
PopChart1.DataMember = "";
PopChart1.DataKeyField = "";
PopChart1.DataBind();
}
B-21
.....
PopChart
B
6(5 9(5
Advanced Customization with PopChart Embedder.NET
ADVANCED CUSTOMIZATION WITH
PopChart Embedder. N E T
..................................................
If you’re the adventorous type, you can make advanced customizations to your PopChart
image by accessing the embedder member of the PopChart Web Server Control. the
embedder member is an instance of the PopChart Embedder object that the Web Server
Control uses to embed your PopChart image.
You change embedder attributes and call embedder methods just as you would any
PopChart Embedder object. Any changes you make will be applied after customizations
that you make using the Web Server Control.
Note:
You will only be able to see your customizations to the PopChart Embedder when you
preview the web page.
For example, suppose you want to take advantage of PopChart Embedder’s
loadData() method. Assuming that the id of your Web Server Control is PopChart1
(the default value), you could access this method with the following code inside of your
class file’s Page_Load method.
Example B.5
Accessing the Web Server Control’s embedder member
{
PopChart1.embedder.loadData("graph","examples/data/data1.csv");
}
Note:
You do not need to call getEmbeddingHTML(), as the PopChart Web Server Control
does that for you.
For instructions on how to use the PopChart Embedder, refer to Chapter 4, “Embedding
PopChart Images in a Web Page.” For a complete reference of PopChart Embedder
attributes and methods, refer to Chapter 4 of the PopChart Server Reference manual.
B-22
www.corda.com

PopChart Server User Guide

Transcription

Similar documents

Mise en page 1

© www.jbonzer.com Graphics DJ Inkers

Standard Console 425-6012

JULIAN - Armani/Casa

An Italian tile made in the USA

horsing - Le Bocage Normand

UltraVu® II 5330

Meryl Natchez, CEO, TechProse

Untitled - Content admin

Free Graphics and Image Editing Tools