Advanced Topic: Using Flash Vars with Crystal
One of the most frequently asked questions for Crystal Xcelsius customers that are integrating their dashboards with a portal or web sites is: "How can I pass parameters to the Dashboard when it loads?" This document will take a look at a feature in Crystal Xcelsius called Flash Variables. This feature allows Dashboard Designers to define ranges of information in Crystal Xcelsius that are to be replaced on load from an html page. The html page will set the Flash Vars variable, call the SWF, and push the ranges of information from the html page to the SWF file. This functionality will allow a portal or web site to pass user information, configuration parameters, or pre-defined criteria to the SWF.
This document contains three sections:
How do Flash Vars Work
Flash Vars can be used to pass any piece of information to the SWF file upon load. This differs from a data connection via XML that allows for accessing information only after the SWF has been loaded. The benefit of using Flash Vars is the ability to pass parameters to the SWF file that will be used to either configure the dashboard, or used as criteria and login information for the queries back to the data source.
The Dashboard designer defines the information that they want replaced with outside parameters by defining a variable and selecting a range of cells for that variable. This information is passed to the SWF file from an html page by setting the Flash Vars variable in the call to load the SWF. The information can be passed in two different formats, CSV and XML. If XML is used then the Crystal Xcelsius standard Row, Column XML structure needs to be used, hence CSV is generally easier to work with.
Example of how Flash Vars can be used
This section will discuss a sample scenario for using the Flash Vars functionality.
When integrating a Crystal Xcelsius designed dashboard into a portal environment that makes real-time connections back to the database, Flash Vars can provide for a seamless and easy-to-implement solution. The portal environment already handles authentication against the security database, as well as specifies which users have access to the various applications inside the shared environment. Using the same authentication techniques, you can ensure that only specific users have access to your dashboard. When the user opens the dashboard, the SWF will need to connect to the database to pull back the data that confirms the user has rights to access and populate the dashboard with the new data. Using Flash Vars, a web developer can easily capture the user's login information from the portal environment, and then pass the credentials to the SWF file upon load. Once the SWF file has the proper credentials it will then pass the information back to the database to run a query. You can also expand upon this idea, and run a query against the database that returns data specific to each individual user.
Example of setting Flash Variable in the html file
Here is a snippet of the format of the html used to call a SWF and to pass the parameters. This example uses the CSV format for the Flash Vars The Flash Vars variable must be set in 2 locations (both highlighted in the following example) the first is under PARAM and the second is in the EMBED tag. The EMBED tag is used for Netscape browsers while the PARAM section is used by all other browsers.
Step-by-Step directions to define Flash Vars
This section is going to describe the steps necessary to define Flash Vars in your Dashboard. We will use the Crystal Xcelsius Sample Models.xls spreadsheet.
1) Open Crystal Xcelsius and press the excel icon in the toolbar to import in the sample spreadsheet. Browse to the Crystal Xcelsius Sample Models.xls file and click ok to import.
2) Select a Column chart from the component dialog box and place it in the middle of the canvas.
3) We will need to define some data to show on the chart. Open the properties dialog for the column chart and select cells 'Simple Chart'!A10:B14 to be displayed in the chart.
4) Next we need to define the data that we want replaced by the Flash Vars. Go to the File Menu and select Export Settings.
5) Select the Use Flash Variables Radio Button and set the format to CSV. Next select the check box for Generate Sample Code, this will generate an html file containing the code needed to call the SWF and set the Flash Vars.
6) The next step is to define the range of data to be set by the Flash Vars. Click on the Define Variables button to open the Replace Data Selection dialog box. Click Add to add a new range, we can leave it called Range0 for this example.
7) Click on the Variable Selection button to define the cells for Flash Vars. Select the 3.00 value in Cell E6 on the Simple Chart Tab. Changing this value will change the data that we selected for our Column Chart. Close the Export Settings Dialog.
8) We have now defined a Flash Variable. Let's export our SWF so we can test how this works. Go to the File Menu and Select Export->Macromedia Flash (SWF). Save the SWF to any location, this example will be saving to the desktop as FlashVar.swf.
9) An html file (FlashVars.html) was generated in the same location as the swf. Double-click on the html file which will open the swf. Make note of the values in the column chart. Now let's change our Flash Variable and see the effect.
10)Start by opening the html file in notepad. We need to change the Flash variables in the 2 spots mentioned in the Example of setting Flash Variable in the html file section above (PARAM, and EMBED tags). Change the value 3.00000 to 13.00000. Save the html file and open it again. We can see that all the values in our chart have now changed. Now open the SWF separately and compare the difference. By opening the SWF and not the html, the Flash Variable is not passed through, which is why we see the default values.
By integrating Flash Vars into your Crystal Xcelsius dashboards, you can create an entirely new set of security and data connectivity features that are not present "out-of-the-box." This level of functionality can be extremely useful, and in some cases necessary, when deploying a connected dashboard into a shared enterprise portal environment.
Chris Bryant is a Product Manager at Business Objects and was responsible for the Crystal Xcelsius 4.5 product release. In addition, Chris oversees all current and future technical integrations between Crystal Xcelsius and other business intelligence platforms. He plays a key role in the strategic development of the Crystal Xcelsius product line.