FlashDB is a small database for Flash 4/5 written in Perl.
It is very easy to use, and is very basic. There are just two actions:
read and write. With "write" you can write a set of Flash variables to
the webserver. With "read" you can read them all back into Flash.
Simple yet powerful and flexible, that's how I like things.
Freeware database for Flash 4 and Flash 5
Very easy to use
Written in Perl
Unix and Windows 98/NT/2000
Unlimited database size
FlashDB uses the "Load variables" action that was introduced in Flash 4. The
database will therefore not work with Flash 3 or older. The "Load variables" action
will write all currently active variables in one big lump to the server, or
read them all back into Flash. You don't have to specify which variables you
want to write or read, and you don't have to specify their format, type, size,
recordname, database userid/password, or other things that can make
other databases such a pain to use.
FlashDB has no limit to the number of records (a set of Flash variables)
you can store, other than the size of your harddisk.
A record can hold up to 131072 bytes, imposed by the POST method of browsers.
If you are planning a large database
(more than 25.000 records, more than 1Kb per record)
or heavy use (more than 5000 actions per day)
then you should probably look around for something else. FlashDB can handle
it allright, but commercial databases will be faster.
Examples
Visitor Counter
The visitor counter is a perfect example of how to use FlashDB. It's very small
and easy to understand, and still is a useful and practical application.
You can use this counter as a stand-alone counter, or incorporate it into
your Flash movie.
The counter shows all the techniques needed: how to read data from the
server into Flash (in this case a number), change that data (increment by 1), write
the data back to the server, and present the data to the user.
It may sound like a lot, but it's all done in a single movieclip with about 10
actions!
The "counter.fla" source of this example is included in the download (see below).
Take a look at the actions of the Counter movieclip. Specifically look at the
"state" variable, used to wait for a reply from the server.
Here is the same counter again but this time dressed up with graphics and stuff.
This version was designed for me by Fabrice at
ZuidZijde Reclamebureau. This counter
may sometimes show counter+1 if the counter above has finished before this
one.
Chat
A slightly more elaborate example is the chat. I have kept it as basic
as possible, you can add all kinds of bells and whistles yourself.
The button below will open two (2) windows with the chat.
Using the chat should be self-explanatory. Try entering some text, see your
messages appear in the other window, chat to yourself.
The "chat.fla" source of this example is included in the download (see below).
There are several movieclips, take a look at their actions.
Download and install
FlashDB is written in Perl, a populair programming language often used on the
internet. Most webservers have support for Perl, but if your's doesn't then
your administrator will have to install Perl first. Without Perl you cannot
use FlashDB.
The current version of Perl is version 5, but FlashDB will probably work with
Perl 4 just as well.
Create a new directory on your webserver where FlashDB can store
the data, the database directory. A good name would be "data", and a good
location would be near your html directory. Please make sure the permissions
on the directory are so that FlashDB can read and write into it (try 777 on Unix
only if you are having problems).
Use a basic text editor to make the following changes in both scripts in
the cgi-bin directory ("FlashDBread.pl" and "FlashDBwrite.pl"):
Change the location of Perl.
The location of Perl on webservers is usually "/usr/local/bin/perl". If Perl lives in
another directory on your webserver then you must change the first line of
the scripts. Other common locations are "/usr/bin/perl" and "/bin/perl". If your
server is running on Windows 98/NT/2000 then this is a don't-care.
Change the "$Database" setting (both scripts) into the
directory which you created in step 1. Please enter the complete
directoryname all the way up to the root (sometimes called the "fully
qualified path").
Do not use constructions like ".." or "$USER", and do not enter
an URL.
See below for more information about fully qualified
paths.
Upload both scripts.
The scripts should go into your cgi-bin directory,
and must be made executable (permissions 755 on Unix). You may have to change
the filename-extension from ".pl" into something else, some servers use ".cgi"
instead. In some FTP-upload programs you have to manually set the upload-mode
to "text" if the default is "bin".
Test the scripts. Start your browser and enter the URL of the
"FlashDBwrite.pl" script (probably
"http://www.yourserver.com/cgi-bin/FlashDBwrite.pl").
You should see a page with "filename=221&state=done" (the number can be anything).
If you see "state=cannot_open_file" then FlashDB has no permissions to access
the "$Database" directory (see step 1).
Fully qualified paths
A fully qualified path is the complete directoryname all the way up to the root of
the harddisk. It is not an URL and never starts with "http://".
When you enter your account (at the webserver, using FTP) you will see your
folders such as "/cgi-bin", "/html", "/logs", or whatever.
You won't see the rest of the server, you only have access to your own
folders.
Here is an example of an account and it's fully qualified paths:
You see
The fully qualified path
/cgi-bin
/usr/home/www/www.foobar.com/jeroen/cgi-bin
/html
/usr/home/www/www.foobar.com/jeroen/html
/www
/usr/home/www/www.foobar.com/jeroen/www
/logs
/usr/home/www/www.foobar.com/jeroen/logs
A good location for FlashDB's data directory would be:
You see
The fully qualified path
/data
/usr/home/www/www.foobar.com/jeroen/data
You will have to figure out what the first part of your fully qualified
path is.
You can ask your provider, or maybe you can find it on their website in
the help-pages. Or maybe you can find out with this little
showenv program.
It's a little Perl program, just upload it to your cgi-bin directory and
execute it by entering the URL in your browser. Look in the output for
something that looks like a fully qualified path.
Installing the visitor counter
Edit the "counter.fla" file with your Flash editor.
You can find this file in the distribution, the "html" directory. Open the
"counter" symbol. Check the Actions in the properties of frame 2 and frame 5.
The URL of the "Load Variables" action must be changed to point to the cgi-bin
directory on your webserver.
Create "counter.swf". Use the Export function of the Flash Editor
to create a "counter.swf" file.
Upload "counter.swf" and "counter.html".
Upload the "counter.swf" you just created and the "counter.html" from the FlashDB
distribution to your webserver. The location is not important, you can place them
in the top of your document tree, or create a special FlashDB directory first.
Test it. Start your browser and enter the URL of the "counter.html"
file (probably "http://www.yoururl.com/counter.html").
You should now see "Visitors: 1". The number should increment every time
you hit the reload-button of your browser.
Installing the chat
To get the chat working on your server you should basically do the same as with
the visitor counter (see above). I leave this as an excercise to the reader.
Using FlashDB
Tip: Copy the "Counter" movie clip from
the "counter.fla" file in the distribution.
Write
Add the following actions to the properties of a frame. This will write the
current Flash variables into a particular record of the FlashDB database on the server.
The filename variable is the name of the file in which FlashDB will
store the information.
If you don't specify a filename or the filename is "default" then FlashDB
will generate a unique number as filename (the process-id), making the
number available in Flash as, guess what, variable "filename".
Flash Actions (frame properties)
Remarks
Set Variable: "filename" = "record1"
Select a filename for FlashDB.
Load Variables ("/cgi-bin/FlashDBwrite.pl","")
Call FlashDBwrite at the server.
All variables in the current movieclip will be stored on the
server. You do not have to select or deselect variables, they will all
be stored automatically!
The "current" movieclip is the movieclip that contains the FlashDB actions.
The filename is the name of the record in which FlashDB will store
the variables. You can use characters a..z, A..Z, and 0..9.
Use the "filename" to create multiple records.
For example if you want to store the settings of a visitor then you would
assign every visitor a unique userid and copy the userid into the "filename".
The URL of the Load Variables action is the location where you have installed
the FlashDBwrite script on your webserver.
You can also select "Send using GET", but then the amount of data that can
be transmitted is very limited. Depending on the user's browser it is sometimes
as low as 512 bytes.
Read
Add the following actions to the properties of a frame. This will read variables
from a particular record in the FlashDB database on the server.
Frame
Flash Actions (frame properties)
Remarks
1
Set Variable: "filename" = "record1"
Select a filename for FlashDB.
Set Variable: "state" = "busy"
Initialize the "state" variable.
Load Variables ("/cgi-bin/FlashDBread.pl","")
Call FlashDBread at the server.
2
Leave this frame empty, no actions.
3
If (state eq "busy")
Wait for the "state" variable to change.
Go to and Play(2)
Loop. Warning: do NOT use "Go to Previous frame"!
End If
4
The reply from the server has been received and the movie can now continue.
The URL of the Load Variables action is the location where you have installed
the FlashDBread script on your webserver.
Where is the "Load variables" action?
Flash 4: It's hidden under the "load/unload movie" action. Click the "+" button,
select "load/unload movie", then select the "Load variables into location"
radio-button.
Flash 5: In the list of "actions".
Using FlashDB with Flash5
FlashDB will work as-is with Flash5. There are no changes necessary
whatsoever.
You could use the new "onClipEvent(data)"
method to wait for the reply from the server. However, this method will not
work for Flash4 users. My advice is to use FlashDB's method of
waiting for variable "state" to change as described above.
How does it work?
Flash has a special action called "Load Variables"
(see the "load/unload movie" action). This action will communicate with the
webserver, making it possible to read or write Flash variables. The
protocol is very simple, but only sketchily explained in the Flash documentation.
Sending variables to the server
The "Load Variables" action will send a request to the webserver.
Maybe a more logical name for the action would have been "Send Variables",
because that's what it does. Complain to Macromedia, not me.
The format of the request is exactly the same as with a form on a webpage.
The contents of Flash variables is encoded as if they are fields in a
form (you can select GET or POST in Flash). A typical request looks like this:
/cgi-bin/FlashDBwrite.pl?aa=Jeroen&bb=Kessels
I'm sure you have seen URL's like this before.
In this example variable "aa" with contents "Jeroen" is sent, and variable
"bb" with contents "Kessels". The rest of the URL is determined by the URL
parameter of the "Load Variables" action.
Reading variables from the server
Flash uses the same action ("Load Variables") for reading. In this case the
name of the action describes exactly what it does (no complaints here).
Flash expects a flat text file as input, with a single line of text in it.
The text-line is encoded exactly the same as when sending variables.
Here is an example of the contents of such a textfile:
aa=Jeroen&bb=Kessels
To read variables we can specify the URL of such a textfile as URL in the
"Load Variables" action. With the "location" setting you can specify a movieclip
into which the variables will be loaded.
Load Variables ("/data/sample.txt","")
About FlashDB
All FlashDB has to do is store everything after the question-mark "?" (see above)
in a textfile, and dump that textfile back when we want to read the
variables. FlashDB adds a "filename" parameter so you can select a textfile,
and a "state" variable to wait for the server (see below).
Wait for the server
The "Load Variables" action will not wait for the server to respond. The movie
will continue regardless. Depending on the speed of the internet the response
may arrive several frames later, probably at a point where you don't want it
anymore.
You have to make sure a reply from the server has been received.
When you're reading variables from FlashDB it will always add variable
"state=done". Set "state" to something else (for example "state=busy"),
then use "Load Variables" to call FlashDB, and you are sure the variables
have been received when the content of "state" becomes "done".
About security
FlashDB is not protected with userids, passwords, and such stuff. The same is
true for most other cgi-bin applications out there. Hackers love that. They thrive
on it. It's up to you to protect FlashDB with userids and passwords. Simply put
FlashDB in a separate cgi-bin directory and let your webserver protect that
directory.
FlashDB will only write files in the data directory, nowhere else.
It will only accept the following characters in incoming filenames:
'a-z', 'A-Z', and '0-9'. Any other characters are quietly removed, specifically
directory-separators '/' and '\', and shell-escapes such as '|'.
Known problems
Error message "core router not implemented"
This problem seems to be limited to the Flash plugin that comes with
Shockwave version 7.0.3 r15 for the Mac, and only when used inside a browser
(the standalone player works fine). The problem is caused by a bug in the Flash
plugin, not FlashDB.
Usually FlashDB simply does not respond, but sometimes the browser will
crash with the error message "core router not implemented".
The problem occurs if you specify a fully qualified URL
(an URL that starts with "http://www.yoursite.com") in the
"Load Variables" action. The same problem has been reported to occur if
there are too many levels in the URL (more than one "..").
ok:
/cgi-bin/FlashDBread.pl
bad:
http://www.yoursite.com/cgi-bin/FlashDBread.pl
ok:
../cgi-bin/FlashDBread.pl
bad:
../../cgi-bin/FlashDBread.pl
Method=POST does not work
Internet Explorer version 4.5 on Mac's does not support Method=POST.
Internet Explorer version 5 is reported to be fixed, but I have heard from a user
who still had a problem.
There is no problem if you use Method=GET, if you have a PC, or if you are
using Netscape.
Notes
If you have interesting suggestions for improvements then please
let me know! Thanks are welcome, too!
FlashDB is copyrighted freeware. You hereby have my permission to use and/or
change the script in any way you want. If you change the FlashDB scripts then
please remove my copyright.
I have limited time to answer your questions. Please try everything you
can think of before emailing me.
