With this tutorial you will discover how the IWE Guestbook application was developed. An advanced tutorial for expert Flash MX users

[b][i]This is an old tutorial that was published years ago on my old website. I publish it here again together with the sources in the Media section of the site.[/i][/b]

TUTORIAL SUMMARY:

1. Introduction
2. The server-side work
3. Building the client side
4. Conclusion and useful links

1. INTRODUCTION

1.1 What we are going to do

Hello to everyone! Here we are again with another lesson. Last time we talked about how to make a simple news ticker using interaction beetween Flash and a PHP server-side script based on a MySQL database. This time, the tools we are going to use are the same again, but the goal we want to achieve is different: we will analyze how I built my IWE Guestbook. The level of this lesson is more advanced than my first one, so the target of this tutorial are experienced developers, expecially under Flash MX, as there is a huge work to do. So, you have to know how to work with functions, how to organize your work in several files, how to use shared libraries and how to use the LoadVars object and its methods. But you also must know how databases work, SQL and basic PHP 4 syntax. To speed up our work and avoid a too big "jump" into the OOP world I made a consistent use of Components for this application. You can find them into the Sources archive. Before opening the source files you must read carefully the REAME_FIRST.txt file, as there are important license terms and conditions to know. Well, if you accepted all terms and conditions go on reading, else stop here. You can download the IWEDataManager and the FadingCoverTextbox components also on my website in the Downloads section (the FadingCoverTextbox is available also on Macromedia Flash Exchange and on Flashcomponents.com). Ok, it looks like you agree to all the license terms and conditions, so let's continue our lesson, or better, let's begin Well, the first thing to think of is what is the result that we want to reach: I thought about a quite complex but easy to use and upgrade application, not a guestbook for this tutorial, but a guestbook for daily usage, for the webmaster that needs a guestbook but that maybe does not know Flash or for a developer like me, that maybe wants to give a quality product without losing time when the customer asks him for a guestbook. So this product must be totally dynamic, totally customizable, with administration facilities and easy and quick to install. So my project is about a software that has all these requirements and that every one (me at first place) can make it run in minutes or maybe seconds. I don't want to list here all the installation procedure, as it is well explained in the README_FIRST.txt file. We will touch all steps, but from the developer side and not from the user one.

2. THE SERVER-SIDE WORK

2.1 Projecting the structure of the application and the database.

What is a guestbook? It's an area where an user can leave a message to the author or the owner of a website. So, which parts do we need to make this kind of application? Well, a basic guestbook should have a page (or movie in this case) that shows all entries saved by the site's visitors and an entry insertion form to let new visitors save their own entry. All these data need to be stored in a database, so we need also a table that's used to save these information. In IWE Guestbook I had others tasks to manage: the first thing I thought about was the installation procedure. The user has got to unzip the guestbook archive file and launch the installation user interface. With this procedure the software must create all tables that are needed and save the settings information inside one of them as each administrator can customize the guestbook interface. So the first step to do is to create the PHP script that will receive data from the Flash form and will create the database structure and save the settings inside the settings table. We could do this part also without a Flash form, but as one of my goals was to let the user to have a preview of the settings he is going to set, I preferred to achieve it by using Flash. Before showing the code of the first PHP script let's think about the data we want to store in the settings table:

1. the administrator username
2. the administrator password (those data are saved for future administrator logins)
3. the header color
4. the rows background colors
5. the header text color
6. the body font color
7. the welcome text
8. the header text
9. a custom logo

The above data are the fields of our table, with a field that was not listed and that is optional, as this table will have only one record: the ID field. I insert it too as it is useful for updating the settings in a second time and because to "normalize" a database the first rule is that all tables must own at least a primary key.

2.2 Setting up the configuration file

Well done, let's introduce two scripts before showing the PHP installation script. I want this guestbook an easy-to-install software. As we are not wizards, we need to know four data for making a connection to the MySQL server: the hostname, the database name and the username and password. These are the only data that the user will edit by his own opening a file. I called this file "config.php". Let's look at its code:

The above code is well explained. Why are we making a separate file to store these information? There are several factors to look at: the user work must be easy, we cannot make him open all .php files to change the connection info. Maybe the user is not a developer at all so he must be able to configure the connection data even without having any coding basis. This from the users side. From the developer side it's a question of workflow optimization and time saving for future updates. It's easier to change information only once and it's less difficult to require a single file in each file respect to write the same lines of code each time. This is the concept that is at the base of this application building process. I will use it with both the server-side and the client-side code.

2.3 Writing the connection code

Now that we have gathered the connection information we can pass to code the connection. Using the above concept, we will do a single file that we will include or require in each page that will need to connect to the database. I called this file "connection.php". Following is the connection code:

As you can see I inserted in the die function a strange line: die("&error1=".mysql_error()); this means that if the mysql_connect function fails, the die output will be &error=error value. In this way our Flash movie can receive an error value that can be managed by a custom script (we will analyze this step later).

2.4. The installation script

Ok, now we can write down the code for the installation file. I called this one "install.php".

With this script we first check that all required fields exists and are passed to the server. If something's wrong it will pass an error code to Flash telling that data are missing. As you can see in the very first line I required another file: "global_functions.php". This file contains some functions that are used in most of the other files. The last function sets compatibility between old and new PHP 4 versions, as in PHP 4.2 and newer versions there have been added new global variables such as $_GET instead of $HTTP_GET_VARS and so on. This explains why I included that file. Well, let's go on. We suppose that all variables have been sent by the Flash movie. In this case the script will connect to the database (requiring the connection file), and will execute the first SQL query: let's analyze it together. It sets up the settings table with 10 fields: this table will contain all the settings that the user specifies through the Flash Installation UI. So you can se in detail how is structured each field by watching at the query: there is an id field (unique and primary key), the administrator field (that contains the administrator username), the administrator password (no need to explain), and so on (read above, in the list at point 2.1). Someone can tell that is not a good idea to save directly the password in the database, but this is a guestbook, not a so secure application. If you want to add more security to the application, you could use an encryption script (based on the MD5 algorythm, for example) that saves the encrypted password and when it is needed again (for a login) it checks for equality of the saved encrypted value and the encrypted entered value. After that, the query is executed and actually a new query is set up: this time we need to insert the passed values into the iwe_gb_settings table that has just been created. We use the INSERT INTO SQL command to insert values in their respective table fields. As you can see, the id value is left blank, as it is managed automatically by the database. After creating the query we need to execute it. Ok, if it is all right now we'll do a strange thing: look at the following lines of code:

With this code we check with a new query if values have really been inserted into the settings table. If the number of rows is equal to 1 we set the $step1 variable value to true. This variable is needed after for another control, so try to take it in mind. Now we need one more thing to complete the database creation step and the installation process: to create the second table, the one that will contain the surfers messages. I called it "iwe_gb_entries". In it we need to save the following information besides the ID that is a must and is automatically managed, as in the first table:

1. surfer's name *
2. surfer's email address
3. surfer's homepage text
4. surfer's homepage URL
5. surfer's entry *
6. ipaddress
7. hostname
8. entrydate

The * fields must be completed by the surfer to validate the sending of the entry. As you can notice, there are 6 fields that are needed: the first 5 (not including the id one) and the last one. The ipaddress and the hostname are not needed, but they can be useful, so I inserted them anyway and I'll let only the administrtor have access to them. After having set the query it is executed. In the following line of code you can see again a variable name that you should remember: $step2. But this time it's a new variable. Let's analyze what is happening:

In the first line the query result value is checked: if it's different from 0 it means that the query has been executed succesfully. In this case we can delete the install.php file itself and passing the install parameter to Flash. Note that depending on your user's system permissions, sometimes you cannot delete this file automatically, in that case you must delete it manually or simply renaming it. Why must this file be removed? Because Flash will do a control that we are going to analyze in the next paragraph. Well, now the installation script is complete, let's go and analyze the next script that we need on the server-side.

2.5. Detecting if the guestbook has already been installed

I said before that we need to check if the install file exists or not to know whether the installation user interface must be shown or not. Imagine our Installation UI: it's a Flash movie that the first time you launch the guestbook makes this control. If the guestbook needs to be installed it proceeds with its installation, else it let the Administrator (and only this user!!) make changes to the guestbook configuration. To enable this feature we need a really simple PHP script. Here it is:

This code is contained in the "detect.php" file. As you can see it checks for the install.php file and returns a variable to use in the Flash movie(s).

[i]2.6. Getting/saving settings from the administration panel[/i]

When the guestbook Administrator will need to make changes to the guestbook panel, it could be a good idea to automatically remember him (or her) the current settings, so that he/she can easily update them. To do this we need another server-side script, that is the "admin_settings.php" file. Let's have a look inside it:

Once again we require two already known files: they are "connection.php" and "global_functions.php". In the third line we set compatibility calling the setCompliance fucntion. Then we have to check if a POST parameter was passed by the Flash movie: it's called getInfo and it can have two values, true and false. In the first case this script will get the settings from the setting table and will output them for Flash, and in the second case it will save the new entered values into that table. Also in this script I wanted to make an error control, so I wrote two error codes in case Flash won't pass the getInfo variable or it won't pass the settings values required during the saving process. To save new data I used an UPDATE SQL statement.

2.7. Getting entries data

For now we analyzed only the server-side scripts that are used in the installation and in the settings administration processes. Now let's introduce the real guestbook. As you can imagine, to show the guestbook entries we need a script that reads those data into the database and outputs them out. Well, following you can take a look at that script:

As usual I included the "connection.php" file to enable the database connection. You can see a comment under the header comment in this file. It says: " NOTE: this code respects IWEDataManager FlashMX component requirements". What does this mean? I said in the introduction of this tutorial, I used a certain number of components in this application. This is one of those components: it's my own IWEDataManager component V. 1.1.0, you can find it in the"IWE_GB_SOURCES.zip" file or you can download V. 1.1.0 also from my website's [url="/media"]Media section[/url]). As you can see there is also an evolution of this component, it's the IWEPHPDataManager 2.0, but now I'll explain about V. 1.2.0, because when I make the guestbook application the other component wasn't still born. The IWEDatamanager is a component that loads data from a data source and stores them in a complex object, in this case a multidimensional array (you can think about it as an array of sub-arrays, each index contains a sub-array). In this way the Flash Developer work will be only to take data from that array and using them as he/she needs, with no need to write any functions to load and manage data. It also returns several properties, lenght, success, error, and so on. For a better comprehension about this component read the README.txt file attached in the component package. For now let's go on talking about the server-side. The PHP script that will work together with the Flash component (but it could be also an ASP, or a CFM or a TXT script) must follow this guideline: it must contain a "num_rows" and a "num_fields" variables, so that it can build the structure of the externalData object in the right way. If you don't respect this guideline the component won't work in the right way. So in our script you see that I made it in this way:

Anyway, let's explain the whole script from the beginning, even if it is really simple. As usual I require the connection file. Then I setup the query that will extract the data that need to be put out. The query is executed and the num_rows and the num_fields variables are setup and then printed for Flash as shown before. In the next line I check if the query has returned some results: if there is at least one record the output for Flash is print, else an error code is returned. Ok, this is all for this step, let's go to the next step.

2.8. Inserting a new entry

Well, we are now near to the end of our guestbook server-side coding. The only things left to do are inserting a new entry into the database, letting the administrator update and delete the existing entries. Let's start from the first feature looking at my code:

As usual, I required the connection and the global functions files, calling also the setCompliance function. Then I checked that two required values are passed from the Flash movie: as we wouldn't save an empty record, we test if the name and the entry values exist. If they exist we go on with the saving process, else we send an appropriate errore code. After receiving the name and the entry value from Flash I check if they are not empty string values: this may not happen, as from the Flash movie we will make a first check, but in this way there is one more control and we can stay relaxed! After this, if all is correct, the script checks for the other parameters that are optional but that should be passed to it anyway. If the email value is not an empty string we need to validate the email address received, so I called one of the other functions that you find in the "global_functions.php" file, that is to say the checkEmail function. It is a validation function that returns a boolean value using a regular expression: if the argument passed (the email address) matches the regular expression rules it returns true, else it returns false. So, if the returned value is true the value of the email variable remains the same, else we set the email address to a NULL value. We could also do a more advanced control that returns an error code, but as the email field is optional I didn't want to spend too much time on it. The next values that are checked are the homepage and the location parameters: if one of them is not defined (if the variable is empty) they are set to NULL so that there cannot be any homepages without the respective locations or any locations without their respective homepages. Else we validate the location (URL) variable using the remainin function of the global_functions.php file, that is the checkURL function. It works with the same logic that I applied to the previous one (checkEmail) but this time it returs a formatted value. Ok, only three values are left: ipaddress, hostname and entrydate. Those values are set by the system, so we don't need to check them because they are not passed by the Flash movie. So I simply used the respective functions and global variables to give to each one its own value. The next thing that there is to do is to setup the SQL query and execute it. So, if you look at the code, you can see that I used an INSERT MySQL statement. Using the mysql_affected_rows function (as we did before in the admin_settings.php file) we can know how many records have been affected by the query. If only one record was inserted we can easily return a value to Flash that says that all is all right, else an error code is needed and we set it up in the "else" statement. Also this step is completed, let's take a look to the next one.

2.9. Updating an existing entry

Let's see now what do you need to update an existing entry. First of all, there is a consideration to do: this action, together with the "delete entry" one should be done only by the administrator, because simple users must not delete previously saved records or changing their text or other information. For this reason, as you can see in the code below, I required the "admin_login.php" file. The job of this file is to validate the administrator login. If an user hasn't got any permissions to access these features he/she will not be logged in.

Also this time the script is not long. As you can notice, I commented the usual require statement and the respective calling of the setCompliance function. And I didn't do one more thing: I didn't used the connection require statement. Why? Only because those statements are all required by the "admin_login.php" file. Next, we will analyze this file, for now let's look to the current code. Again, some parameters are checked: the login variable (passed by the login script file) , the record id, name, email, homepage, location and entry parameters. Why only these variables? Because they are the only values we will allow the administrator to change: we are not interested in changin an IP address or a HOST name or the DATE of an entry. Those data can be changed, if needed, by the database administrator (if he/she is not the same person). So, if the login variable is true (in this case it means that the login was successful) the script will update the current record. I used the variables names with the "2" number at their end simply because the "normal" names are used in the admin_login.php file, it's only a way to avoid confusion and, maybe, conflicts inside the script itself. The script ends returning the update status if only one record has been modified or an error in case no records or two or more records were updated.

2.10. Deleting an entry

The last step remaining is scripted inside the "delete_entry.php" file. It's very similar to the previous script (the update one), so there is not much more to say. The only real difference is the query, that uses the DELETE SQL statement. Let's look at the code:

As you can see the code above is really a copy of the "update_entry.php" one. Only the query has changed. In the first control that I did only two parameters are checked and after the execution of the query there is one more control: if the mysql_affected_rows() function returned more than one record an error code is sended, as it would be really a dangerous thing! These cases are really unreal, but it's better to think to all what could happen and try and manage it in such a way. One more step is left: let's analyze the administrator login code.

2.11. Administrator's login

As we talked before, the "admin_login.php" file manages the administrator's login process. Now I'll explain it more in detail. Let's have a look to the code.

At the beginning of the script I required the usual files. Then I checked for administrator and password parameters sended by Flash. If this two variables are not sended the script send the relative error code. If this is not the case it goes on extracting the administrator's record from the database (settings table). If there are no matches or there is more than one match an error code is sended, else the administrator username and password got by the database are checked for matching the parameters sended by the Flash movie. If they match the login variable is set to true, else it is set to false and an error message is sent to tell the user that he/she is not allowed to enter the administration area. As I said in the beginning, this is not the more secure way to authenticate an user, we should use at least an MD5 encryption, but a guestbook is not a "too secret" application, so we can also ease our work and jump that step.

2.12. The get_settings.php file

Before the server side work is complete, you need to code another file. With this file, the system will read the settings from the database and configure the look of the guestbook interface. As this file must work together with the IWE Data Manager Flash MX component, you will code it using the correct parameters, as seen in paragraph 2.7 Getting entries data. Following is the code:

Ok, nothing new here, the only thing to note again are the num_rows and num_fields variables that must be set for compliance with the IWE Data Manager component. Well, the server-side work is finished. Now we will work on the client-side, and it will be a quite long work, because we need to manage also all the error codes that we setup in this lesson. But I think and hope that it is a quite amazing work!

Stay tuned for the nex days, I'll publish the last part of this tutorial!

ubuntu kernel panic not syncing vfs unable to mount root fs on unknown-block!! Help! :-) The last time I tried to reboot one of my Ubuntu Server (10.04 LTS) machines I received this message and the boot process simply did not continue. I hate rebo[…]

Read more

Chi di voi è abituato a passare molto tempo installando/configurando/personalizzando Magento saprà che si tratta di un'ottima piattaforma per realizzare siti e-commerce di elevata qualità. Però, per chi è un po' all[…]

Read more

Last week I was trying to connect to my FTP server after I rebooted the server machine and after a lot of time I didn't connect to it. Normally, I use Filezilla FTP client to connect to FTP servers, and I'm running the version 3.5.3 under Windows. […]

Read more

I'm writing this article to warn all those people that think to pay less for developing their own websites. I'm referring, as usual, to my own experience, but I think that the problem could be encountered in a quite high percentage of web applicat[…]

Read more

Torno a scrivere sul mio blog dopo un periodo di assenza un po' forzata (causa vacanze estive ed impegni vari intercorsi nel frattempo e successivamente) e un po' causata dalla poca voglia (lo ammetto!), dato che in questo periodo sono molto stanco. […]

Read more