Customise 4D Business Kit To Fit Your Needs

4DBK goes Flash (Part I)
Technical Note 02-40

Introduction

This technical note is an introduction to the many ways in which Macromedia FlashÇ, the animation program, can be used in conjunction with 4D Business Kit, the turnkey e-commerce solution from 4D. The discussion will focus on the strategies that can be used to get around certain restrictions that may exist when combining these two products. The information given in this technical note is based on the features of Flash version 4.

The topics of discussion include:

• Request and response
• HTTP requests and responses between Flash and 4D Business Kit
• Sending a request from Flash to 4D Business Kit
• Retrieving data from 4D Business Kit for use in Flash
• Sending a request without expecting any return variables
• Submitting data from Flash to 4D Business Kit

Request and response

Before we begin to discuss how 4D Business Kit interacts with Flash, it will be beneficial to understand some of the basic requests as well as the response model of 4D Business Kit. Having this information will give you a better idea of what can and cannot be done between 4D Business Kit and a Flash movie.

In 4D Business Kit, all actions are performed based on the URL that 4D Business Kit receives from the Web browser. The URL must include an appropriate action of what operation 4D Business Kit needs to perform and/or what it needs to send back in return (the HTML page). From this point, we can break the process of request and response down into two scenarios.

Scenario 1: A request is sent to 4D Business Kit to perform a task and return the result in the form of an HTML page.

This type of request is sent to 4D Business Kit in the form of a URL which includes 4D Business Kit command[s]. Once the task has been performed, 4D Business Kit will perform an HTTP redirect to itself and send back the result page.

1. The request is sent from the browser to 4D Business Kit to retrieve data for a specific item.
2. 4D Business Kit performs the requested task and sends a request redirect to itself with a second URL to return the result page to the browser.
3. The data has been inserted into the HTML page and the page is sent to the Web browser.

Scenario 2: A request is sent directly to retrieve an HTML page.

Since there is no specified action (no 4DBK command included), the 4D Business Kit will consider it a direct request to an HTML file. If the requested path exists, the target page will be sent back to the Web browser. Otherwise, an error page will be returned instead.

HTTP requests and responses between Flash and 4D Business Kit

There are three types of HTTP requests that can be sent from a Flash movie to a Web server: 1) form submission with GET method, 2) form submission with POST method, and 3) request without submitting a variable (equivalent to <a href. . .>). Each method may or may not be suitable to use depending on the design of your Flash movie and how the Web server will react to it.

There are two commands in Flash that can send an HTTP request: Get URL and Load Variables. The requests that are performed by these commands are targeted at a particular URL, and may optionally be accompanied by Flash variables sent using either the GET or POST HTTP request methods.

Before you begin using GET or POST method (Flash specifies them as Variables options) in your action-script, you need to understand what can and cannot be processed by 4D Business Kit. From the previous section, we know that 4D Business Kit is only concerned about what is in the URL. Therefore, all variables that you need to send must be included in the URL with a proper format. You may need to construct the URL by appending the variables into it. This procedure will be discussed in a later section of this technical note.

Sending a request from Flash to 4D Business Kit

The type of HTTP request that works best with 4D Business Kit in all situations is a request that occurs without submitting a variable <a href>. Unlike POST and GET method, <a href> will send a request without sending variables in a separate header or attaching them at the end of the URL.

In the case where the request is sent with the GET method, the data that is sent to 4D Business Kit may include one or more form variables as part of the URL (e.g. http://www.domain.com/DVDS_Site/WebPagesUs/detail.html?Variable=value). This type of HTTP request will result in an unhandled URL error in 4D Business Kit because it will take "?" and the rest of the expression as part of the file name which, in this case, does not exist. Therefore it is recommended that all requests be done without sending a variable in order to avoid this problem.

In Flash, you can simulate <a href> by using the command Load Variables or Get URL. The only requirement is that you set the Variables option to "Don't Send." This option will only retrieve data from (and therefore will not send any data to) 4D Business Kit.

Retrieving data from 4D Business Kit to Flash

When using the command Load Variables, Flash can only load text data from 4D Business Kit's response into a numbered level of the Flash movie, or into a target movie clip of the Flash movie. Text data is the only dynamic content type that Flash can retrieve from 4D Business Kit. If you have a picture of your product that you want to display in the Flash movie, you need to copy and paste it directly into the Flash movie. Flash will not be able to retrieve and display it dynamically.

When Flash receives data from 4D Business Kit, the data must be formatted in a certain format. This format requires that all data must be preceded by a variable name.

e.g. variableName=variableValue

If there is more than one variable to be sent, "&" must be used to separate each variable and its value.

variableName1=variableValue1&variableName2=variableValue2&. . .& variableName[N]=variableValue[N]

Since 4D Business Kit can only return an HTML file back to the Web browser, these variables must be preformatted in an HTML file.

For example, I want to obtain information about a movie (such as the price, actors, director, and general description) from 4D Business Kit and dynamically display it in a Flash movie. First, I need to create an HTML file (e.g. Info.html) in the standard ASCII format (plain-text). This file cannot use Word, HTML, or any format other than plain-text. This file will be used to store the variables that you want to display in the Flash movie. In this case, there are four values that need to be retrieved. We can start by adding the following line into the HTML file to create a basic format of the returning variables.

vPrice=&vActor=&vDirector=&vDescription=

Next, a 4DBK tag will be added to allow data to substitute where the value of each variable should be.

&vPrice=<!--#4DBKField/PrCustomerINV.USD,$ ### ### ##0.00-
->&vTitle=<!--#4DBKField/title-->&vDirector=<!--#4DBKField/
director-->&vActor=<!--#4DBKIf(4DBKFieldMultipleSize/actors>
0)-->Starring++<!--#4DBKLoop/VL01,1,4DBKFieldMultipleSize/
actors--> <!--#4DBKFieldMultiple/actors,4DBKVar/VL01-->,
< !--#4DBKEndLoop/VL01--><!--#4DBKEndIf-->&vDescription
=<!--#4DBKField/Text-->

Once the 4DBK tags have been inserted for all values of each variable, we need to specify the store and item that we want to access. You can do this by inserting the following tags at the beginning of the first value tag.

Tag to be inserted:

<!--#4DBKStoreSet/ADDY--><!--#4DBKSelectionSet/5-->
< !--#4DBKQuerySet/code=4DBKDetail-->

Here is what it looks like when all tags have been inserted:

&vPrice=<!--#4DBKStoreSet/ADDY--><!--#4dBKSelectionSet/5-->
< !--#4DBKQuerySet/code=4DBKDetail-->
<!--#4DBKField/PrCustomerINV.USD,$ ### ### ##0.00-->
& vTitle=<!--#4DBKField/title-->&vDirector=<!--#4DBKField/
director-->&vActor=<!--#4DBKIf(4DBKFieldMultipleSize/actors>0)
-->Starring++<!--#4DBKLoop/VL01,1,4DBKFieldMultipleSize/
actors--> <!--#4DBKFieldMultiple/actors,4DBKVar/VL01-->,
<!--#4DBKEndLoop/VL01--><!--4DBKEndIf-->&vDescription=
< !--#4DBKField/Text-->

Note: According to the restriction in Flash, the use of a <space> in the file is also forbidden. If you need to insert a space as part of the value, you need to use "+".

The next step is to create four variables within a Flash movie frame. Here is an example of a frame that has the variables (vPrice, vActor, vDirector and vDescription) created.

This example frame uses the Load Variables command to make an HTTP request to 4D Business Kit to retrieve the variables. The command is embedded in the picture (DVD box) that has been converted into a button.

Here is what the action-script of the image button looks like from the script editor.

- The Load Variables command will make a request to relative URL (the Web browser will insert the http://domainName in front of the specified URL) of

/4daction/4DBKExecute/4DBKStoreSet/ADDY;4DBKSelectionSet/
1;4DBKRecordSet/1;4DBKDetailSet/0001;4DBKGo/info.html

- The Level is set to 0 to refer to the first scene (main timeline) of the movie. If you have more than one scene, make sure that the Level is set to an appropriate scene (0 for the first scene, 1 for the second scene, and so on).

- Since we only need to retrieve data from (and do not send data to) 4D Business Kit, Variables are set to Don't Send.

When the button is clicked, the request will be sent to 4D Business Kit and the result will be as shown below.

Sending a request without expecting any return variables

Often, you may not expect any return values from 4D Business Kit when adding an item into the shopping cart. Of course, it depends on your preference of what you want to happen afterward. Suppose that you only want to click on a graphic to add an item to the cart, run a movie clip, and then return back to where you were. You can ask 4D Business Kit to return an empty HTML file back to Flash. This will ensure that there will be no variables sent back to the Flash movie once the task has been performed by 4D Business Kit.

For example:

/4daction/4DBKExecute/4DBKStoreSet/ADDY;4DBKQuantitySet/
+1;4DBKBasketSet/0001;4DBKGo/result.html,yes,text/plain

Note: result.html is an empty HTML file that 4D Business Kit will send back.

Submitting data from Flash to 4D Business Kit

Submitting data is done in a similar fashion as making a request to retrieve data. The URL that is sent to 4D Business Kit must have the submitting data included as part of the URL. In the case where the submitting data is coming from the user input, the Variables must be inserted into the target URL in a proper way. This is important because combining text and variables in the action-script editor can be very tricky.

Let's take a look at a simple example.

The following movie frame contains an interface to allow the user to log in.

In the frame, there are two variables that will be sent to 4D Business Kit to request a login. The data that is in CustomerCode and CustomerPassword will be inserted into the target URL that Flash will send to 4D Business Kit. This action will be executed by the action-script in the "GO" button.

For the login request, 4D Business Kit will expect to receive a URL with the following format:

http://yourdomain.com/4daction/4DBKExecute/4DBKStoreSet/DVDS
;4DBKCustomerLogin/Username,Password,success.html,fail.html

The same format can be created in the script editor by using a combination of "" and &. Here is an example of what the URL (in the script editor) should look like for the Load Variables command.

"/4daction/4DBKExecute/4DBKStoreSet/ADDY;4DBKCustomerLogin/"
& CustomerCode & "," & CustomerPassword & ",success.html,fail.html"

Important:

In an HTML page, you can declare a URL that uses 4DBKExecute command in the following:

4DBKExecute:4DBKStoreSet/DVDS;

4D Business Kit will automatically convert "4DBKExecute:" to /4daction/4DBKExecute when the file is requested. However, this same declaration format cannot be used with Flash. The URL that is sent from Flash must be a fixed URL. It must be predefined with "/4daction/4DBKExecute/", not 4DBKExecute:4DBKStoreSet/DVDS. 4D Business Kit can manipulate only the content of the HTML file, not the components/script/object within the Flash movie.

Caution:Once a Flash movie has been loaded in the Web browser as part of the HTML page, it will stay loaded until the Web browser has requested a different URL target. Since the movie is loaded as an Object in the HTML, all changes must occur within the object and not the HTML page. If for some reason the Web browser reloads the HTML page, the Flash movie will also be reloaded and the movie will be displayed at the initial state.

Summary

This technical note demonstrates what you need to know about the basic communication types between Flash and 4D Business Kit. Its purpose is to explain the different kinds of behaviors that you can expect from Flash and 4D Business Kit when they communicate.

4D UK Newsletter

Please enter your email address to register for the 4D UK newsletter

International | Company | Contact 4D | Site Map | Privacy Policy | © 4D UK 1995-2009 | Change font size: [A] [A] [A] |