This is the third part of my blog series about data connections provided by Xcelsius 2008. The first part about XML Data is available Explaining Data Connections of Xcelsius 2008 - Part 1: XML Data and the second part is about Flash Variable.
Most content is from my latest book about Xcelsius co-written with Evan Delodder published by SAP Press which is also available on Amazon.
Introduction
Generally speaking, FS Command is an Adobe Flashtechnology that enables Flash to communicate with either the Flash Player orthe program hosting the Flash Player such as a web browser, through JavaScript.For example, a Flash file can use FS Command to execute a piece of JavaScriptstatement in a web browser.
Xcelsius provides an FS Command connection as oneof its standard data connection types. With FS Command, your visualization can invoke JavaScript code written in itscontainer, either the Flash Player or a web browser. Note that this datacommunication is one-way – you can only pass data from Xcelsius to itscontainer, but not the other way. This is just opposite to Flash Variables fromthis extent.
If you are familiar with the Action Scriptlanguage, you may know the function fscommandwith 2 parameters of command and parameters. This data connectivity issimilar to the Action Script function fscommand.You may refer to
for more infoabout its usage.
When to use
You may choose an FS Command connectivity when youwant to control the behavior of the visualization’s container (either the FlashPlayer or the host such as a web server, as mentioned in the section above),from inside the visualization. For example, you can maximum the browser window,or display an alert message using JavaScript when the user has done something,from within the dashboard .
Another scenario when you might choose an FSCommand connectivity is when you want to pass data from your visualization toits container. For example, you can pass data of your dashboard, such as thecurrently selected value from a Combo box, to a piece of JavaScript code run onthe web server for further processing. This is faster than passing the data toa Web Service or XMLL Data connectivity running on a web application server. Onedisadvantage of it is that the JavaScript code may be interpreted differentlyby different web browsers of an Internet Browser or Netscape.
Definition
The Property panel of an FS Command connectivity inData Manager is very simple, divided into 2 tabs. The Usage tab is common toother connection types, where you define when to trigger the connection. Herewe talk about the Definition tab, the properties of which are displayed inFigure 1 below.
Figure 1. Definition of FS Command connection
§ Name
Same as that of any other Data Connectivitymentioned in sections above, you name theconnection here with a meaningful text instead of “Connection 1” or “Connection2”, to make it distinguishable when there’re several connections in the list tothe left. A typical name should indicate the purpose or functionality of thatconnectivity.
§ Command & Parameters
In these 2 fields you specify what command toinvoke and the parameters along with it. If your dashboard is run in AdobeFlash Player, the command can only be one of the predefined some. However, ifit’s wrapped inside a HTML file and run in a web browser, you can use the nameof any JavaScript function here thus make it possible for your dashboard tocall any JavaScript function.
For the latter case, at runtime, your dashboarddoesn’t call the command directly. Instead, in the HTML file with yourdashboard embedded, you write a myMovie_DoFSCommandfunction usingJavaScript with 2parameters of “command” and “properties”, as below:
function myMovieName_DoFSCommand(command, args)
In this function, myMovieName isthe id of your dashboard as an embedded SWF object in the HTML, that’s, the NAME attributeof the EMBED tagor the ID property of the OBJECT tag in the HTML file. When the connectivityis triggered, command and parameters configured here will be passed to thisfunction as command and argsrespectively.
OK, let’s return to how to specify values for these2 fields. In Command field, you specify the name of the JavaScript functionthat you want to call or invoke by either entering a text directly in the Inputfield, or clicking the Bind button to bind to a single cell in the embeddedspreadsheet. So it is with the Properties field. The accepted values of these 2fields are different when the dashboard is run in an Adobe Flash Player or in aweb browser, as explained below.
If the container of your visualization is the FlashPlayer, you must enter the name of one of the predefined commands here, and correspondingly,ether the name of one of the supported parameters of that command, if any. Thesupported commands and their required parameters are listed below.
Quit:
Parameter: No parameter accepted
Purpose: Use this command if you want to close theAdobe Flash Player to terminate the presentation. You may provide a Togglebutton in your visualization labeled Close for the user to close the FlashPlayer. The user’s clicking the button will trigger the connectivity, thusclose the Flash Player.
Fullscreen
Parameter: true of false
Purpose: Use this command if you want to enable the user to set the Flash Player tofull-screen mode or return it to normal menu view. Specify parameter true forfull-screen mode or false for normal view.
Allowscale
Parameter: true of false
Purpose: Specifying false sets the Flash Player so that your visualization is alwaysdrawn at its original size and never scaled. Specifying true forces it to scaleto 100% of the player.
Showmenu
Parameter: true of false
Purpose: Specifying true enables the full set of context menu items in the Flash Player.If you want to restrict the user’s access to them, specify false to hide allthe context menu items except About Flash Player.
Exec
Parameter: path to the application
Purpose: Use this command if you want to execute an applicationfrom within the Flash Player. This command runs in the subdirectory fscommand only. In other words, if you use this command to call an application, the application mustreside in a subdirectory named fscommand.
Trapallkeys
Parameter: true of false
Purpose: Specifying true sends all key events, including accelerator keys, to theonClipEvent(keyDown/keyUp) handler in the Flash Player.
On the other hand, if your dashboard is wrapped byan HTML file and run in a web browser, you can send any message in the 2parameters of command and parameters. The messages are sent to theJavaScript function with special name myMovieName_DoFSCommand in the HTML file, as mentioned before. This function can then either display or process the messages, or call otherJavaScript functions based on what command is passed in. This makes it possiblefor your dashboard to call any JavaScript function from within it, with myMovieName_DoFSCommand as the proxy.
2 Comments
