From 654a9cae43358c7eecf3b522e9876aa7815e2453 Mon Sep 17 00:00:00 2001 From: Fabio Bas Date: Mon, 7 Dec 2015 15:57:51 +0100 Subject: Move urls from pradosoft.com to github's project page; drop unmaintained quickstart tutorial translations --- .../pages/Tutorial/fr/CurrencyConverter.page | 404 --------------------- 1 file changed, 404 deletions(-) delete mode 100755 demos/quickstart/protected/pages/Tutorial/fr/CurrencyConverter.page (limited to 'demos/quickstart/protected/pages/Tutorial/fr/CurrencyConverter.page') diff --git a/demos/quickstart/protected/pages/Tutorial/fr/CurrencyConverter.page b/demos/quickstart/protected/pages/Tutorial/fr/CurrencyConverter.page deleted file mode 100755 index 6b8c7bc3..00000000 --- a/demos/quickstart/protected/pages/Tutorial/fr/CurrencyConverter.page +++ /dev/null @@ -1,404 +0,0 @@ - -

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. - See the Command Line Tool - for more details. -

- -php prado/framework/prado-cli.php -c currency-converter - - -

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. -

- -<com:TForm> -

- Currency Converter -

- <com:TLabel ForControl="currencyRate" Text="Exchange Rate per $1:" /> - <com:TTextBox ID="currencyRate" /> -

- <com:TLabel ForControl="dollars" Text="Dollars to Convert:" /> - <com:TTextBox ID="dollars" /> -

- Amount in Other Currency: - <com:TLabel ID="total" CssClass="result" /> -

- <com:TButton Text="Convert" /> -

-</com:TForm> - -

- 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. - class="figure" /> -

- -

- The first component we add is a - - that basically corresponds to the HTML <form> element. - In Prado, only one TForm element is allowed per page. -

- -

The next two pair of component we add is the - - and - - that basically defines a label and a textbox for the user of the application - to enter the currency exchange rate. - The ForControl 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 <label> element to do the same thing, but - you would have to find the correct ID of the textbox (or - <input> in HTML) as Prado components may/will render the - ID value differently in the HTML output. -

- -

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 - - that the user will click to calculate the results. The Text - property sets the button label. -

- -

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 - , the default base - class for all Prado pages. -

- -<?php -class Home extends TPage -{ - -} - -

- Prado uses PHP's __autoload method to load classes. The convention - is to use the class name with ".php" extension as filename. -

- -

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". -

- -<com:TButton Text="Convert" OnClick="convert_clicked" /> - -

- The value of the OnClick, "convert_clicked", will be the method - name in the "Home.php" that will called when the user clicks on the - "Convert" button. -

- -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; - } -} - -

- 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. -

- -

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. -

- -$rate = floatval($this->currencyRate->Text); - -

- The statement $this->currencyRate corresponds to the - TTextBox component with ID value "currencyRate" in the - "Home.page" template. The Text property of the TTextBox - contains the value that the user entered. So, we obtain this - value by $this->currencyRate->Text which we convert the - value to a float value. -

- -$dollars = floatval($this->dollars->Text); - -

- The next line does a similar things, it takes the user value from - the TTextBox with ID value "dollars and converts it to - a float value. -

- -

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. -

- -$this->total->Text = $rate * $dollars; - - -

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.

- To ensure 1 we add one - . To ensure 2 and 3, we add one - . 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 - Validation Controls page. -

- -<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." /> - - -

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).

- To ensure 1 we just add another TRequiredFieldValidator, for 2 - we could use a - . For simplicity we only allow the user to enter - a number for the amount they wish to convert. -

- -<com:TRequiredFieldValidator - ControlToValidate="dollars" - ErrorMessage="Please enter the amount you wish to calculate." /> -<com:TDataTypeValidator - ControlToValidate="dollars" - DataType="Float" - ErrorMessage="Please enter a number." /> - -

- -

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. -

- -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; - } -} - - -

Improve User Experience With Active Controls

In this simple application we may further improve the user experience - by increasing 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, - , - that can trigger a server side click event without reloading the page. - In addition, we can change the "totals" TLabel with the - Active Control counter part, - , such that the server side can update the browser without - reloading the page. -

- -

- Amount in Other Currency: - <com:TActiveLabel ID="total" CssClass="result" /> -

- <com:TActiveButton Text="Convert" OnClick="convert_clicked" /> -

- -

- 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". -

- -Prado::using('System.Web.UI.ActiveControls.*'); - - -

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). -

- -<com:TActiveButton Text="Convert" OnClick="convert_clicked" > - <prop:ClientSide.OnLoading> - $('<%= $this->total->ClientID %>').innerHTML = "calculating..." - </prop:ClientSide.OnLoading> -</com:TActiveButton> - - -

The ClientSide.OnLoading and various - accept a javascript block as their content or value. - The javascript code $('...') is a javascript function that is - equivalent to document.getElementById('...') 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, $this->total->ClientID. We place this bit of code within a <%= %> to obtain the rendered HTML ID for the "total" label. The rest of the - javascript code innerHTML = "calculating..." simply changes - the content of the "total" label. -

- -

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). -

- -<%@ Theme="Basic" %> - - -<com:THead Title="Currency Converter" /> - - -

- The first line <%@ Theme="Basic" %> defines the - theme to be used for this page. The - - corresponds to the HTML <head> element. In addition - to display the Title property by the THead, all CSS - files in the themes/Basic directory are also rendered/linked - for the current page. Our final currency converter web application - looks like the following. - class="figure" /> - This completes introduction tutorial to the Prado web application framework. -

- -- cgit v1.2.3