diff options
Diffstat (limited to 'demos/quickstart/protected/pages/Tutorial')
| -rw-r--r-- | demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page | 382 | ||||
| -rw-r--r-- | demos/quickstart/protected/pages/Tutorial/example1.png | bin | 0 -> 11139 bytes | |||
| -rw-r--r-- | demos/quickstart/protected/pages/Tutorial/example2.png | bin | 0 -> 13842 bytes |
3 files changed, 382 insertions, 0 deletions
diff --git a/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page b/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page new file mode 100644 index 00000000..0e54fbc2 --- /dev/null +++ b/demos/quickstart/protected/pages/Tutorial/CurrencyConverter.page @@ -0,0 +1,382 @@ +<com:TContent ID="body"> + <h1>Building a Simple Currency Converter</h1> + <p>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. + </p> + + <p>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. + <img src=<%~ example2.png %> class="figure" /> + You can try the application <a href="../currency-converter/index.php">locally</a> or at + <a href="http://www.pradosoft.com/demo/currency-converter/">Pradosoft.com</a>. + Notice that the application still functions exactly the same if javascript + is not available on the user's browser. + </p> + + <h1>Downloading and Installing Prado</h1> + <p>To install Prado, simply download the latest version of Prado from + <a href="http://www.pradosoft.com/">http://www.pradosoft.com</a> + and unzip the file to a directory <b>not</b> 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 + <a href="?page=GettingStarted.Installation">Quickstart Installation</a> guide. + </p> + + <h1>Creating a new Prado web Application</h1> + <p>The quickest and simplest way to create a new Prado web application is + to use the command tool <tt>prado-cli.php</tt> found in the <tt>framework</tt> + 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 + <tt>currency-converter</tt> in your current working directory. + You may need to change to the appropriate directory + first. +<com:TTextHighlighter Language="text" CssClass="source"> +php prado/framework/prado-cli.php -c currency-converter +</com:TTextHighlighter> + See the <a href="?page=GettingStarted.CommandLine">Command Line Tool</a> + for more details. + </p> + + <p>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 <tt>index.php</tt> script in the <tt>currency-converter</tt> directory. + You should see the message "Welcome to Prado!" + </p> + + <h1>Creating the Currency Converter User Interface</h1> + <p>We start by editing the <tt>Home.page</tt> file found in the + <tt>currency-converter/protected/pages/</tt> 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. +<com:TTextHighlighter Language="prado" CssClass="source"> +<com:TForm> + <fieldset> + <legend>Currency Converter</legend> + <div class="rate-field"> + <com:TLabel ForControl="currencyRate" Text="Exchange Rate per $1:" /> + <com:TTextBox ID="currencyRate" /> + </div> + <div class="dollar-field"> + <com:TLabel ForControl="dollars" Text="Dollars to Convert:" /> + <com:TTextBox ID="dollars" /> + </div> + <div class="total-field"> + <span class="total-label">Amount in Other Currency:</span> + <com:TLabel ID="total" CssClass="result" /> + </div> + <div class="convert-button"> + <com:TButton Text="Convert" /> + </div> + </fieldset> +</com:TForm> +</com:TTextHighlighter> + If you refresh the page, you should see something similar to the following figure. + It may not look very pretty or orderly, but we shall change that later using CSS. + <img src=<%~ example1.png %> class="figure" /> + </p> + + <p> + The first component we add is a + <com:DocLink ClassPath="System.Web.UI.WebControls.TForm" Text="TForm" /> + that basically corresponds to the HTML <tt><form></tt> element. + In Prado, only <b>one</b> <tt>TForm</tt> element is allowed per page. + </p> + + <p>The next two pair of component we add is the + <com:DocLink ClassPath="System.Web.UI.WebControls.TLabel" Text="TLabel" /> + and + <com:DocLink ClassPath="System.Web.UI.WebControls.TTextBox" Text="TTextBox" /> + that basically defines a label and a textbox for the user of the application + to enter the currency exchange rate. + The <tt>ForControl</tt> property value determines which component + that the label is for. This allows the user of the application to click + on the label to focus on the field (a good thing). You could have used + a plain HTML <tt><label></tt> element to do the same thing, but + you would have to find the correct <tt>ID</tt> of the textbox (or + <tt><input></tt> in HTML) as Prado components may/will render the + <tt>ID</tt> value differently in the HTML output. + </p> + + <p>The next pair of components are similar and defines the textbox + to hold the dollar value to be converted. + The <tt>TLabel</tt> with <tt>ID</tt> value "total" defines a simple label. + Notice that the <tt>ForControl</tt> 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. + </p> + + <p>The final component is a + <com:DocLink ClassPath="System.Web.UI.WebControls.TButton" Text="TButton" /> + that the user will click to calculate the results. The <tt>Text</tt> + property sets the button label. + </p> + + <h1>Implementing Currency Conversion</h1> + + <p>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 <tt>Home</tt> class + should extends the + <com:DocLink ClassPath="System.Web.UI.TPage" Text="TPage" />, the default base + class for all Prado pages. +<com:TTextHighlighter Language="php" CssClass="source"> +<?php +class Home extends TPage +{ + +} +?> +</com:TTextHighlighter> + Prado uses PHP's <tt>__autoload</tt> method to load classes. The convention + is to use the class name with ".php" extension as filename. + </p> + + <p>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 <tt>Home</tt> class. The more interesting + bits are in Prado's event-driven architecture as we shall see next. + </p> + + <p>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 <tt>OnClick</tt> property to the "Convert" button in + the "Home.page" template and add a corresponding event handler method + in the "Home.php". +<com:TTextHighlighter Language="prado" CssClass="source"> +<com:TButton Text="Convert" OnClick="convert_clicked" /> +</com:TTextHighlighter> + The value of the <tt>OnClick</tt>, "convert_clicked", will be the method + name in the "Home.php" that will called when the user clicks on the + "Convert" button. +<com:TTextHighlighter Language="php" CssClass="source"> +class Home extends TPage +{ + public function convert_clicked($sender, $param) + { + $rate = floatval($this->currencyRate->Text); + $dollars = floatval($this->dollars->Text); + $this->total->Text = $rate * $dollars; + } +} +</com:TTextHighlighter> + If you run the application in your web browser, enter some values and click + the "Convert" button then you should see that calculated value displayed next + to the "Amount in Other Currency" label. + </p> + + <p>In the "convert_clicked" method the first parameter, <tt>$sender</tt>, + corresponds to the object that raised the event, in this case, + the "Convert" button. The second parameter, <tt>$param</tt> contains + any additional data that the <tt>$sender</tt> object may wish to have added. + </p> + + <p>We shall now examine, the three lines that implements the simply currency + conversion in the "convert_clicked" method. +<com:TTextHighlighter Language="php" CssClass="source"> +$rate = floatval($this->currencyRate->Text); +</com:TTextHighlighter> + The statement <tt>$this->currencyRate</tt> corresponds to the + <tt>TTextBox</tt> component with <tt>ID</tt> value "currencyRate" in the + "Home.page" template. The <tt>Text</tt> property of the <tt>TTextBox</tt> + contains the value that the user entered. So, we obtain this + value by <tt>$this->currencyRate->Text</tt> which we convert the + value to a float value. +<com:TTextHighlighter Language="php" CssClass="source"> +$dollars = floatval($this->dollars->Text); +</com:TTextHighlighter> + The next line does a similar things, it takes the user value from + the <tt>TTextBox</tt> with <tt>ID</tt> value "dollars and converts it to + a float value. + </p> + + <p>The third line calculates the new amount and set this value in the + <tt>Text</tt> property of the <tt>TLabel</tt> with <tt>ID="total"</tt>. + Thus, we display the new amount to the user in the label. +<com:TTextHighlighter Language="php" CssClass="source"> +$this->total->Text = $rate * $dollars; +</com:TTextHighlighter> + </p> + + <h1>Adding Validation</h1> + <p>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. + </p> + + <p>For the currency rate, we should ensure that + <ol> + <li>the user enters a value,</li> + <li>the currency rate is a valid number,</li> + <li>the currency rate is positive.</li> + </ol> + To ensure 1 we add one + <com:DocLink ClassPath="System.Web.UI.WebControls.TRequiredFieldValidator" Text="TRequiredFieldValidator" />. To ensure 2 and 3, we add one + <com:DocLink ClassPath="System.Web.UI.WebControls.TCompareValidator" Text="TCompareValidator" />. We may add these validators any where within + the "Home.page" template. Further details regarding these validator and other + validators can be found in the + <a href="?page=Controls.Validation">Validation Controls</a> page. +<com:TTextHighlighter Language="prado" CssClass="source"> +<com:TRequiredFieldValidator + ControlToValidate="currencyRate" + ErrorMessage="Please enter a currency rate." /> +<com:TCompareValidator + ControlToValidate="currencyRate" + DataType="Float" + ValueToCompare="0" + Operator="GreaterThan" + ErrorMessage="Please enter a positive currency rate." /> +</com:TTextHighlighter> + </p> + + <p>For the amount to be calculated, we should ensure that + <ol> + <li>the user enters a value,</li> + <li>the value is a valid number (not including any currency or dollar signs).</li> + </ol> + To ensure 1 we just add another <tt>TRequiredFieldValidator</tt>, for 2 + we could use a + <com:DocLink ClassPath="System.Web.UI.WebControls.TDataTypeValidator" Text="TDataTypeValidator" />. For simplicity we only allow the user to enter + a number for the amount they wish to convert. +<com:TTextHighlighter Language="prado" CssClass="source"> +<com:TRequiredFieldValidator + ControlToValidate="dollars" + ErrorMessage="Please enter the amount you wish to calculate." /> +<com:TDataTypeValidator + ControlToValidate="dollars" + DataType="Float" + ErrorMessage="Please enter a number." /> +</com:TTextHighlighter> + </p> + + <p>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 <b>always performed</b>. For the server side, we + should skip the calculation if the validators are not satisfied. This can + done as follows. +<com:TTextHighlighter Language="php" CssClass="source"> +public function convert_clicked($sender, $param) +{ + if($this->Page->IsValid) + { + $rate = floatval($this->currencyRate->Text); + $dollars = floatval($this->dollars->Text); + $this->total->Text = $rate * $dollars; + } +} +</com:TTextHighlighter> + </p> + + <h1>Improve User Experience With Active Controls</h1> + <p>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. + </p> + + <p>We can replace the <tt>TButton</tt> with the Active Control counter part, + <com:DocLink ClassPath="System.Web.UI.ActiveControls.TActiveButton" Text="TActiveButton" />, + that can trigger a server side click event without reloading the page. + In addition, we can change the "totals" <tt>TLabel</tt> with the + Active Control counter part, + <com:DocLink ClassPath="System.Web.UI.ActiveControls.TActiveLabel" Text="TActiveLabel" />, such that the server side can update the browser without + reloading the page. +<com:TTextHighlighter Language="prado" CssClass="source"> +<div class="total-field"> + <span class="total-label">Amount in Other Currency:</span> + <com:TActiveLabel ID="total" CssClass="result" /> + </div> + <div class="convert-button"> + <com:TActiveButton Text="Convert" OnClick="convert_clicked" /> +</div> +</com:TTextHighlighter> + The server side logic remains the same, we just need to import the + Active Controls name space as they are not included by default. We + add the following line to the begin of "Home.php". +<com:TTextHighlighter Language="php" CssClass="source"> +Prado::using('System.Web.UI.ActiveControls.*'); +</com:TTextHighlighter> + </p> + + <p>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. + </p> + + <p>To indicate that the calculation is in progress, we can change the text + of the "total" label as follows. We add a <tt>ClientSide.OnLoading</tt> property + to the "Convert" button (since this button is responsible for requesting + the calculation). +<com:TTextHighlighter Language="prado" CssClass="source"> +<com:TActiveButton Text="Convert" OnClick="convert_clicked" > + <prop:ClientSide.OnLoading> + $('<%= $this->total->ClientID %>').innerHTML = "calculating..." + </prop:ClientSide.OnLoading> +</com:TActiveButton> +</com:TTextHighlighter> + </p> + + <p>The <tt>ClientSide.OnLoading</tt> and various + <com:DocLink ClassPath="System.Web.UI.ActiveControls.TCallbackClientSide" Text="other properties" /> accept a javascript block as their content or value. + The javascript code <tt>$('...')</tt> is a javascript function that is + equivalent to <tt>document.getElementById('...')</tt> that takes a string + with the ID of an HTML element. Since Prado renders its components's IDs, we need + to use the rendered ID of the "total" label, that is, <tt>$this->total->ClientID</tt>. We place this bit of code within a <tt><%= %></tt> to obtain the rendered HTML ID for the "total" label. The rest of the + javascript code <tt>innerHTML = "calculating..."</tt> simply changes + the content of the "total" label. + </p> + + <h1>Adding Final Touches</h1> + <p>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". + </p> + + <p>To create and use a theme with Prado applications, we simply create a new + directory "themes/Basic" in the <tt>currency-converter</tt> directory. + You may need to create the <tt>themes</tt> directory first. Any + directory within the <tt>themes</tt> are considered as a theme with the + name of the theme being the directory name. See the + <a href="?page=Advanced.Themes">Themes and Skins</a> for further details. + </p> + + <p>We simply create a CSS file named "common.css" and save it in the + <tt>themes/Basic</tt> directory. Then we add the following code + to the beginning of "Home.page" (we add a little more HTML as well). +<com:TTextHighlighter Language="prado" CssClass="source"> +<%@ Theme="Basic" %> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" > +<com:THead Title="Currency Converter" /> +<body> +</com:TTextHighlighter> + The first line <tt><%@ Theme="Basic" %></tt> defines the + theme to be used for this page. The + <com:DocLink ClassPath="System.Web.UI.WebControls.THead" Text="THead" /> + corresponds to the HTML <tt><head></tt> element. In addition + to display the <tt>Title</tt> property by the <tt>THead</tt>, all CSS + files in the <tt>themes/Basic</tt> directory are also rendered/linked + for the current page. Our final currency converter web application + looks like the following. + <img src=<%~ example2.png %> class="figure" /> + This completes introduction tutorial to the Prado web application framework. + </p> +</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Tutorial/example1.png b/demos/quickstart/protected/pages/Tutorial/example1.png Binary files differnew file mode 100644 index 00000000..0c7da7ba --- /dev/null +++ b/demos/quickstart/protected/pages/Tutorial/example1.png diff --git a/demos/quickstart/protected/pages/Tutorial/example2.png b/demos/quickstart/protected/pages/Tutorial/example2.png Binary files differnew file mode 100644 index 00000000..1df56cfb --- /dev/null +++ b/demos/quickstart/protected/pages/Tutorial/example2.png |
