add currency-converter tutorial

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">
+&lt;com:TForm&gt;
+    <fieldset>
+        <legend>Currency Converter</legend>
+        <div class="rate-field">
+            &lt;com:TLabel ForControl="currencyRate" Text="Exchange Rate per $1:" /&gt;
+            &lt;com:TTextBox ID="currencyRate" /&gt;
+        </div>
+        <div class="dollar-field">
+            &lt;com:TLabel ForControl="dollars" Text="Dollars to Convert:" /&gt;
+            &lt;com:TTextBox ID="dollars" /&gt;
+        </div>
+        <div class="total-field">
+            <span class="total-label">Amount in Other Currency:</span>
+            &lt;com:TLabel ID="total" CssClass="result" /&gt;
+        </div>
+        <div class="convert-button">
+            &lt;com:TButton Text="Convert" /&gt;
+        </div>
+    </fieldset>
+&lt;/com:TForm&gt;
+</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>&lt;form&gt;</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>&lt;label&gt;</tt> element to do the same thing, but
+		you would have to find the correct <tt>ID</tt> of the textbox (or 
+		<tt>&lt;input&gt;</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">
+&lt;?php
+class Home extends TPage
+{
+	
+}
+?&gt;
+</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">
+&lt;com:TButton Text="Convert" OnClick="convert_clicked" /&gt;
+</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">
+&lt;com:TRequiredFieldValidator
+	ControlToValidate="currencyRate"
+	ErrorMessage="Please enter a currency rate." /&gt;
+&lt;com:TCompareValidator
+	ControlToValidate="currencyRate"
+	DataType="Float"
+	ValueToCompare="0"
+	Operator="GreaterThan"
+	ErrorMessage="Please enter a positive currency rate." /&gt;
+</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">
+&lt;com:TRequiredFieldValidator
+	ControlToValidate="dollars"
+	ErrorMessage="Please enter the amount you wish to calculate." /&gt;
+&lt;com:TDataTypeValidator
+	ControlToValidate="dollars"
+	DataType="Float"
+	ErrorMessage="Please enter a number." /&gt;
+</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>
+         &lt;com:TActiveLabel ID="total" CssClass="result" /&gt;
+    </div>
+    <div class="convert-button">
+        &lt;com:TActiveButton Text="Convert" OnClick="convert_clicked" /&gt;
+</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">
+&lt;com:TActiveButton Text="Convert" OnClick="convert_clicked" &gt;
+    &lt;prop:ClientSide.OnLoading&gt;
+        $('&lt;%= $this->total->ClientID %&gt;').innerHTML = "calculating..."
+    &lt;/prop:ClientSide.OnLoading&gt;
+&lt;/com:TActiveButton&gt;	
+</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>&lt;%= %&gt;</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">
+&lt;%@ Theme="Basic" %&gt;
+<!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" >
+&lt;com:THead Title="Currency Converter" /&gt;
+<body>	
+</com:TTextHighlighter>
+		The first line <tt>&lt;%@ Theme="Basic" %&gt;</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>&lt;head&gt;</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
new 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
new file mode 100644
index 00000000..1df56cfb
--- /dev/null
+++ b/demos/quickstart/protected/pages/Tutorial/example2.png