Using PopChart Embedder

PopChart Server User Guide 4.0.5

ASP.NET

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.

To add a reference to 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.

This file is located in the dev_tools/dotnet_embedder folder of your installation.

5. The PopChart component should now be listed in the Selected Components box. 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.

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.

To place a control for your PopChart image in the web form

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>

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" in Chapter 4.

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.

Inserting Your PopChart Embedder Code

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

//Put user code to initialize the page here

Instantiating a PopChart Embedder Object

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).

PopChartEmbedder myPopChart = new PopChartEmbedder();

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()

Setting the Server Information

As mentioned in "Setting the Server Information" in Chapter 4, 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.

C#

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:

myPopChart.externalServerAddress = "http://popchart.mycompany.com:2001";

myPopChart.internalCommPortAddress = "10.0.1.1:2002";

Visual Basic

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:

myPopChart.externalServerAddress = "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.

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. 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

Miscellaneous Differences

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: This applies to Active Server Pages, not to the COM PopChart Embedder in General.

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 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:

myPopChart.appearanceFile="bar.pcxml";

This line of code is valid:

myPopChart.appearanceFile="bar.pcxml"

For most Visual Basic developers this will be a very obvious conversion process.

Writing the image to Your Web Page

When you are ready to actually write your embedding HTML to the control you created in "Placing a Control in Your Web Form" in Chapter 5. You will need to output the getEmbeddingHTML() method to the control.

To write the embedding HTML to an HTML control

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" in Chapter 5. 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" in Chapter 5.

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");

In Visual Basic, your assignment statement will look like this:

PopChart1 = FindControl("PopChart1")

Note: You can easily combine these first two steps, as has been done in the examples at the end of this section.

3. 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

Complete Example Code

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#

Visual Basic