Building a Simple Currency Converter
+This tutorial introduces the Prado web application framework and teaches + you how to build a simple web application in a few simple steps. This + tutorial assumes that you are familiar with PHP and you have access + to a web server that is able to serve PHP5 scripts. +
+ +In this tutorial you will build a simple web application that converts
+ a dollar amount to an other currency, given the rate of that currency
+ relative to the dollar. The completed application is shown bellow.
+ class="figure" />
+ You can try the application locally or at
+ Pradosoft.com.
+ Notice that the application still functions exactly the same if javascript
+ is not available on the user's browser.
+
Downloading and Installing Prado
+To install Prado, simply download the latest version of Prado from + http://www.pradosoft.com + and unzip the file to a directory not accessible by your web server + (you may unzip it to a directory accessible by the web server if you wish + to see the demos and test). For further detailed installation, see the + Quickstart Installation guide. +
+ +Creating a new Prado web Application
+The quickest and simplest way to create a new Prado web application is
+ to use the command tool prado-cli.php found in the framework
+ directory of the Prado distribution. We create a new application by running
+ the following command in your
+ command prompt or console. The command creates a new directory named
+ currency-converter in your current working directory.
+ You may need to change to the appropriate directory
+ first.
+
The above command creates the necessary directory structure and minimal + files (including "index.php" and "Home.page") to run a Prado web application. + Now you can point your browser's url to the web server to serve up + the index.php script in the currency-converter directory. + You should see the message "Welcome to Prado!" +
+ +Creating the Currency Converter User Interface
+We start by editing the Home.page file found in the
+ currency-converter/protected/pages/ directory. Files ending
+ with ".page" are page templates that contains HTML and Prado controls.
+ We simply add two textboxes, three labels and one button as follows.
+ class="figure" />
+
+ The first component we add is a
+
The next two pair of component we add is the
+
The next pair of components are similar and defines the textbox + to hold the dollar value to be converted. + The TLabel with ID value "total" defines a simple label. + Notice that the ForControl property is absent. This means that this + label is simply a simple label which we are going to use to display the + converted total amount. +
+ +The final component is a
+
Implementing Currency Conversion
+ +If you tried clicking on the "Convert" button then the page will refresh
+ and does not do anything else. For the button to do some work, we need
+ to add a "Home.php" to where "Home.page" is. The Home class
+ should extends the
+
So far there is nothing interesting about Prado, we just declared some + "web components" in some template file named Home.page and created + a "Home.php" file with a Home class. The more interesting + bits are in Prado's event-driven architecture as we shall see next. +
+ +We want that when the user click on the "Convert" button, we take the
+ values in the textbox, do some calculation and present the user with
+ the converted total. To handle the user clicking of the "Convert" button
+ we simply add an OnClick property to the "Convert" button in
+ the "Home.page" template and add a corresponding event handler method
+ in the "Home.php".
+
In the "convert_clicked" method the first parameter, $sender, + corresponds to the object that raised the event, in this case, + the "Convert" button. The second parameter, $param contains + any additional data that the $sender object may wish to have added. +
+ +We shall now examine, the three lines that implements the simply currency
+ conversion in the "convert_clicked" method.
+
The third line calculates the new amount and set this value in the
+ Text property of the TLabel with ID="total".
+ Thus, we display the new amount to the user in the label.
+
Adding Validation
+The way we convert the user entered value to float ensures that the + total amount is always a number. So the user is free to enter what + ever they like, they could even enter letters. The user's experience + in using the application can be improved by adding validators + to inform the user of the allowed values in the currency rate and the + amount to be calcuated. +
+ +For the currency rate, we should ensure that +
-
+
- the user enters a value, +
- the currency rate is a valid number, +
- the currency rate is positive. +
For the amount to be calculated, we should ensure that +
-
+
- the user enters a value, +
- the value is a valid number (not including any currency or dollar signs). +
Now if you try to enter some invalid data in the application or left out
+ any of the fields the validators will be activated and present the user
+ with error messages. Notice that the error messages are presented
+ without reloading the page. Prado's validators by default validates
+ using both javascript and server side. The server side validation
+ is always performed. For the server side, we
+ should skip the calculation if the validators are not satisfied. This can
+ done as follows.
+
Improve User Experience With Active Controls
+In this simple application we may further improve the user experience + by decreasing the responsiveness of the application. One way to achieve + a faster response is calculate and present the results without reloading + the whole page. +
+ +We can replace the TButton with the Active Control counter part,
+
If you try the application now, you may notice that the page no longer + needs to reload to calculate and display the converted total amount. + However, since there is not page reload, there is no indication or not obvious + that by clicking on the "Convert" button any has happened. + We can further refine the user experience by change the text of "total" label + to "calculating..." when the user clicks on the "Convert" button. The text of + the "total" label will still be updated with the new calculate amount as before. +
+ +To indicate that the calculation is in progress, we can change the text
+ of the "total" label as follows. We add a ClientSide.OnLoading property
+ to the "Convert" button (since this button is responsible for requesting
+ the calculation).
+
The ClientSide.OnLoading and various
+
Adding Final Touches
+So far we have built a simple currency converter web application with + little attention of the looks and feel. Now we can add a stylesheet + to improve the overall appearance of the application. We can simply + add the stylesheet inline with the template code or we may create + a "theme". +
+ +To create and use a theme with Prado applications, we simply create a new + directory "themes/Basic" in the currency-converter directory. + You may need to create the themes directory first. Any + directory within the themes are considered as a theme with the + name of the theme being the directory name. See the + Themes and Skins for further details. +
+ +We simply create a CSS file named "common.css" and save it in the
+ themes/Basic directory. Then we add the following code
+ to the beginning of "Home.page" (we add a little more HTML as well).
+ class="figure" />
+ This completes introduction tutorial to the Prado web application framework.
+