4. MML Command Tags

This chapter describes some higher-level MML tags, which are called MML commands. See the MML Reference section for the full reference about these commands.

• Loading Turbine Variables
• Loading Turbine DataSets
• AutoMovieClip
• AutoImage
• AutoMedia
• Chart
• Publishing Variables and DataSets
• Using Flash Components

Loading Turbine Variables

Turbine variables can be loaded from MML through the <Var> tag. Variables can be either specified "inline" within the <Var> tag itself:

Or they can be loaded from an external location:

Please see the 'Defining Variables' Section for more details.
 
   

Loading Turbine DataSets

Through the <DataSet> MML tag, DataSets can be loaded from XML tags included "inline" in MML:

For more details about loading DataSets from XML please see the 'Loading a DataSet from XML' Section.

 

AutoMovieClip

The AutoMovieClip command is a really powerful way of automatically generating items like spots on maps, grids, menus, combo-boxes and all sorts of widgets.
Simply put, the AutoMovieClip command displays movie clips driven by values from a DataSet - each row of the DataSet originates the placement of a movie clip. The driving DataSet can have some specially named columns (that start by an underscore character) with information like the movie clip position, scaling, alpha, etc.

The AutoMovieClip tag can work in two modes, with respect to the place coordinates:

• with an automatic cursor - this mode is useful for horizontal/vertical lists and grids.
• with coordinate values specified on the DataSet - this mode is more suited for applications like hot-spots on maps, where coordinates are not structured.

For the complete reference information, please see the <AutoMovieClip> reference entry and the command in action on the included AutoMovieClip Sample.
 

AutoImage

The AutoImage tag does for images what the AutoMovieClip tag does for movie clips - it is a way of displaying either structured or unstructured sets of images, commanded by a DataSet, with each DataSet row originating the placement of an image, with custom properties being controlled by the DataSet values.

As the AutoMovieClip, AutoImage can also work in two modes, in respect to the placement coordinates:

• with an automatic cursor - this mode is useful for horizontal/vertical image lists and grids.
• with coordinate values specified on the DataSet - this mode is more suited for applications like images on on maps, where coordinates are not structured.

For the complete reference information, please see the <AutoImage> reference entry.
 

AutoMedia

While the AutoMovieClip and AutoImage MML commands automate the displaying of Movie Clips and Images respectively, AutoMedia can automate the displaying of any combination of MML tags. With AutoMedia, each DataSet row can originate the creation and display of an element, making it possible to orchestrate complex scenes from structured information in a DataSet.

AutoMedia can work in two different modes, depending on whether pre-defined element ids are specified (on the DataSet or as a tag attribute) or are not specified at all. When an id is specified, instances of the element of such id are displayed as commanded by the DataSet rows. But if no id is specified, Turbine will try to create new elements as instructed by the DataSet and specified <AutoMedia> tag attributes.

For the complete reference information, please see the <AutoMedia> reference entry.

Chart

 
If you're looking into generating impressive animated and interactive Flash charts, please see Rich Chart Server.

Turbine can create sophisticated chart graphics based on DataSet contents, by using the <Chart> tag. Turbine can create charts where each bar, column or pie slice automatically display information contained in DataSet rows. Besides the actual chart element proportions, this information can include a label text, custom color, tooltip text and/or a link to be used (for example) on custom drill-down sequences.

The following chart types are included:

• Area
• Area3d
• Column
• Column3d
• CoolColumn
• Glass
• Line
• Line3d
• LineMarker
• Pie
• Pie3d
• Plain
• Scatter
• Stick
• Triangle
• Triangle3d

Please see the included Charts sample for live examples of all these chart types.
 

Publishing Variables and DataSets

Turbine Variables exist at server-time, when the output media is processed and generated; often, it's useful to make some of these values available into the Flash player, as Action Script variables.
Turbine Variables can be published in MML by using the the <PublishVar> tag, which can publish into different types of Action Script variables - these variables are defined, just as if they were natively defined in Action Script code - the following variable types can be created:

The following example publishes Turbine variables {name} and {address} into AS variables:

This would create two AS variables, similar as the following AS block:

On a similar way, the contents of a DataSet can also be published into Action Script with the <PublishDataSet> tag - for example:

The same possibilities in regard to Action Script variable types are also present when publishing DataSets.

Published variables will not be available when exporting to PDF.

Using Flash Components

Flash MX components can be used with Turbine to build complex interfaces. To use a Flash component, the following simple steps are needed:

• A Flash .swf file containing an instance of the component must be included with the <Include> tag or with the Interface with the Turbine.Include call
• The component must be placed with the <Place> tag, by using the special component attribute. Any component parameters can be defined with <Param> tags inside the <Place> tag - the component parameter names should be the same as used on the Macromedia Flash authoring tool.

Suppose we have a Flash .swf movie (pushbutton.swf) where an instance of a PushButton component as been placed. To include and use this component, all we need to do is:

The above would display a PushButton component with default values - to set component parameters, we can use <Param> tags inside the <Place> - for example to set the button label, we can:

The above example displays the button with its label set to the inspiring "This is a Button".
Component and parameter names and value types are the same as used in the Macromedia Flash authoring tool 'Component Panel' and on the 'Component Parameters' window.

 
Now suppose we have a Flash .swf movie (listbox.swf) where an instance of a ListBox component as been placed. As above, to include and use the component, all we need to do is:

The above would display the ListBox component with default entries - to add some entries to the list box, we can:

The above example displays a list box with the three entries as specified on the labels parameter. Note that the value is an Action Script array - parameter names and values are the same as used in the Macromedia Flash authoring tool Component Parameters window, specified as valid Action Script data types.

The component names that can be used on the <Place> tag should be the same as the component names used on the Flash authoring tool, as listed on the Components panel or on the component's Symbol Properties under the "Name:" field (on this case "ListBox"):

However if the component name as such is not understood by Turbine, then the 'Linkage Identifier' name should be used instead (for example on the above dialog "FListBoxSymbol") - this means that Turbine doesn't known the component and cannot perform this mapping.

A similar mapping is also done for the component parameter names - the parameter names listed on the Component Parameters panel should be used on the <Param> tag, which will cause Turbine to perform a mapping from the parameter names to the actual parameter variable names. In fact this mapping is similar to the mapping listed on the Component Definition dialog (in the Name and Variable columns):

As long as you use the component names and component parameter names, this mapping will occur in a transparent way. The mappings between component parameter names and their underlying Action Script names are stored on the componentregistry.settings file, located on the Turbine installation directory, which already includes a large number of standard component mappings.
If you find a component that is not supported by Turbine, please contact us about it, so we can update it as soon as possible.

When using multiple components, it's advisable to create a single Flash .swf with all the components to be included - the .swf acts as a kind of a component library, which is more efficient than including from separate Flash .swf files and rules out any component version mismatches that might occur.

See the included Components sample for examples of component usage.

Flash components will not be available when exporting to PDF.