PCScript

PopChart Server Reference 4.0.5

AddNote

Syntax graph.AddNote(Category, Series, Text, [Textbox] [;Category, Series, Text, [Textbox]]*)

Description Adds a PopChart Note to any data item(s) that are in the specified categor(ies) and series.

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.

You can change the format for notes generated dynamically inside of PopChart Builder. To do this, choose a graph and select Graph Properties > Notes. This dialog allows you to change the positioning, font, color, and other settings of dynamic notes.

Using an optional fourth parameter in the addNote() method, you can also attach any note to Textbox Objects. This gives you more control over the formatting of your note.

Each Graph.AddNote method can specify any number of Note boxes. The parameters for each different Note box should be separated from the parameters for other Note boxes by a semi-colon (or the item delimiter, which is specified in the Main. ItemDelimiter method).

Note: If you are loading data via the graph. LoadFile command, be sure to call AddNote after you call graph. LoadFile. Otherwise, PopChart Server will be unable to associate your Note with the correct data item.

Parameters Graph.AddNote accepts the following parameters.

Category

{ int | int-int | Category Name }

Specifies the category or categories of the data item(s) for which a Note will appear. This value can be an integer, a range of integers, or the name of a category that has been specified in a Graph. SetCategories method.

If the value of this parameter is an integer, it refers to the nth category listed in the Graph. SetCategories method, where n is the integer specified. So, for example, if Fred is the second category name listed in the Graph. SetCategories method, and we pass 2 as the value of the categories parameter, we are referring to the Fred category.

If you wish to access a category number that is the same as another category's name, you will need to use the pound # sign before the category number. This lets PopChart Server know that you are referring to a category number instead of a category name.

For example, if category number 5 is named 3, then the statement graph.AddNote(3,1,Hello) will add a Note to category number 5, not 3, as it assumes you are referring to the category name. However, if you include a pound # sign before the number 3—graph.AddNote(#3,1,Hello)—then PopChart Server will override the category name and instead add a Note to category number 3.

You can denote a range of categories with an integer, followed by a hyphen, followed by another integer. The first integer represents the first category that should display a Note, while the last integer indicates the last category that should display a Note. All data items in categories between these two will also display the Note. Line 5 of Example 5.6 illustrates how to do this.

Because X-Y and Time graphs do not use categories, the value of this parameter for those graphs is the number of the data item in the specified data series to which you want to add PopUp text. Example 5.7 illustrates this difference.

Note: Make sure you have Sort Data turned off in your appearance file (uncheck Properties > Graph Properties > General > Sort Data) if you are going to use Popup text with X-Y and Line graphs. Otherwise, the Note may appear at the wrong data point.

Series

{ int | Series Name }

Specifies the series of the data item(s) for which a Note will appear. This value can be an integer, a range of integers, or the name of a series that has been specified in a Graph. SetSeries method.

If the value of this parameter is an integer, it refers to the nth series listed in the Graph. SetSeries method(s), where n is the integer specified. For example, if Fruit is the name of the series described in the second Graph. SetSeries method, and we pass 2 as the value of the series parameter, we are referring to the Fruit series.

If you wish to access a series number that is the same as another series' name, you will need to use the pound # sign before the series number. This lets PopChart Server know that you are referring to a series number instead of a series name.

For example, if series number 5 is named 3, then the statement graph.AddNote(1,3,Hello) will add PopUp text to series number 5, not 3, as it assumes you are referring to the series name. However, if you include a pound # sign before the number 3—graph.AddNote(1,#3,Hello)—then PopChart Server will override the series name and instead add a Note to series number 3.

A range of series is denoted by an integer, followed by a hyphen, followed by another integer. The first integer represents the first series that should display a Note, while the last integer indicates the last series that should display a Note. All data items in series between these two will also display a Note. This works similarly to the range of categories shown in Line 5 of Example 5.6.

Text

String

The text that will appear in the Note box.

You can force a new line in the Note box text by insert a backslash and the letter n (\n) where you want the new line to occur. However, when forcing a new line in JavaScript, \n is interpreted as an escape code. You will need to use \\n in JavaScript to specify a new line.

Textbox

Textbox Object

(Optional) This parameter allows you to specify the name of a text box object to which the note will be attached.

For example, if you have created a textbox (or notebox—for all practical purposes, they are the same) in PopChart Builder called notebox1, you can attach a Note to that box using the addNote() call on line 9 of Example 5.6.

Important: If you are sending PCScript in an HTTP Request (i.e. not the PopChart Embedder), be sure to URL-encode (see "URL Encoding" in Chapter 11 of the PopChart Server User Guide) this command, especially if the Note box text string contains spaces or other irregular characters.

Lines 5 and 6 in Example 5.8 are the same command. The first just uses category and series names, while the second uses numbers. In both cases, the text Fred is failing Math will appear in a Note connected to the Fred category in the Math series.

Line 7 shows how to incorporate a range of data items. Data items that are in both the Science series and categories 1-3 display the PopUp text Barney and Wilma and Fred are failing Science.

Line 8 shows how more than one Note can be added with just one Graph.AddNote command.

Example 5.9 shows how Graph.AddNote differs for X-Y and Time graphs. In this case, the text Second Red Plot Point will appear as a Note connected to the data point (5,10).