Table of Contents

 

5. ASP.NET Interface

This section describes the Turbine ASP.NET interface, its methods and properties and how to accomplish the most common tasks.

 

 
 

Getting Started

Let's start with a first example of an ASP.NET script written in C#, that shows how to create a Turbine object and how to generate Flash movie based on a media template (the next examples all use the C# language):

<%@ Page language="c#" %>
<%
// create the Turbine object:
Turbine.Turbine7 Turbine = new Turbine.Turbine7();

// assign a variable:
Turbine.Variable["{name}"] = "some text";

// select the Flash or MML template to use:
Turbine.Load("template.swf");

// now generate the movie to the web browser:
Turbine.GenerateFlash();
' we could also generate PDF:
'Turbine.GeneratePDF();

%>

We start by creating the Turbine object named Turbine, which will be of the type Turbine.Turbine7.

The next line creates a Turbine variable {name} which will have a string value of "some text". This variable will be used in the Flash .swf template loaded on the following line.

Finally we generate the Flash movie and send it to the web browser. Alternatively we could also generate a PDF document.

 

The Turbine ASP.NET Component

Turbine is implemented as an ASP.NET component that inherits from System::ComponentModel::Component and as such it has all the methods and properties as any other .NET component.

A few important things about the behavior of the Turbine component:

  1. It's very important to remember not to have any text before the ASP.NET script block ( <% ... %> ) as all this info will be served to the web browser, and can cause the generated media to be misunderstood by the Flash plug-in or PDF reader on the browser.
  2. Text after the ASP.NET script block where the media is generated will also be sent to the web browser and can possibly be misunderstood by the Flash plug-in or PDF reader. Don't leave text after the trailing %> of the ASP.NET script block.
  3. If you decide not to generate the media (that is, if the ASP.NET script doesn't call the Turbine.Generate command) you can still send any normal HTML to the browser. However, after a call to Turbine.Generate it's not possible to revert and send HTML data, since the generated media was already sent.
  4. After the Turbine.Generate command is issued, the internal memory of Turbine is cleared, resulting in the release of all the loaded elements, loaded variables, etc.

Turbine can be freely used on the Visual Studio environment, after installation it will be available on the Visual Studio Toolbox, on a category name 'Turbine', for normal usage like other components. Since Turbine is not a design-time visual component, when you install it in the Visual Studio Toolbox and drag and drop it on a web form, it will show himself on the bottom part of the page.


Turbine Properties

Some of the characteristics of the movie to generate can be manipulated by setting Turbine's Media properties - for example the background color, the frame rate, width or height.
There are two major groups of properties: properties that are applied to the output media and properties that dictate the overall system settings. Most of the Media settings which are auto-explanatory:


// set media Width:
Turbine.Width = 300;

// set media Height:
Turbine.Height = 200;

// set media background Color:
Turbine.Color = "#FF0000";

// set FrameRate to 12 frames per second(Flash only):
Turbine.FrameRate = 12;

// set Compression level to the maximum:
Turbine.Compress = 9;

// Allow output media to be imported(Flash only):
Turbine.Protect = false;

// enable Debug window:
Turbine.Debug = true;

// let's generate flash MX (which is version 6):
Turbine.FlashVersion = "6";

// get the number of frames from media:
int media_num_frames = Turbine.NumFrames;

// tell Turbine to log every kind of events
// (errors, warnings and infos):
Turbine.Log = "all";

// log to file:
Turbine.LogTo = "file";

You can find a complete list of Turbine properties here.

 

Working with Variables

Defining a value for a Turbine variable will cause the value of such variable to be substituted when the media is generated, everywhere the variable name appears on Text Blocks, Text Fields, Action Script, Turbine commands, both in MML or in Flash .swf templates. With the Turbine ASP.NET interface, variables can be defined by using the Variable property. Let's see an example:


// define an integer variable:
Turbine.Variable["int_variable"] = 7;

// define a real variable:
Turbine.Variable["real_variable"] = 7.77;

// define a string variable:
Turbine.Variable["string_variable"] = "Julia";

// define a boolean variable:
Turbine.Variable["bool_variable"] = true;

Several variables can be loaded at once from a file by using the LoadVar command:


// load several variables from a local file:
Turbine.LoadVar("names.txt");

// load several variables from a remote file:
Turbine.LoadVar("http://www.example.com/names.aspx");

The file can be locally or remotely located.

 

Working with DataSets

Turbine supports the concept of a DataSet which is a collection of variables organized in rows and columns. Please see the DataSet section for more details about Turbine DataSets.

There are four methods to define DataSets: handmade; from a string; from a string defined inside a file; and from ADO.NET.

"Handmade" DataSets

To build an handmade DataSet, you need to define the columns that it contains, and then to add one row/line at a time (of course these lines need to have the same number of defined columns).
To make an analogy with a database table (DataSets are pretty much like tables), first you define which columns (the column titles) that the table will have and then define each of the rows:


// define the DataSet with 2 columns:
Turbine.MakeDataSet("people", "name,age");

// add a row to the DataSet:
Turbine.AddDataSetRow("John,37");

// add another row:
Turbine.AddDataSetRow("Rose,32");

// let's add another column:
int row = 0;
Turbine.AddDataSetColumn("people", "address", row, "Street B");
 

 
Defining DataSets from a String

The format of the string that defines the DataSet can be a special formatted string or it can be a XML string:


// define the DataSet from a DataSet string:
Turbine.DataSetFromString("<name,age>john,77,Rose,50", "people");

// define the DataSet from a XML string:
Turbine.DataSetFromString("<people> <person> <name> John </name> <age> 7 </age> </person> </people>", "people", "person", "name,age");
 

The format of the DataSet string is the same as DataSet files and can be found here.

 
Defining DataSets from Files

Instead of having the string defined inside C# code, one can have the DataSet string defined in a local or remote file:


// define the DataSet from a file:
Turbine.LoadDataSet("people.txt", "people");

// define the DataSet from a XML file:
Turbine.DataSetFromString("http://example.com/people.aspx", "people", "person", "name,age");
 

 
Defining DataSets from ADO.NET

Turbine can create DataSets from ADO.NET DataTables; from ADO.NET DataSets; and from ADO.NET DataViews, to integrate content accessed from a database, causing a Turbine DataSet to be created from the query results stored on such ADO.NET object.

Let's show a simple example on how to create a Turbine DataSet from a ADO.NET DataSet with the command DataSetFromDataSet. The data comes from an SQL database.

...

// define the connection
SqlConnection conn = new SqlConnection(  "server=(local)\\examp;Trusted_Connection=yes;database=people");

// define the SQL to select the data:
String sql = "select * from people";
SqlDataAdapter mySqlDataAdapter = new SqlDataAdapter (sql, conn);

// create the ADO.NET DataSet:
myDataSet = new DataSet();
mySqlDataAdapter.Fill(myDataSet,"people");

// now define the Turbine DataSet from the ADO.NET DataSet:
Turbine.DataSetFromDataSet(myDataSet);

...

The above example will create one Turbine DataSet for each table defined inside the ADO.NET DataSet, which in this particular example, will be just one: the DataSet people.

To create a DataSet from a DataTable you should use the command DataSetFromDataTable:

Turbine.DataSetFromDataTable(myDataTable)

In the same manner, to create a DataSet from a DataView you should use DataSetFromDataView:

Turbine.DataSetFromDataView(myDataView)

 

Working with Media Templates

Turbine can use media from several sources, "mixing" it together with templates to produce the final media. The media templates formats currently supported by Turbine are MML and Flash .swf files. Turbine can include multiple media templates to produce the resulting media.

Let's see a simple example:


// load a Flash .swf template:
Turbine.Load("frame.swf");

// load an MML template:
Turbine.Load("menu.mml");
 

This approach is very useful and powerful, because you can build an application by having several parts of the application in separate files and them assemble them with Turbine. It allows the structuring of media templates to build complex applications through the reuse of common parts by simply Loading them.

What if you want to just include the same file several times? Do you have to load it several times as well? No - for these cases you can use the Include command which includes the file, but does not show it. Later on, you can display it in several places. Let's see an example:


// load a Flash file but don't show it:
// internally this Flash file defines the id "frame"
Turbine.Include("frame.swf");

// place id "frame" several times in different positions:
Turbine.Create("<place id='frame' pos='100,100'/>");
Turbine.Create("<place id='frame' pos='100,120'/>");
Turbine.Create("<place id='frame' pos='100,140'/>");
 

 

Creating MML

What if we'd want to include arbitrary MML in your resulting media? For this situation the ASP.NET Turbine interface provides the Create command:


// place some text:
Turbine.Create("<text>Text generated with MML<text/>");

// place an image:
Turbine.Create("<image src='http://example.com/image.jpg'/>");

// move objects from depth 10 to another position:
Turbine.Create("<move depth='10' pos='10,10'/>");
 

 

Working with Flash Components

Flash components will not be outputted to PDF. If you intend to use Turbine as a PDF outputter only, this subsection can be skipped.

Turbine includes an advanced mechanism to include and use Flash MX components. Turbine can include a component, create several instances of it placed where appropriated and customize each one of the instances by modifying its properties. Turbine can also automatically feed data to a component from a DataSet.
Let's see an example:


// let's include a ListBox component:
Turbine.Include("flistboxsymbol.swf");

// place the component and
// customize it by setting its parameter 'select multiple' to true:
Turbine.Create(
  "<place component='ListBox'
          pos='30,50'
          instance='lst'>
      <param name='select multiple' value='true'/>
   </place>");

Please note that you can use the component's screen name as available on the Macromedia Flash authoring tool: ListBox. Also note that the parameters are also called by their names as seen in Flash editor.

Now we want to populate the ListBox, right? You can do that in a very simple way by loading a DataSet and passing it to the ListBox by using the InjectData command:


// read a DataSet from a file:
// the DataSet is made of one unique column with the ListBox labels
Turbine.LoadDataSet("data.txt", "data");

// now give the DataSet to the ListBox:
// 'lst' is the name of the ListBox
Turbine.InjectData("data", "lst");

Please see the 'Using Components' section for more details about components.

 

Creating Scripting

Scripting will not be exported to PDF. If you intend to use Turbine as a PDF outputter only, this subsection can be skipped.

The ECMA-262 Script or JavaScript scripting language, also known as Action Script (AS) can be included in the resulting Flash media since Turbine has a built-in JavaScript compiler. To include JavaScript, simply use the Script command:

// Create an onscreen text field:
Turbine.Script("createTextField('txt', 1, 150, 170, 200, 20);");

 

Publishing to Client Side

This subsection depends on scripting which will not be exported to PDF. If you intend to use Turbine as a PDF outputter only, this subsection can be skipped.

We already know how to define server-side variables and DataSets in Turbine, but there are some situations where it would be useful to have these same variables and DataSets available to be used at player-time. The ASP.NET Interface provides two commands to accomplish this: the PublishVar and PublishDataSet commands.

The next example publishes one variable into a simple JavaScript variable:


// create a Turbine variable:
Turbine.Var["globalAlphaValue"] = 50;

// publish it to client side:
Turbine.PublishVar("globalAlphaValue");

// now create a client script to use it:
 Turbine.Script("_root.alpha=globalAlphaValue");
 

Next let's publish an entire DataSet to an Action Script Named Array:


// create a Turbine DataSet from a string:
Turbine.DataSetFromString("<name,num>\njohn,64\nRose,50", "people");

// publish it to client side under the name 'ASPeople':
Turbine.PublishDataSet("people", "namedArray", "ASPeople");

// now create a client script to use it:
// it should print 'Rose', assuming we have a textfield named 'txt'
Turbine.Script("txt.text = 'name 1: ' + ASPeople[1]['name'];");
 

 

Fetching HTTP Content

This command does an HTTP GET request to an absolute or relative HTTP URL. This can be useful for a host of situations where you might desire to filter received data before feeding it to Turbine. Let's see an example of the HTTPGet command in action:


' access a remote ASP.NET script:
String to = Turbine.HTTPGet("http://www.example.com/to.aspx");

if (to == "John") {
  Turbine.Load("john.swf");
}
else {
  Turbine.Load("default.swf");
}

If your HTTP content is an image or any other kind of binary content then you should instead use the HTTPGetArray command which returns an Array of bytes with the binary content.

 

Generating Media into the Browser

After all the content and templates have been loaded, it's time to actually generate the media and send it into the web browser. This is as easy as calling the GenerateFlash or GeneratePDF command, as you'll see in most of the examples we've seen - for instance as in the first example of this chapter.

 

Generating to Local Files

Besides generating dynamic Flash media to web users with the GenerateFlash or GeneratePDF command, Turbine allows you to generate and save the media into a file on the web server local disk - this is accomplished by the GenerateToFile command:


// ************** generate first file *********
// set data to generate the media:
 Turbine.Variable["name"] = "Grace";
Turbine.Load("template.swf");

// generate to a local Flash file:
Turbine.GenerateToFile("grace.swf", "flash");
// generate also a PDF document:
Turbine.GenerateToFile("grace.pdf", "pdf");

// empty Turbine memory and start over with a different name
Turbine.Reset();

// ************** generate second file *********
// set data to generate another media:
 Turbine.Variable["name"] = "Dora";
Turbine.Load("template.swf");

// generate to a local Flash file:
Turbine.GenerateToFile("dora.swf", "flash");
// generate also a PDF document:
Turbine.GenerateToFile("dora.pdf", "pdf");
 

Note the Reset command which cleans the memory so we can start all over again.

 

Generating an HTML Plug-in Page

As we've seen Turbine generates PDF or Flash format content. So if one directly requests a Turbine generated media (from an HTML page or by typing the URL on the browser location bar), the web browser displays the generated media in the full browser window. Sometimes this behavior is not desired, so Turbine features an automatic way of detecting if it should directly generate the media content or send before an HTML page with the necessary plug-in loading tags (<object...> and <embed...>). This page in turn will load the generated media content. This can be a great commodity, because you no longer need to care about using a separate HTML page for loading the Turbine generated content. Here's an example of the GenerateHTMLFirst command:


// generate the HTML page with the plug-in
// use the default html page: flashplugin.htm
Turbine.GenerateHTMLFirst();

// browsers should not cache this page
Response.Expires = -1;

// now generate the movie to the web browser
Turbine.GenerateFlash();

When outputting to PDF we can use the same command with a different argument:


// generate the HTML page with the plug-in
// use the default html page: pdfplugin.htm
Turbine.GenerateHTMLFirst("pdf");

// browsers should not cache this page
Response.Expires = -1;

// now generate the document to the web browser
Turbine.GeneratePDF();

 

Media Caching

Sometimes the data access operations involved in generating media can impose heavy loads on database servers or other back-office servers. Also on some situations the accessed data does not change frequently - obvious examples are the news industry (for example a daily news site generated from a database only needs to access this database once a day, as all the other media for the day will be equal), weather maps, distribution maps (with update periods of 3 hours for example), product descriptions (for example updated only weekly at most) and others.

Turbine's caching capabilities can be used in two ways - an easy way, and another more complex (and powerful) way. The easy way is by using the Cache command which will:

  1. Verify if there's any valid (non-expired) media on the media cache. Media is identified on the cache by a code based on the script URL (this is automatically calculated inside Turbine). If there's a cached media, it will be served and script execution will stop as in a "Response.End" command.
  2. If no valid media exists on the cache, execution continues, the media will be generated and its results cached at the end with the specified expiration date. The next request, if the media is on the cache, will be served directly as described on step 1.


// cache the media for 7 hours:
Turbine.Cache("++070000");


But media caching can be controlled in another more powerful way, by using two commands - basically one command adds a file to cache with a certain validity; the other command will serve the media straight from the cache while it is still valid.
The command to add a generated media to the cache is CacheMedia.

The media will only be cached after it is generated, when you issue the GenerateFlash, GeneratePDF or GenerateToFile. So after you issue a CacheMedia command the media will be cached when the Generate command is executed. Any media currently on the cache with the given "reference" will be deleted when the new media is cached.

So we know how to add media to the cache, but how do we serve it (if available, straight from the cache)? By using the ServeCached command.

This command works by checking if there's some valid media on the cache and if so serves it and returns True, exactly in the same way as in the GenerateFlash or GeneratePDF command. But if the media is not in the cache or is out of validity then this command will do nothing and return false.

Usually you will want to use the above commands as in the following example:


// Is media cached?
// If yes, it is served and we can terminate execution
// If no, then we ask it to be cached for 1 minute from now
if (Turbine.ServeCached("some_ref")) {
  Response.End();
}
else {
  Turbine.CacheMedia("some_ref", "++0100");
}

// now generate the media to the web browser
// (which will also automatically cache it)
Turbine.GenerateFlash();
 


Special Case Internet Explorer Optimization

The popular (as in "ubiquitous") Microsoft Internet Explorer browser has a weird behavior when requesting full browser window Flash movies or PDF documents. What happens is that IE makes several HTTP requests for the same page/movie/document - this is not a good thing because it represents more load to the web server, and it's a problem for scripts that do database inserts or updates. ASP Turbine includes a solution for this problem, the IEOptimize command.

Please note that this is only a problem on full browser window requests (without the <object> HTML loader tag). It will not happen when the media is loaded from HTML (for example if you use GenerateHTMLFirst this IE behavior will not happen); It will also not happen on Action Script loadMovie command requests. And it will not happen with other browsers like Mozilla and Opera.

The IEOptimize command must be placed immediately after the Turbine object creation, and preferably on the start of the script, as execution will stop at this command for the unnecessary requests, thus improving performance:

Turbine.Turbine7 Turbine = new Turbine.Turbine7();
Turbine.IEOptimize();

This command will stop script execution (as in a "Response.End" command) if the request is one of the unnecessary requests fired by IE. However, if the request is the valid one (which will actually be displayed on the browser), then normal script execution will continue.
This command will only do something for IE browsers (for other browsers the execution will simply continue), and if the {System.IEOptimization} global setting is enabled, which is the default setting.
Please note that IEOptimize cannot be used on the same script where the GenerateHTMLFirst command is used.

 
Table of Contents

 
Flash and Macromedia Flash are trademarks of Macromedia, Inc.