From 45b0fe42a979d444d547a5248eb2e9e915aaf16a Mon Sep 17 00:00:00 2001 From: wei <> Date: Sun, 14 Jan 2007 02:10:24 +0000 Subject: Add "block-content" to allow user comments on block level elements in quickstart docs. --- .../pages/ActiveControls/ActiveButton.page | 30 +- .../pages/ActiveControls/ActiveCheckBox.page | 6 +- .../ActiveControls/ActiveCustomValidator.page | 6 +- .../protected/pages/ActiveControls/Home.page | 30 +- .../pages/ActiveControls/Introduction.page | 2 +- .../protected/pages/Advanced/Assets.page | 26 +- .../quickstart/protected/pages/Advanced/Auth.page | 38 +-- .../protected/pages/Advanced/Collections.page | 58 ++-- .../quickstart/protected/pages/Advanced/Error.page | 32 +- .../quickstart/protected/pages/Advanced/I18N.page | 146 ++++----- .../protected/pages/Advanced/Logging.page | 26 +- .../protected/pages/Advanced/MasterContent.page | 22 +- .../protected/pages/Advanced/Performance.page | 38 +-- .../pages/Advanced/Samples/I18N/Home.de.page | 2 +- .../pages/Advanced/Samples/I18N/Home.es.page | 2 +- .../pages/Advanced/Samples/I18N/Home.fr.page | 2 +- .../pages/Advanced/Samples/I18N/Home.page | 2 +- .../pages/Advanced/Samples/I18N/Home.pl.page | 2 +- .../pages/Advanced/Samples/I18N/Home.zh.page | 2 +- .../pages/Advanced/Samples/I18N/zh_TW/Home.page | 2 +- .../protected/pages/Advanced/Scripts.page | 104 +++---- .../protected/pages/Advanced/Scripts1.page | 22 +- .../protected/pages/Advanced/Scripts2.page | 80 ++--- .../protected/pages/Advanced/Scripts3.page | 12 +- .../protected/pages/Advanced/Security.page | 38 +-- .../quickstart/protected/pages/Advanced/State.page | 26 +- .../protected/pages/Advanced/Themes.page | 26 +- .../protected/pages/Configurations/AppConfig.page | 14 +- .../protected/pages/Configurations/Overview.page | 4 +- .../protected/pages/Configurations/PageConfig.page | 12 +- .../protected/pages/Configurations/Templates1.page | 44 +-- .../protected/pages/Configurations/Templates2.page | 46 +-- .../protected/pages/Configurations/Templates3.page | 50 +-- .../protected/pages/Configurations/UrlMapping.page | 36 +-- .../protected/pages/Controls/Button.page | 4 +- .../protected/pages/Controls/CheckBox.page | 4 +- .../protected/pages/Controls/ClientScript.page | 21 +- .../protected/pages/Controls/ColorPicker.page | 2 +- .../quickstart/protected/pages/Controls/Data.page | 2 +- .../protected/pages/Controls/DataGrid.page | 68 ++-- .../protected/pages/Controls/DataList.page | 26 +- .../protected/pages/Controls/DatePicker.page | 30 +- .../protected/pages/Controls/Expression.page | 8 +- .../protected/pages/Controls/FileUpload.page | 10 +- .../quickstart/protected/pages/Controls/Head.page | 2 +- .../protected/pages/Controls/HiddenField.page | 4 +- .../protected/pages/Controls/HtmlArea.page | 10 +- .../protected/pages/Controls/HyperLink.page | 2 +- .../quickstart/protected/pages/Controls/Image.page | 2 +- .../protected/pages/Controls/ImageButton.page | 2 +- .../protected/pages/Controls/ImageMap.page | 8 +- .../protected/pages/Controls/InlineFrame.page | 8 +- .../protected/pages/Controls/JavascriptLogger.page | 12 +- .../quickstart/protected/pages/Controls/Label.page | 2 +- .../protected/pages/Controls/LinkButton.page | 2 +- .../quickstart/protected/pages/Controls/List.page | 30 +- .../protected/pages/Controls/Literal.page | 8 +- .../protected/pages/Controls/MultiView.page | 14 +- .../protected/pages/Controls/NewControl.page | 58 ++-- .../protected/pages/Controls/OutputCache.page | 20 +- .../quickstart/protected/pages/Controls/Pager.page | 14 +- .../quickstart/protected/pages/Controls/Panel.page | 2 +- .../protected/pages/Controls/PlaceHolder.page | 2 +- .../protected/pages/Controls/RadioButton.page | 2 +- .../protected/pages/Controls/Repeater.page | 26 +- .../protected/pages/Controls/SafeHtml.page | 6 +- .../protected/pages/Controls/Standard.page | 2 +- .../protected/pages/Controls/Statements.page | 12 +- .../quickstart/protected/pages/Controls/Table.page | 2 +- .../protected/pages/Controls/TextBox.page | 2 +- .../protected/pages/Controls/TextHighlighter.page | 8 +- .../protected/pages/Controls/Validation.page | 72 ++--- .../protected/pages/Controls/Wizard.page | 30 +- .../protected/pages/Database/ActiveRecord.page | 139 ++++----- demos/quickstart/protected/pages/Database/DAO.page | 70 ++--- .../protected/pages/Database/SqlMap.page | 84 ++--- .../protected/pages/Fundamentals/Applications.page | 20 +- .../protected/pages/Fundamentals/Architecture.page | 4 +- .../protected/pages/Fundamentals/Components.page | 52 ++-- .../protected/pages/Fundamentals/Controls.page | 22 +- .../protected/pages/Fundamentals/Hangman.page | 7 +- .../protected/pages/Fundamentals/Modules.page | 20 +- .../protected/pages/Fundamentals/Pages.page | 8 +- .../protected/pages/Fundamentals/Services.page | 16 +- .../protected/pages/GettingStarted/AboutPrado.page | 32 +- .../pages/GettingStarted/CommandLine.page | 26 +- .../protected/pages/GettingStarted/HelloWorld.page | 41 +-- .../pages/GettingStarted/Installation.page | 17 +- .../pages/GettingStarted/Introduction.page | 8 +- .../protected/pages/GettingStarted/Upgrading.page | 31 +- .../protected/pages/Services/SoapService.page | 76 +++-- .../protected/pages/Tutorial/AjaxChat.page | 264 ++++++++-------- .../pages/Tutorial/CurrencyConverter.page | 343 +++++++++++---------- 93 files changed, 1430 insertions(+), 1377 deletions(-) (limited to 'demos/quickstart/protected/pages') diff --git a/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page b/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page index adf50d22..c80c22dc 100644 --- a/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page +++ b/demos/quickstart/protected/pages/ActiveControls/ActiveButton.page @@ -1,9 +1,9 @@ -

TActiveButton

+

TActiveButton

-

TActiveButton is the active control counter part to +

TActiveButton is the active control counter part to TButton. When a TActiveButton is clicked, rather than a normal post back request a callback request is initiated. The OnCallback event is raised @@ -11,29 +11,29 @@ during a callback request and it is raise after the OnClick event.

-

When the ActiveControl.EnableUpdate property is true, +

When the ActiveControl.EnableUpdate property is true, changing the Text property during a callback request will update the button's caption on the client-side.

-

Since the OnCallback event is raised only during a callback request, +

Since the OnCallback event is raised only during a callback request, the OnCallback event handler can be used to handle logic specifically related to callback requests. The OnClick event handler is raised when ever the button is clicked, even if javascript is disabled.

-

The following example the use of both the OnClick and OnCallback +

The following example the use of both the OnClick and OnCallback events of an TActiveButton.

-

TActiveButton Class Diagram

-

The class diagram for TActiveButton is illustrated in the figure below. +

TActiveButton Class Diagram

+

The class diagram for TActiveButton is illustrated in the figure below. Most active control that can perform callback request have a similar structure.

class="figure" alt="TActiveButton class diagram" title="TActiveButton class diagram" /> -

TActiveButton is an extension of TButton +

TActiveButton is an extension of TButton and implements two additional interfaces ICallbackEventHandler and IActiveControl. The TActiveButton contains an instance of TBaseActiveCallbackControl @@ -41,24 +41,24 @@ available through the ActiveControl property of TActiveButton. The following example set the callback parameter of the TActiveButton when a callback request is dispatched.

- + <com:TActiveButton Text="Click Me" OnCallback="button_callback" ActiveControl.CallbackParameter="value" /> -

In the OnCallback event handler method, the CallbackParameter +

In the OnCallback event handler method, the CallbackParameter is available in the $param object.

- + public function button_callback($sender, $param) { echo $param->CallbackParameter; //outputs "value" } -

Adding Client Side Behaviour

+

Adding Client Side Behaviour

-

With in the ActiveControl property is an instance of +

With in the ActiveControl property is an instance of TCallbackClientSide available as a property ClientSide of TActiveButton. The ClientSide property contains sub-properties, such as RequestTimeOut, @@ -68,7 +68,7 @@ The following example demonstrates the toggling of a "loading" indicator when the client-side is making a callback request.

- + <com:TClientSide PradoScripts="effects" /> Loading... @@ -82,7 +82,7 @@ when the client-side is making a callback request. </com:TActiveButton> -

The example loads the "effects" javascript library using the +

The example loads the "effects" javascript library using the TClientScript component. The ClientSide.OnLoading property value contains javascript statement that uses the "effects" library to show the "Loading..." diff --git a/demos/quickstart/protected/pages/ActiveControls/ActiveCheckBox.page b/demos/quickstart/protected/pages/ActiveControls/ActiveCheckBox.page index d66c48f5..5b34492a 100644 --- a/demos/quickstart/protected/pages/ActiveControls/ActiveCheckBox.page +++ b/demos/quickstart/protected/pages/ActiveControls/ActiveCheckBox.page @@ -1,9 +1,9 @@ -

TActiveCheckBox

+

TActiveCheckBox

-

+

TActiveCheckBox is the active control counter part to TCheckbox. The AutoPostBack property of TActiveCheckBox is set to true by default. @@ -11,7 +11,7 @@ OnCallback event is raise after the OnCheckedChanged event.

-

+

The Text and Checked properties of TActiveCheckBox can be changed during a callback request. The TextAlign property of TActiveCheckBox can not be changed during diff --git a/demos/quickstart/protected/pages/ActiveControls/ActiveCustomValidator.page b/demos/quickstart/protected/pages/ActiveControls/ActiveCustomValidator.page index f97ea40d..d723cbac 100644 --- a/demos/quickstart/protected/pages/ActiveControls/ActiveCustomValidator.page +++ b/demos/quickstart/protected/pages/ActiveControls/ActiveCustomValidator.page @@ -1,15 +1,15 @@ -

TActiveCustomValidator

+

TActiveCustomValidator

-

Performs custom validation using only server-side OnServerValidate +

Performs custom validation using only server-side OnServerValidate validation event. The client-side uses callbacks to raise onServerValidate event. The ClientValidationFunction property is disabled and will throw an exception if trying to set this property.

-

Beware that the onServerValidate may be +

Beware that the onServerValidate may be raised when the control to validate on the client side changes value, that is, the server validation may be called many times. diff --git a/demos/quickstart/protected/pages/ActiveControls/Home.page b/demos/quickstart/protected/pages/ActiveControls/Home.page index 5b8c40a2..289c7c1c 100644 --- a/demos/quickstart/protected/pages/ActiveControls/Home.page +++ b/demos/quickstart/protected/pages/ActiveControls/Home.page @@ -1,7 +1,7 @@ -

Active Controls (AJAX enabled Controls)

-

See the Introduction +

Active Controls (AJAX enabled Controls)

+

See the Introduction for a quick overview of the concept behind active controls (AJAX enabled controls). Most active controls have a property of ActiveControl and @@ -13,14 +13,14 @@ during a callback request. Active controls is reliant on a collection of javascript classes.

-

For a quick demo of active controls, try the +

For a quick demo of active controls, try the TActiveButton control. See also the later part of the Current Converter tutorial for a more indepth example.

-

* the tutorial for this control is not completed yet.

+

* the tutorial for this control is not completed yet.

-

Standard Active Controls

-
    +

    Standard Active Controls

    +
    • TActiveButton represents a click button on a Web page. It can be used to trigger a callback request. @@ -92,8 +92,8 @@ TActiveButton control. See also the later part of the Active List Controls +
      • * TActiveCheckBoxList displays a list of checkboxes on a Web page and each checkbox @@ -121,10 +121,10 @@ TActiveButton control. See also the later part of the Extended Active Controls -
          +
          • * TAutoComplete extends TActiveTextBox to offer text completion suggestions. @@ -158,8 +158,8 @@ TActiveButton control. See also the later part of the Active Control Abilities +

            The following table shows the Active Controls that can trigger a callback event and whether the control will raise a PostBack event if Javascript was disabled on the client's browser.

            @@ -307,10 +307,10 @@ if Javascript was disabled on the client's browser.

            -

            Active Control Infrastructure Classes

            -

            The following classes provide the basic infrastructure classes required to +

            Active Control Infrastructure Classes

            +

            The following classes provide the basic infrastructure classes required to realize the active controls.

            -
              +
              • * TActiveControlAdapter tracks the viewstate values of the control and update differences of the client-side HTML diff --git a/demos/quickstart/protected/pages/ActiveControls/Introduction.page b/demos/quickstart/protected/pages/ActiveControls/Introduction.page index 08edac33..df76bd3d 100644 --- a/demos/quickstart/protected/pages/ActiveControls/Introduction.page +++ b/demos/quickstart/protected/pages/ActiveControls/Introduction.page @@ -1,6 +1,6 @@ -

                Overview of Active Controls

                +

                Overview of Active Controls

                TODO: diff --git a/demos/quickstart/protected/pages/Advanced/Assets.page b/demos/quickstart/protected/pages/Advanced/Assets.page index 8c7980a6..f8a41bc3 100644 --- a/demos/quickstart/protected/pages/Advanced/Assets.page +++ b/demos/quickstart/protected/pages/Advanced/Assets.page @@ -1,31 +1,31 @@

                Assets

                -

                +

                Assets are resource files (such as images, sounds, videos, CSS stylesheets, javascripts, etc.) that belong to specific component classes. Assets are meant to be provided to Web users. For better reusability and easier deployment of the corresponding component classes, assets should reside together with the component class files . For example, a toggle button may use two images, stored in file down.gif and up.gif, to show different toggle states. If we require the image files be stored under images directory under the Web server document root, it would be inconvenient for the users of the toggle button component, because each time they develop or deploy a new application, they would have to manually copy the image files to that specific directory. To eliminate this requirement, a directory relative to the component class file should be used for storing the image files. A common strategy is to use the directory containing the component class file to store the asset files.

                -

                +

                Because directories containing component class files are normally inaccessible by Web users, PRADO implements an asset publishing scheme to make available the assets to Web users. An asset, after being published, will have a URL by which Web users can retrieve the asset file.

                Asset Publishing

                -

                +

                PRADO provides several methods for publishing assets or directories containing assets:

                -
                  +
                  • In a template file, you can use asset tags to publish assets and obtain their URLs. Note, the assets must be relative to the directory containing the template file.
                  • In PHP code, you can call $object->publishAsset($assetPath) to publish an asset and obtain its URL. Here, $object refers to an instance of TApplicationComponent or derived class, and $assetPath is a file or directory relative to the directory containing the class file.
                  • If you want to publish an arbitrary asset, you need to call TAssetManager::publishFilePath($path).
                  -

                  +

                  BE AWARE: Be very careful with assets publishing, because it gives Web users access to files that were previously inaccessible to them. Make sure that you do not publish files that do not want Web users to see.

                  Customization

                  -

                  +

                  Asset publishing is managed by the System.Web.TAssetManager module. By default, all published asset files are stored under the [AppEntryPath]/assets directory, where AppEntryPath refers to the directory containing the application entry script. Make sure the assets directory is writable by the Web server process. You may change this directory to another by configuring the BasePath and BaseUrl properties of the TAssetManager module in application configuration,

                  - + <modules> <module id="asset" class="System.Web.TAssetManager" @@ -35,18 +35,18 @@ Asset publishing is managed by the System.Web.TAssetManager module. By

                  Performance

                  -

                  +

                  PRADO uses caching techniques to ensure the efficiency of asset publishing. Publishing an asset essentially requires file copy operation, which is expensive. To save unnecessary file copy operations, System.Web.TAssetManager only publishes an asset when it has a newer file modification time than the published file. When an application runs under the Performance mode, such timestamp checking is also omitted.

                  -

                  +

                  ADVISORY: Do not overuse asset publishing. The asset concept is mainly used to help better reuse and redistribute component classes. Normally, you should not use asset publishing for resources that are not bound to any component in an application. For example, you should not use asset publishing for images that are mainly used as design elements (e.g. logos, background images, etc.) Let Web server to directly serve these images will help improve the performance of your application.

                  A Toggle Button Example

                  -

                  +

                  We now use the toggle button example to explain the usage of assets. The control uses two image files up.gif and down.gif, which are stored under the directory containing the control class file. When the button is in Up state, we would like to show the up.gif image. This can be done as follows,

                  - + class ToggleButton extends TWebControl { ... protected function addAttributesToRender($writer) { @@ -60,10 +60,10 @@ class ToggleButton extends TWebControl { ... } -

                  +

                  In the above, the call $this->getAsset('up.gif') will publish the up.gif image file and return a URL for the published image file. The URL is then rendered as the src attribute of the HTML image tag.

                  -

                  +

                  To redistribute ToggleButton, simply pack together the class file and the image files. Users of ToggleButton merely need to unpack the file, and they can use it right away, without worrying about where to copy the image files to.

                  \ No newline at end of file diff --git a/demos/quickstart/protected/pages/Advanced/Auth.page b/demos/quickstart/protected/pages/Advanced/Auth.page index 3373644a..45f6ea0b 100644 --- a/demos/quickstart/protected/pages/Advanced/Auth.page +++ b/demos/quickstart/protected/pages/Advanced/Auth.page @@ -1,29 +1,29 @@

                  Authentication and Authorization

                  -

                  +

                  Authentication is a process of verifying whether someone is who he claims he is. It usually involves a username and a password, but may include any other methods of demonstrating identity, such as a smart card, fingerprints, etc.

                  -

                  +

                  Authorization is finding out if the person, once identified, is permitted to manipulate specific resources. This is usually determined by finding out if that person is of a particular role that has access to the resources.

                  How PRADO Auth Framework Works

                  -

                  +

                  PRADO provides an extensible authentication/authorization framework. As described in application lifecycles, TApplication reserves several lifecycles for modules responsible for authentication and authorization. PRADO provides the TAuthManager module for such purposes. Developers can plug in their own auth modules easily. TAuthManager is designed to be used together with TUserManager module, which implements a read-only user database.

                  -

                  +

                  When a page request occurs, TAuthManager will try to restore user information from session. If no user information is found, the user is considered as an anonymous or guest user. To facilitate user identity verification, TAuthManager provides two commonly used methods: login() and logout(). A user is logged in (verified) if his username and password entries match a record in the user database managed by TUserManager. A user is logged out if his user information is cleared from session and he needs to re-login if he makes new page requests.

                  -

                  +

                  During Authorization application lifecycle, which occurs after Authentication lifecycle, TAuthManager will verify if the current user has access to the requested page according to a set of authorization rules. The authorization is role-based, i.e., a user has access to a page if 1) the page explicitly states that the user has access; 2) or the user is of a particular role that has access to the page. If the user does not have access to the page, TAuthManager will redirect user browser to the login page which is specified by LoginPage property.

                  Using PRADO Auth Framework

                  -

                  +

                  To enable PRADO auth framework, add the TAuthManager module and TUserManager module to application configuration,

                  - + <service id="page" class="TPageService"> <modules> <module id="auth" class="System.Security.TAuthManager" @@ -36,13 +36,13 @@ To enable PRADO auth framework, add the TAuthManager module and TUs </modules> </service> -

                  +

                  In the above, the UserManager property of TAuthManager is set to the users module which is TUserManager. Developers may replace it with a different user management module that is derived from TUserManager.

                  -

                  +

                  Authorization rules for pages are specified in page configurations as follows,

                  - + <authorization> <allow pages="PageID1,PageID2" users="User1,User2" @@ -52,41 +52,41 @@ Authorization rules for pages are specified in -

                  +

                  An authorization rule can be either an allow rule or a deny rule. Each rule consists of four optional properties:

                  -
                    +
                    • pages - list of comma-separated page names that this rule applies to. If empty or not set, this rule will apply to all pages under the current directory and all its subdirectories recursively.
                    • users - list of comma-separated user names that this rule applies to. A character * refers to all users including anonymous/guest user. And a character ? refers to anonymous/guest user.
                    • roles - list of comma-separated user roles that this rule applies to.
                    • verb - page access method that this rule applies to. It can be either get or post. If empty or not set, the rule applies to both methods.
                    -

                    +

                    When a page request is being processed, a list of authorization rules may be available. However, only the first effective rule matching the current user will render the authorization result.

                    -
                      +
                      • Rules are ordered bottom-up, i.e., the rules contained in the configuration of current page folder go first. Rules in configurations of parent page folders go after.
                      • A rule is effective if the current page is in the listed pages of the rule AND the current user action (get or post) is in the listed actions.
                      • A rule matching occurs if the current user name is in the listed user names of an effective rule OR if the user's role is in the listed roles of that rule.
                      • If no rule matches, the user is authorized.
                      -

                      +

                      In the above example, anonymous users will be denied from posting to PageID1 and PageID2, while User1 and User2 and all users of role Role1 can access the two pages (in both get and post methods).

                      Using TUserManager

                      -

                      +

                      As aforementioned, TUserManager implements a read-only user database. The user information are specified in either application configuration or an external XML file.

                      -

                      +

                      We have seen in the above example that two users are specified in the application configuration. Complete syntax of specifying the user and role information is as follows,

                      - + <user name="demo" password="demo" roles="demo,admin" /> <role name="admin" users="demo,demo2" /> -

                      +

                      where the roles attribute in user element is optional. User roles can be specified in either the user element or in a separate role element.

                      \ No newline at end of file diff --git a/demos/quickstart/protected/pages/Advanced/Collections.page b/demos/quickstart/protected/pages/Advanced/Collections.page index 84883be4..a5b219db 100644 --- a/demos/quickstart/protected/pages/Advanced/Collections.page +++ b/demos/quickstart/protected/pages/Advanced/Collections.page @@ -1,21 +1,21 @@

                      Collections

                      -

                      +

                      Collection is a basic data structure in programming. In traditional PHP programming, array is used widely to represent collection data structure. A PHP array is a mix of cardinal-indexed array and hash table.

                      -

                      +

                      To enable object-oriented manipulation of collections, PRADO provides a set of powerful collection classes. Among them, the TList and TMap are the most fundamental and usually serve as the base classes for other collection classes. Since many PRADO components have properties that are of collection type, it is very important for developers to master the usage of PRADO collection classes.

                      Using TList

                      -

                      +

                      A TList object represents a cardinal-indexed array, i.e., an array (object) with the index 0, 1, 2, ...

                      -

                      +

                      TList may be used like a PHP array. For example,

                      - + $list=new TList; // create a list object ... $item=$list[$index]; // read the item at the specified index @@ -26,14 +26,14 @@ if(isset($list[$index])) // test if the list has an item at $index foreach($list as $index=>$item) // traverse each item in the list -

                      +

                      To obtain the number of items in the list, use the Count property. Note, do not use count($list), as it always returns 1.

                      -

                      +

                      In addition, TList implements a few commonly used convenient methods for manipulating the data in a list. These include

                      -
                        +
                        • clear(): removes all items in the list.
                        • contains(): tests if the list contains the specified item.
                        • indexOf(): obtains the zero-based index of the specified item in the list.
                          • @@ -43,30 +43,30 @@ In addition, TList implements a few commonly used convenient methods fo

                        Using TList-based component properties

                        -

                        +

                        As aforementioned, many PRADO component properties are based on TList or TList-derived collection classes. These properties all share the above usages.

                        -

                        +

                        For example, TControl (the base class for all PRADO controls) has a property called Controls which represents the collection of child controls. The type of Controls is TControlCollection which extends TList. Therefore, to append a new child control, we can use the following,

                        - + $control->Controls[]=$newControl; -

                        +

                        To traverse through the child controls, we can use,

                        - + foreach($control->Controls as $childControl) ... -

                        +

                        Another example is the Items property, available in list controls, TRepeater, TDataList and TDataGrid. In these controls, the ancestor class of Items is TList.

                        Extending TList

                        -

                        +

                        Often, we want to extend TList to perform additional operations for each addition or removal of an item. The only methods that the child class needs to override are insertAt() and removeAt(). For example, to ensure the list only contains items that are of TControl type, we can override insertAt() as follows,

                        - + public function insertAt($index,$item) { if($item instanceof TControl) @@ -78,13 +78,13 @@ public function insertAt($index,$item)

                        Using TMap

                        -

                        +

                        A TMap object represents a hash table (or we say string-indexed array).

                        -

                        +

                        Similar to TList, TMap may be used like an array,

                        - + $map=new TMap; // create a map object ... $map[$key]=$value; // add a key-value pair @@ -92,14 +92,14 @@ unset($map[$key]); // remove the value with the specified key if(isset($map[$key])) // if the map contains the key foreach($map as $key=>$value) // traverse the items in the map -

                        +

                        The Count property gives the number of items in the map while the Keys property returns a list of keys used in the map.

                        -

                        +

                        The following methods are provided by TMap for convenience,

                        -
                          +
                          • clear(): removes all items in the map.
                          • contains(): tests if the map contains the specified key.
                          • toArray(): returns an array representation of the items in the map.
                            • @@ -108,28 +108,28 @@ The following methods are provided by TMap for convenience,

                          Using of TAttributeCollection

                          -

                          +

                          TAttributeCollection is a special class extending from TMap. It is mainly used by the Attributes property of TControl.

                          Besides the normal functionalities provided by TMap, TAttributeCollection allows you to get and set collection items like getting and setting properties. For example,

                          - + $collection->Label='value'; // equivalent to: $collection['Label']='value'; echo $collection->Label; // equivalent to: echo $collection['Label']; -

                          +

                          Note, in the above $collection does NOT have a Label property.

                          -

                          +

                          Unlike TMap, keys in TAttributeCollection are case-insensitive. Therefore, $collection->Label is equivalent to $collection->LABEL.

                          -

                          +

                          Because of the above new features, when dealing with the Attributes property of controls, we may take advantage of the subproperty concept and configure control attribute values in a template as follows,

                          - + <com:TButton Attributes.onclick="if(!confirm('Are you sure?')) return false;" .../> -

                          +

                          which adds an attribute named onclick to the TButton control.

                          \ No newline at end of file diff --git a/demos/quickstart/protected/pages/Advanced/Error.page b/demos/quickstart/protected/pages/Advanced/Error.page index 9d2cf9ec..97d3a602 100644 --- a/demos/quickstart/protected/pages/Advanced/Error.page +++ b/demos/quickstart/protected/pages/Advanced/Error.page @@ -1,21 +1,21 @@

                          Error Handling and Reporting

                          -

                          +

                          PRADO provides a complete error handling and reporting framework based on the PHP 5 exception mechanism.

                          Exception Classes

                          -

                          +

                          Errors occur in a PRADO application may be classified into three categories: those caused by PHP script parsing, those caused by wrong code (such as calling an undefined function, setting an unknown property), and those caused by improper use of the Web application by client users (such as attempting to access restricted pages). PRADO is unable to deal with the first category of errors because they cannot be caught in PHP code. PRADO provides an exception hierarchy to deal with the second and third categories.

                          -

                          +

                          All errors in PRADO applications are represented as exceptions. The base class for all PRADO exceptions is TException. It provides the message internationalization functionality to all system exceptions. An error message may be translated into different languages according to the user browser's language preference.

                          -

                          +

                          Exceptions raised due to improper usage of the PRADO framework inherit from TSystemException, which can be one of the following exception classes:

                          -
                            +
                            • TConfigurationException - improper configuration, such as error in application configuration, control templates, etc.
                            • TInvalidDataValueException - data value is incorrect or unexpected.
                            • TInvalidDataTypeException - data type is incorrect or unexpected.
                              • @@ -28,46 +28,46 @@ Exceptions raised due to improper usage of the PRADO framework inherit from
                            • TNotSupportedException - errors caused by requesting for unsupported feature.
                            • THttpException - errors to be displayed to Web client users.
                            -

                            +

                            Errors due to improper usage of the Web application by client users inherit from TApplicationException.

                            Raising Exceptions

                            -

                            +

                            Raising exceptions in PRADO has no difference than raising a normal PHP exception. The only thing matters is to raise the right exception. In general, exceptions meant to be shown to application users should use THttpException, while exceptions shown to developers should use other exception classes.

                            Error Capturing and Reporting

                            -

                            +

                            Exceptions raised during the runtime of PRADO applications are captured by System.Exceptions.TErrorHandler module. Different output templates are used to display the captured exceptions. THttpException is assumed to contain error messages that are meant for application end users and thus uses a specific group of templates. For all other exceptions, a common template shown as follows is used for presenting the exceptions.

                            exception page

                            Customizing Error Display

                            -

                            +

                            Developers can customize the presentation of exception messages. By default, all error output templates are stored under framework/Exceptions/templates. The location can be changed by configuring TErrorHandler in application configuration,

                            - + <module id="error" class="TErrorHandler" ErrorTemplatePath="Application.ErrorTemplates" /> -

                            +

                            THttpException uses a set of templates that are differentiated according to different StatusCode property value of THttpException. StatusCode has the same meaning as the status code in HTTP protocol. For example, a status code equal to 404 means the requested URL is not found on the server. The StatusCode value is used to select which output template to use. The output template files use the following naming convention:

                            - + error-.html -

                            +

                            where status code refers to the StatusCode property value of THttpException, and language code must be a valid language such as en, zh, fr, etc. When a THttpException is raised, PRADO will select an appropriate template for displaying the exception message. PRADO will first locate a template file whose name contains the status code and whose language is preferred by the client browser window. If such a template is not present, it will look for a template that has the same status code but without language code.

                            -

                            +

                            The naming convention for the template files used for all other exceptions is as follows,

                            - + exception-.html -

                            +

                            Again, if the preferred language is not found, PRADO will try to use exception.html, instead.

                            diff --git a/demos/quickstart/protected/pages/Advanced/I18N.page b/demos/quickstart/protected/pages/Advanced/I18N.page index 9c3d620f..091c0b0a 100644 --- a/demos/quickstart/protected/pages/Advanced/I18N.page +++ b/demos/quickstart/protected/pages/Advanced/I18N.page @@ -1,14 +1,14 @@

                            Internationalization (I18N) and Localization (L10N)

                            -

                            Many web application built with PHP will not have internationalization in mind when it was first written. It may be that it was not intended for use in languages and cultures. Internationalization is an important aspect due to the increase adoption of the Internet in many non-English speaking countries. The process of internationalization and localization will contain difficulties. Below are some general guidelines to internationalize an existing application.

                            +

                            Many web application built with PHP will not have internationalization in mind when it was first written. It may be that it was not intended for use in languages and cultures. Internationalization is an important aspect due to the increase adoption of the Internet in many non-English speaking countries. The process of internationalization and localization will contain difficulties. Below are some general guidelines to internationalize an existing application.

                            Separate culture/locale sensitive data

                            -

                            Identify and separate data that varies with culture. The most obvious are text/string/message. Other type of data should also be considered. The following list categorize some examples of culture sensitive data +

                            Identify and separate data that varies with culture. The most obvious are text/string/message. Other type of data should also be considered. The following list categorize some examples of culture sensitive data

                            -
                              +
                              • Strings, Messages, Text, in relatively small units (e.g. phrases, sentences, paragraphs, but not the full text of a book).
                              • Labels on buttons.
                              • Help files, large units of text, static text.
                                • @@ -23,20 +23,20 @@
                              • Page layout.
                              -

                              If possible all manner of text should be isolated and store in a persistence format. These text include, application error messages, hard coded strings in PHP files, emails, static HTML text, and text on form elements (e.g. buttons).

                              +

                              If possible all manner of text should be isolated and store in a persistence format. These text include, application error messages, hard coded strings in PHP files, emails, static HTML text, and text on form elements (e.g. buttons).

                              Configuration

                              -

                              To enable the localization features in PRADO, you need to add a few configuration options in your application configuration. +

                              To enable the localization features in PRADO, you need to add a few configuration options in your application configuration. First you need to include the System.I18N.* namespace to your paths.

                              - + -

                              Then, if you wish to translate some text in your application, you need to add one translation message data source.

                              - +

                              Then, if you wish to translate some text in your application, you need to add one translation message data source.

                              + System.I18N.*                               namespace to your paths. -

                              Where source in translation is the dot path to a directory +

                              Where source in translation is the dot path to a directory where you are going to store your translate message catalogue. The autosave attribute if enabled, saves untranslated messages back into the message catalogue. With cache enabled, translated messages are saved in the application runtime/i18n directory. The marker value is used to surround any untranslated text.

                              -

                              With the configuration complete, we can now start to localize your application. If you have autosave enabled, after running your application with some localization activity (i.e. translating some text), you will see a directory and a messages.xml created within your source directory.

                              +

                              With the configuration complete, we can now start to localize your application. If you have autosave enabled, after running your application with some localization activity (i.e. translating some text), you will see a directory and a messages.xml created within your source directory.

                              What to do with messages.xml?

                              -

                              The translation message catalogue file, if using type="XLIFF", is a standardized translation message interchange XML format. You can edit the XML file using any UTF-8 aware editor. The format of the XML is something like the following.

                              +

                              The translation message catalogue file, if using type="XLIFF", is a standardized translation message interchange XML format. You can edit the XML file using any UTF-8 aware editor. The format of the XML is something like the following.

                              - + trans-unit                               tag, where

                              Setting and Changing Culture

                              -

                              Once globalization is enabled, you can access the globalization settings, such as, Culture, Charset, etc, using

                              - +

                              Once globalization is enabled, you can access the globalization settings, such as, Culture, Charset, etc, using

                              + $globalization = $this->getApplication()->getGlobalization(); echo $globalization->Culture; $globalization->Charset= "GB-2312"; //change the charset -

                              You also change the way the culture is determined by changing the class attribute in the module configuration. For example, to set the culture that depends on the browser settings, you can use the TGlobalizationAutoDetect class. - +

                              You also change the way the culture is determined by changing the class attribute in the module configuration. For example, to set the culture that depends on the browser settings, you can use the TGlobalizationAutoDetect class. + ... -

                              You may also provide your own globalization class to change how the application culture is set. +

                              You may also provide your own globalization class to change how the application culture is set. Lastly, you can change the globalization settings on page by page basis using template control tags. For example, changing the Culture to "zh".

                              - + <%@ Application.Globalization.Culture="zh" %> @@ -104,16 +104,16 @@ Lastly, you can change the globalization settings on page by page basis using localize                               function detailed below. To localize text in the template, use the TTranslate component.

                              Using localize function to translate text within PHP

                              -

                              The localize function searches for a translated string that matches original from your translation source. First, you need to locate all the hard coded text in PHP that are displayed or sent to the end user. The following example localizes the text of the $sender (assuming, say, the sender is a button). The original code before localization is as follows. - +

                              The localize function searches for a translated string that matches original from your translation source. First, you need to locate all the hard coded text in PHP that are displayed or sent to the end user. The following example localizes the text of the $sender (assuming, say, the sender is a button). The original code before localization is as follows. + function clickMe($sender,$param) { $sender->Text="Hello, world!"; } -

                              The hard coded message "Hello, world!" is to be localized using the localize function.

                              - +

                              The hard coded message "Hello, world!" is to be localized using the localize function.

                              + function clickMe($sender,$param) { $sender->Text=Prado::localize("Hello, world!"); @@ -122,60 +122,60 @@ function clickMe($sender,$param)

                              Compound Messages

                              -

                              Compound messages can contain variable data. For example, in the message "There are 12 users online.", the integer 12 may change depending on some data in your application. This is difficult to translate because the position of the variable data may be difference for different languages. In addition, different languages have their own rules for plurals (if any) and/or quantifiers. The following example can not be easily translated, because the sentence structure is fixed by hard coding the variable data within message.

                              - +

                              Compound messages can contain variable data. For example, in the message "There are 12 users online.", the integer 12 may change depending on some data in your application. This is difficult to translate because the position of the variable data may be difference for different languages. In addition, different languages have their own rules for plurals (if any) and/or quantifiers. The following example can not be easily translated, because the sentence structure is fixed by hard coding the variable data within message.

                              + $num_users = 12; $message = "There are " . $num_users . " users online."; This problem can be solved using the localize function with string substitution. For example, the $message string above can be constructed as follows. - + $num_users = 12; $message = Prado::localize("There are {num_users} users online.", array('num_users'=>$num_users)); -

                              Where the second parameter in localize takes an associative array with the key as the substitution to find in the text and replaced it with the associated value. +

                              Where the second parameter in localize takes an associative array with the key as the substitution to find in the text and replaced it with the associated value. The localize function does not solve the problem of localizing languages that have plural forms, the solution is to use TChoiceFormat.

                              -

                              The following sample demonstrates the basics of localization in PRADO.

                              +

                              The following sample demonstrates the basics of localization in PRADO.

                              I18N Components

                              TTranslate

                              -

                              Messages and strings can be localized in PHP or in templates. +

                              Messages and strings can be localized in PHP or in templates. To translate a message or string in the template, use TTranslate.

                              - + <com:TTranslate>Hello World</com:TTranslate> <com:TTranslate Text="Goodbye" /> -

                              TTranslate can also perform string substitution. +

                              TTranslate can also perform string substitution. The Parameters property can be use to add name values pairs for substitution. Substrings in the translation enclosed with "{" and "}" are consider as the parameter names during substitution lookup. The following example will substitute the substring "{time}" with the value of the parameter attribute "Parameters.time=<%= time() %>". - + <com:TTranslate Parameters.time=<%= time() %> > The time is {time}. </com:TTranslate> -

                              A short for TTranslate is also provided using the following syntax.

                              - +

                              A short for TTranslate is also provided using the following syntax.

                              + <%[string]%> -

                              where string will be translated to different languages according to the end-user's language preference. This syntax can be used with attribute values as well.

                              - +

                              where string will be translated to different languages according to the end-user's language preference. This syntax can be used with attribute values as well.

                              + <com:TLabel Text="<%[ Hello World! ]%>" />

                              TDateFormat

                              -

                              Formatting localized date and time is straight forward.

                              - +

                              Formatting localized date and time is straight forward.

                              + <com:TDateFormat Value="12/01/2005" /> -

                              The Pattern property accepts 4 predefined localized date patterns and 4 predefined localized time patterns. -

                                +

                                The Pattern property accepts 4 predefined localized date patterns and 4 predefined localized time patterns.

                                +
                                • fulldate
                                • longdate
                                • mediumdate
                                  • @@ -185,19 +185,20 @@ The time is {time}.
                                • mediumtime
                                • shorttime
                                +

                                The predefined can be used in any combination. If using a combined predefined pattern, the first pattern must be the date, followed by a space, and lastly the time pattern. For example, full date pattern with short time pattern. The actual ordering of the date-time and the actual pattern will be determine automatically from locale data specified by the Culture property.

                                - + <com:TDateFormat Pattern="fulldate shorttime" /> -

                                You can also specify a custom pattern using the following sub-patterns. +

                                You can also specify a custom pattern using the following sub-patterns. The date/time format is specified by means of a string time pattern. In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following: - + Symbol Meaning Presentation Example ------ ------- ------------ ------- G era designator (Text) AD @@ -222,29 +223,29 @@ The date/time format is specified by means of a string time pattern. In this pat

                                -

                                The count of pattern letters determine the format.

                                +

                                The count of pattern letters determine the format.

                                -

                                (Text): 4 letters uses full form, less than 4, use short or abbreviated form +

                                (Text): 4 letters uses full form, less than 4, use short or abbreviated form if it exists. (e.g., "EEEE" produces "Monday", "EEE" produces "Mon")

                                -

                                (Number): the minimum number of digits. Shorter numbers are zero-padded +

                                (Number): the minimum number of digits. Shorter numbers are zero-padded to this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits. (e.g., if "yyyy" produces "1997", "yy" produces "97".) Unlike other fields, fractional seconds are padded on the right with zero.

                                -

                                (Text and Number): 3 or over, use text, otherwise use number. (e.g., +

                                (Text and Number): 3 or over, use text, otherwise use number. (e.g., "M" produces "1", "MM" produces "01", "MMM" produces "Jan", and "MMMM" produces "January".)

                                -

                                Any characters in the pattern that are not in the ranges of ['a'..'z'] +

                                Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', and '@' will appear in the resulting time text even they are not embraced within single quotes.

                                -

                                Examples using the US locale: +

                                Examples using the US locale: - + Format Pattern Result -------------- ------- "yyyy.MM.dd G 'at' HH:mm:ss" ->> 1996.07.10 AD at 15:08:56 @@ -256,54 +257,55 @@ Format Pattern Result

                                -

                                If the Value property is not specified, the current date and time is used.

                                +

                                If the Value property is not specified, the current date and time is used.

                                TNumberFormat

                                -

                                PRADO's Internationalization framework provide localized currency formatting and number formatting. Please note that the TNumberFormat component provides formatting only, it does not perform current conversion or exchange.

                                +

                                PRADO's Internationalization framework provide localized currency formatting and number formatting. Please note that the TNumberFormat component provides formatting only, it does not perform current conversion or exchange.

                                -

                                Numbers can be formatted as currency, percentage, decimal or scientific -numbers by specifying the Type attribute. The valid types are: -

                                  +

                                  Numbers can be formatted as currency, percentage, decimal or scientific +numbers by specifying the Type attribute. The valid types are:

                                  +
                                  • currency
                                  • percentage
                                  • decimal
                                  • scientific
                                  -

                                  - + <com:TNumberFormat Type="currency" Value="100" /> -

                                  Culture and Currency properties may be specified to format locale specific numbers.

                                  +

                                  Culture and Currency properties may be specified to format locale specific numbers.

                                  -

                                  If someone from US want to see sales figures from a store in +

                                  If someone from US want to see sales figures from a store in Germany (say using the EURO currency), formatted using the german currency, you would need to use the attribute Culture="de_DE" to get the currency right, e.g. 100,00$. The decimal and grouping separator is then also from the de_DE locale. This may lead to some confusion because people from US uses the "," (comma) as thousand separator. Therefore a Currency attribute is available, so that the output from the following example results in $100.00 - + <com:TNumberFormat Type="currency" Culture="en_US" Currency="EUR" Value="100" />

                                  -

                                  The Pattern property determines the number of digits, thousand grouping +

                                  The Pattern property determines the number of digits, thousand grouping positions, the number of decimal points and the decimal position. The actual characters that are used to represent the decimal points and thousand points are culture specific and will change automatically according to the Culture property. The valid -Pattern characters are: -

                                    +Pattern characters are:

                                    +
                                    • # (hash) - represents the optional digits
                                    • 0 (zero) - represents the mandatory digits, zero left filled
                                    • . (full stop) - the position of the decimal point (only 1 decimal point is allowed)
                                    • , (comma) - thousand point separation (up to 2 commas are allowed)
                                    +

                                    For example, consider the Value="1234567.12345" and with Culture="en_US" (which uses "," for thousand point separator and "." for decimal separators). - +

                                    + Pattern Output ------- ------ ##,###.00 ->> 1,234,567.12 @@ -315,11 +317,11 @@ Pattern Output

                                    TTranslateParameter

                                    -

                                    Compound messages, i.e., string substitution, can be accomplished with TTranslateParameter. +

                                    Compound messages, i.e., string substitution, can be accomplished with TTranslateParameter. In the following example, the strings "{greeting}" and "{name}" will be replace with the values of "Hello" and "World", respectively.The substitution string must be enclose with "{" and "}". The parameters can be further translated by using TTranslate. - + <com:TTranslate> {greeting} {name}! <com:TTranslateParameter Key="name">World</com:TTranslateParameter> @@ -331,19 +333,19 @@ with the values of "Hello" and "World", respectively.The substitution string mus

                                    TChoiceFormat

                                    -

                                    Using the localize function or TTranslate component to translate messages does not inform the translator the cardinality of the data required to determine the correct plural structure to use. It only informs them that there is a variable data, the data could be anything. Thus, the translator will be unable to determine with respect to the substitution data the correct plural, language structure or phrase to use . E.g. in English, to translate the sentence, "There are {number} of apples.", the resulting translation should be different depending on the number of apples.

                                    +

                                    Using the localize function or TTranslate component to translate messages does not inform the translator the cardinality of the data required to determine the correct plural structure to use. It only informs them that there is a variable data, the data could be anything. Thus, the translator will be unable to determine with respect to the substitution data the correct plural, language structure or phrase to use . E.g. in English, to translate the sentence, "There are {number} of apples.", the resulting translation should be different depending on the number of apples.

                                    -

                                    The TChoiceFormat component performs message/string choice translation. The following example demonstrated a simple 2 choice message translation.

                                    +

                                    The TChoiceFormat component performs message/string choice translation. The following example demonstrated a simple 2 choice message translation.

                                    - + <com:TChoiceFormat Value="1"/>[1] One Apple. |[2] Two Apples</com:TChoiceFormat> -

                                    In the above example, the Value "1" (one), thus the translated string +

                                    In the above example, the Value "1" (one), thus the translated string is "One Apple". If the Value was "2", then it will show "Two Apples".

                                    -

                                    The message/string choices are separated by the pipe "|" followed by a set notation of the form.

                                    -
                                      +

                                      The message/string choices are separated by the pipe "|" followed by a set notation of the form.

                                      +
                                      • [1,2] -- accepts values between 1 and 2, inclusive.
                                      • (1,2) -- accepts values between 1 and 2, excluding 1 and 2.
                                      • {1,2,3,4} -- only values defined in the set are accepted.
                                        • @@ -351,7 +353,7 @@ is "One Apple". If the Value was "2", then it will show "Two Apples".
                                      -

                                      Any non-empty combinations of the delimiters of square and round brackets are acceptable. +

                                      Any non-empty combinations of the delimiters of square and round brackets are acceptable. The string chosen for display depends on the Value property. The Value is evaluated for each set until the Value is found to belong to a particular set.

                                      diff --git a/demos/quickstart/protected/pages/Advanced/Logging.page b/demos/quickstart/protected/pages/Advanced/Logging.page index 9c7ec15e..d5a13da2 100644 --- a/demos/quickstart/protected/pages/Advanced/Logging.page +++ b/demos/quickstart/protected/pages/Advanced/Logging.page @@ -1,36 +1,36 @@

                                      Logging

                                      -

                                      +

                                      PRADO provides a highly flexible and extensible logging functionality. Messages logged can be classified according to log levels and message categories. Using level and category filters, the messages can be further routed to different destinations, such as files, emails, browser windows, etc. The following diagram shows the basic architecture of PRADO logging mechanism,

                                      Log router

                                      Using Logging Functions

                                      -

                                      +

                                      The following two methods are provided for logging messages in PRADO,

                                      - + Prado::log($message, $logLevel, $category); Prado::trace($message, $category); -

                                      +

                                      The difference between Prado::log() and Prado::trace() is that the latter automatically selects the log level according to the application mode. If the application is in Debug mode, stack trace information is appended to the messages. Prado::trace() is widely used in the core code of the PRADO framework.

                                      Message Routing

                                      -

                                      +

                                      Messages logged using the above two functions are kept in memory. To make use of the messages, developers need to route them to specific destinations, such as files, emails, or browser windows. The message routing is managed by System.Util.TLogRouter module. When plugged into an application, it can route the messages to different destination in parallel. Currently, PRADO provides three types of routes:

                                      -
                                        +
                                        • TFileLogRoute - filtered messages are stored in a specified log file. By default, this file is named prado.log under the runtime directory of the application. File rotation is provided.
                                        • TEmailLogRoute - filtered messages are sent to pre-specified email addresses.
                                        • TBrowserLogRoute - filtered messages are appended to the end of the current page output.
                                        -

                                        +

                                        To enable message routing, plug in and configure the TLogRouter module in application configuration,

                                        - + <module id="log" class="System.Util.TLogRouter"> <route class="TBrowserLogRoute" Levels="Info" @@ -40,21 +40,21 @@ To enable message routing, plug in and configure the TLogRouter module Categories="System.Web" /> </module> -

                                        +

                                        In the above, the Levels and Categories specify the log and category filters to selectively retrieve the messages to the corresponding destinations.

                                        Message Filtering

                                        -

                                        +

                                        Messages can be filtered according to their log levels and categories. Each log message is associated with a log level and a category. With levels and categories, developers can selectively retrieve messages that they are interested on.

                                        -

                                        +

                                        Log levels defined in System.Util.TLogger include : DEBUG, INFO, NOTICE, WARNING, ERROR, ALERT, FATAL. Messages can be filtered according log level criteria. For example, if a filter specifies WARNING and ERROR levels, then only those messages that are of WARNING and ERROR will be returned.

                                        -

                                        +

                                        Message categories are hierarchical. A category whose name is the prefix of another is said to be the ancestor category of the other category. For example, System.Web category is the ancestor of System.Web.UI and System.Web.UI.WebControls categories. Messages can be selectively retrieved using such hierarchical category filters. For example, if the category filter is System.Web, then all messages in the System.Web are returned. In addition, messages in the child categories, such as System.Web.UI.WebControls, are also returned.

                                        -

                                        +

                                        By convention, the messages logged in the core code of PRADO are categorized according to the namespace of the corresponding classes. For example, messages logged in TPage will be of category System.Web.UI.TPage.

                                        diff --git a/demos/quickstart/protected/pages/Advanced/MasterContent.page b/demos/quickstart/protected/pages/Advanced/MasterContent.page index b0836393..ee99b144 100644 --- a/demos/quickstart/protected/pages/Advanced/MasterContent.page +++ b/demos/quickstart/protected/pages/Advanced/MasterContent.page @@ -1,16 +1,16 @@

                                        Master and Content

                                        -

                                        +

                                        Pages in a Web application often share common portions. For example, all pages of this tutorial application share the same header and footer portions. If we repeatedly put header and footer in every page source file, it will be a maintenance headache if in future we want to something in the header or footer. To solve this problem, PRADO introduces the concept of master and content. It is essentially a decorator pattern, with content being decorated by master.

                                        -

                                        +

                                        Master and content only apply to template controls (controls extending TTemplateControl or its child classes). A template control can have at most one master control and one or several contents (each represented by a TContent control). Contents will be inserted into the master control at places reserved by TContentPlaceHolder controls. And the presentation of the template control is that of the master control with TContentPlaceHolder replaced by TContent.

                                        -

                                        +

                                        For example, assume a template control has the following template:

                                        - + <%@ MasterClass="MasterControl" %> <com:TContent ID="A" > content A @@ -22,10 +22,10 @@ content B content B </com:TContent > -

                                        +

                                        which uses MasterControl as its master control. The master control has the following template,

                                        - + other stuff <com:TContentPlaceHolder ID="A" /> other stuff @@ -34,23 +34,23 @@ other stuff <com:TContentPlaceHolder ID="C" /> other stuff -

                                        +

                                        Then, the contents are inserted into the master control according to the following diagram, while the resulting parent-child relationship can be shown in the next diagram. Note, the template control discards everything in the template other than the contents, while the master control keeps everything and replaces the content placeholders with the contents according to ID matching.

                                        alt="Master and Content" /> alt="Parent-child relationship between master and content" />

                                        Master vs. External Template

                                        -

                                        +

                                        Master is very similar to external templates which are introduced since version 3.0.5. A special include tag is used to include an external template file into a base template.

                                        -

                                        +

                                        Both master and external template can be used to share common contents among pages. A master is a template control whose template contains the common content and whose class file contains the logic associated with the master. An external template, on the other hand, is a pure template file without any class files.

                                        -

                                        +

                                        Therefore, use master control if the common content has to be associated with some logic, such as a page header with search box or login box. A master control allows you to specify how the common content should interact with end users. If you use external templates, you will have to put the needed logic in the page or control class who owns the base template.

                                        -

                                        +

                                        Performancewise, external template is lighter than master as the latter is a self-contained control participating the page lifecycles, while the former is used only when the template is being parsed.

                                        diff --git a/demos/quickstart/protected/pages/Advanced/Performance.page b/demos/quickstart/protected/pages/Advanced/Performance.page index d33c110b..18465fca 100644 --- a/demos/quickstart/protected/pages/Advanced/Performance.page +++ b/demos/quickstart/protected/pages/Advanced/Performance.page @@ -1,27 +1,27 @@

                                        Performance Tuning

                                        -

                                        +

                                        Performance of Web applications is affected by many factors. Database access, file system operations, network bandwidth are all potential affecting factors. PRADO tries in every effort to reduce the performance impact caused by the framework.

                                        Caching

                                        -

                                        +

                                        PRADO provides a generic caching technique used by in several core parts of the framework. For example, when caching is enabled, TTemplateManager will save parsed templates in cache and reuse them in the following requests, which saves time for parsing templates. The TThemeManager adopts the similar strategy to deal with theme parsing.

                                        -

                                        +

                                        Enabling caching is very easy. Simply add the cache module in the application configuration, and PRADO takes care of the rest.

                                        - + <modules> <module id="cache" class="System.Caching.TSqliteCache" /> </modules> -

                                        +

                                        Developers can also take advantage of the caching technique in their applications. The Cache property of TApplication returns the plugged-in cache module when it is available. To save and retrieve a data item in cache, use the following commands,

                                        - + if($application->Cache) { // saves data item in cache $application->Cache->set($keyName,$dataItem); @@ -29,55 +29,55 @@ if($application->Cache) { $dataItem=$application->Cache->get($keyName); } -

                                        +

                                        where $keyName should be a string that uniquely identifies the data item stored in cache.

                                        Using pradolite.php

                                        -

                                        +

                                        Including many PHP script files may impact application performance significantly. PRADO classes are stored in different files and when processing a page request, it may require including tens of class files.To alleviate this problem, in each PRADO release, a file named pradolite.php is also included. The file is a merge of all core PRADO class files with comments being stripped off and message logging removed.

                                        -

                                        +

                                        To use pradolite.php, in your application entry script, replace the inclusion of prado.php with pradolite.php.

                                        Changing Application Mode

                                        -

                                        +

                                        Application mode also affects application performance. A PRADO application can be in one of the following modes: Off, Debug, Normal and Performance. The Debug mode should mainly be used during application development, while Normal mode is usually used in early stage after an application is deployed to ensure everything works correctly. After the application is proved to work stably for some period, the mode can be switched to Performance to further improve the performance.

                                        -

                                        +

                                        The difference between Debug, Normal and Performance modes is that under Debug mode, application logs will contain debug information, and under Performance mode, timestamp checking is not performed for cached templates and published assets. Therefore, under Performance mode, application may not run properly if templates or assets are modified. Since Performance mode is mainly used when an application is stable, change of templates or assets are not likely.

                                        -

                                        +

                                        To switch application mode, configure it in application configuration:

                                        - + <application Mode="Performance" > ...... </application >

                                        Reducing Page Size

                                        -

                                        +

                                        By default, PRADO stores page state in hidden fields of the HTML output. The page state could be very large in size if complex controls, such as TDataGrid, is used. To reduce the size of the network transmitted page size, two strategies can be used.

                                        -

                                        +

                                        First, you may disable viewstate by setting EnableViewState to false for the page or some controls on the page if they do not need user interactions. Viewstate is mainly used to keep track of page state when a user interacts with that page/control.

                                        -

                                        +

                                        Second, you may use a different page state storage. For example, page state may be stored in session, which essentially stores page state on the server side and thus saves the network transmission time. The StatePersisterClass property of the page determines which state persistence class to use. By default, it uses System.Web.UI.TPageStatePersister to store persistent state in hidden fields. You may modify this property to a persister class of your own, as long as the new persister class implements the IPageStatePersister interface. You may configure this property in several places, such as application configuration or page configuration using <pages> or <page> tags,

                                        - + <pages StatePersisterClass="MyPersister1" ... > <page ID="SpecialPage" StatePersisterClass="MyPersister2" ... /> </pages> -

                                        +

                                        Note, in the above the SpecialPage will use MyPersister2 as its persister class, while the rest pages will use MyPersister1. Therefore, you can have different state persister strategies for different pages.

                                        Other Techniques

                                        -

                                        +

                                        Server caching techniques are proven to be very effective in improving the performance of PRADO applications. For example, we have observed that by using Zend Optimizer, the RPS (request per second) of a PRADO application can be increased by more than ten times. Of course, this is at the cost of stale output, while PRADO's caching techniques always ensure the correctness of the output.

                                        diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.de.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.de.page index 159c5d54..343df6d6 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.de.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.de.page @@ -25,7 +25,7 @@ Weiter mit dem Thema kulturell angepasster Templates. Text kann unter Zuhilfenah
                                        Nachfolgender Prozess der Übersetzung und Anpassung eines Produktes an die kulturellen Konventionen eines gegebenen Marktes.

                                        Die folgenden Merkmale werden von PRADO unterstützt:

                                        -

                            Include Tags

                            -

                            +

                            Since version 3.0.5, PRADO starts to support external template inclusion. This is accomplished via include tags, where external template files are specified in namespace format and their file name must be terminated as .tpl.

                            - + <%include path.to.templateFile %> -

                            +

                            External templates will be inserted at the places where the include tags occur in the base template.

                            -

                            +

                            Note, nested template inclusion is not supported, i.e., you cannot have include tags in an external template.

                            diff --git a/demos/quickstart/protected/pages/Configurations/Templates2.page b/demos/quickstart/protected/pages/Configurations/Templates2.page index 201c526f..e7cb46f5 100644 --- a/demos/quickstart/protected/pages/Configurations/Templates2.page +++ b/demos/quickstart/protected/pages/Configurations/Templates2.page @@ -3,42 +3,42 @@

                            Dynamic Content Tags

                            -

                            +

                            Dynamic content tags are introduced as shortcuts to some commonly used component tags. These tags are mainly used to render contents resulted from evaluating some PHP expressions or statements. They include expression tags, statement tags, databind tags, parameter tags, asset tags and localization tags.

                            Expression Tags

                            -

                            +

                            An expression tag represents a PHP expression that is evaluated when the template control is in PreRender stage. The expression evaluation result is inserted at the place where the tag resides in the template. The context (namely $this) of the expression is the control owning the template.

                            -

                            +

                            The format of an expression tag is as follows,

                            - + <%= PhpExpression %> -

                            +

                            For example, the following expression tag will display the current page title at the place,

                            - + <%= $this->Title %>

                            Statement Tags

                            -

                            +

                            Statement tags are similar to expression tags, except that statement tags contain PHP statements rather than expressions. The output of the PHP statements (using for example echo or print in PHP) are displayed at the place where the statement tag resides in the template. The context (namely $this) of the statements is the control owning the template. The format of statement tags is as follows,

                            - + <%% PHP Statements %> -

                            +

                            The following example displays the current time in Dutch at the place,

                            - + <%% setlocale(LC_ALL, 'nl_NL'); echo strftime("%A %e %B %Y",time()); @@ -47,52 +47,52 @@ echo strftime("%A %e %B %Y",time());

                            Databind Tags

                            -

                            +

                            Databind tags are similar to expression tags, except that the expressions are evaluated only when a dataBind() call is invoked on the controls representing the databind tags. The context (namely $this) of a databind expression is the control owning the template. The format of databind tags is as follows,

                            - + <%# PhpExpression %>

                            Parameter Tags

                            -

                            +

                            Parameter tags are used to insert application parameters at the place where they appear in the template. The format of parameter tags is as follows,

                            - + <%$ ParameterName %> -

                            +

                            Note, application parameters are usually defined in application configurations or page directory configurations. The parameters are evaluated when the template is instantiated.

                            Asset Tags

                            -

                            +

                            Asset tags are used to publish private files and display the corresponding the URLs. For example, if you have an image file that is not Web-accessible and you want to make it visible to end-users, you can use asset tags to publish this file and show the URL to end-users so that they can fetch the published image.

                            -

                            +

                            The format of asset tags is as follows,

                            - + <%~ LocalFileName %> -

                            +

                            where LocalFileName refers to a file path that is relative to the directory containing the current template file. The file path can be a single file or a directory. If the latter, the content in the whole directory will be made accessible by end-users.

                            -

                            +

                            BE VERY CAUTIOUS when you are using asset tags as it may expose to end-users files that you probably do not want them to see.

                            Localization Tags

                            -

                            +

                            Localization tags represent localized texts. They are in the following format,

                            - + <%[string]%> -

                            +

                            where string will be translated to different languages according to the end-user's language preference. Localization tags are in fact shortcuts to the function call Prado::localize(string).

                            diff --git a/demos/quickstart/protected/pages/Configurations/Templates3.page b/demos/quickstart/protected/pages/Configurations/Templates3.page index bc3b1f87..38391e9c 100644 --- a/demos/quickstart/protected/pages/Configurations/Templates3.page +++ b/demos/quickstart/protected/pages/Configurations/Templates3.page @@ -3,51 +3,51 @@

                            Dynamic Property Tags

                            -

                            +

                            Dynamic property tags are very similar to dynamic content tags, except that they are applied to component properties. The purpose of dynamic property tags is to allow more versatile component property configuration. Note, you are not required to use dynamic property tags because what can be done using dynamic property tags can also be done in PHP code. However, using dynamic property tags bring you much more convenience at accomplishing the same tasks. The basic usage of dynamic property tags is as follows,

                            - + <com:ComponentType PropertyName=DynamicPropertyTag ...> body content </com:ComponentType> -

                            +

                            where you may enclose DynamicPropertyTag within single or double quotes for better readability.

                            -

                            +

                            Like dynamic content tags, we have expression tags, databind tags, parameter tags, asset tags and localization tags. (Note, there is no statement tag here.)

                            Expression Tags

                            -

                            +

                            An expression tag represents a PHP expression that is evaluated when the control is in PreRender stage. The expression evaluation result is assigned to the corresponding component property. The format of expression tags is as follows,

                            - + <%= PhpExpression %> -

                            +

                            In the expression, $this refers to the control owning the template. The following example specifies a TLabel control whose Text property is initialized as the current page title when the TLabel control is being constructed,

                            - + <com:TLabel Text=<%= $this->Page->Title %> />

                            Databind Tags

                            -

                            +

                            Databind tags are similar to expression tags, except that they can only be used with control properties and the expressions are evaluated only when a dataBind() call is invoked on the controls represented by the component tags. In the expression, $this refers to the control owning the template. Databind tags do not apply to all components. They can only be used for controls.

                            -

                            +

                            The format of databind tags is as follows,

                            - + <%# PhpExpression %> -

                            +

                            Since v3.0.2, expression tags and databind tags can be embedded within static strings. For example, you can write the following in a template,

                            - + <com:TLabel> <prop:Text> Today is <%= date('F d, Y',time()) >. @@ -55,49 +55,49 @@ Since v3.0.2, expression tags and databind tags can be embedded within static st </prop:Text> </com:TLabel> -

                            +

                            Previously, you would have to use a single expression with string concatenations to achieve the same effect.

                            Parameter Tags

                            -

                            +

                            Parameter tags are used to assign application parameter values to the corresponding component properties. The format of parameter tags is as follows,

                            - + <%$ ParameterName %> -

                            +

                            Note, application parameters are usually defined in application configurations or page directory configurations. The parameters are evaluated when the template is instantiated.

                            Asset Tags

                            -

                            +

                            Asset tags are used to publish private files and assign the corresponding the URLs to the component properties. For example, if you have an image file that is not Web-accessible and you want to make it visible to end-users, you can use asset tags to publish this file and show the URL to end-users so that they can fetch the published image. The asset tags are evaluated when the template is instantiated.

                            -

                            +

                            The format of asset tags is as follows,

                            - + <%~ LocalFileName %> -

                            +

                            where LocalFileName refers to a file path that is relative to the directory containing the current template file. The file path can be a single file or a directory. If the latter, the content in the whole directory will be made accessible by end-users.

                            -

                            +

                            BE VERY CAUTIOUS when you are using asset tags as it may expose to end-users files that you probably do not want them to see.

                            Localization Tags

                            -

                            +

                            Localization tags represent localized texts. They are in the following format,

                            - + <%[string]%> -

                            +

                            where string will be translated to different languages according to the end-user's language preference. The localization tags are evaluated when the template is instantiated. Localization tags are in fact shortcuts to the function call Prado::localize(string).

                            diff --git a/demos/quickstart/protected/pages/Configurations/UrlMapping.page b/demos/quickstart/protected/pages/Configurations/UrlMapping.page index 20954c24..a8ea3ace 100644 --- a/demos/quickstart/protected/pages/Configurations/UrlMapping.page +++ b/demos/quickstart/protected/pages/Configurations/UrlMapping.page @@ -4,12 +4,12 @@ -

                            Using the TUrlMapping module different URLs can be +

                            Using the TUrlMapping module different URLs can be mapped into any existing Prado pages or services. This allows the application to use nice looking and friendly URLs.

                            -

                            +

                            The TUrlMapping module allows aributary URL path to be mapped to a particular service and page class. This module must be configured before a service is initialized, thus this module should be configured @@ -25,9 +25,9 @@ This usually means delcaring the TUrlMapping module before any Specifying the mappings in the per directory config.xml is not supported. -

                            +

                            To use TUrlMapping, one must set the UrlManager property of the THttpRequest module as the TUrlMapping module ID. See following for an example, - + @@ -39,25 +39,25 @@ To use TUrlMapping, one must set the UrlManager property of th

                            -

                            +

                            The above example is part of the application configuration of the blog demo in the PRADO release. It enables recognition of the following URL formats:

                            -
                              +
                              • /index.php/post/123 is recognized as /index.php?page=Posts.ViewPost&id=123
                              • /index.php/archive/200605 is recognized as /index.php?page=Posts.ListPost&time=200605
                              • /index.php/category/2 is recognized as /index.php?page=Posts.ListPost&cat=2
                              -

                              +

                              The ServiceParameter and ServiceID (the default ID is 'page') set the service parameter and service ID, respectively, of the Request module. The service parameter for the TPageService service is the Page class name, e.g., for an URL "index.php?page=Home", "page" is the service ID and the service parameter is "Home". Other services may use the service parameter and ID differently. See Services for further details.

                              -

                              Specifying URL Patterns

                              -

                              +

                              Specifying URL Patterns

                              +

                              TUrlMapping enables recognition of customized URL formats based on a list prespecified of URL patterns. Each pattern is specified in a <url> tag.

                              -

                              +

                              The Pattern and Parameters attribute values are regular expression patterns that determine the mapping criteria. The Pattern property takes @@ -65,20 +65,20 @@ a regular expression with parameter names enclosed between a left brace '{}'. The pattens for each parameter can be set using Parametersattribute collection. For example, - +

                              The example is equivalent to the following regular expression (it uses the "named group" feature in regular expressions available in PHP): - + \d{4})\/(?P\d{2})\/(?P\d+)/u ]]> -

                              +

                              In the above example, the pattern contains 3 parameters named "year", "month" and "day". The pattern for these parameters are, respectively, "\d{4}" (4 digits), "\d{2}" (2 digits) @@ -92,7 +92,7 @@ to form a complete regular expression string. property you need to escape the slash in regular expressions. -

                              Following from the above pattern example, +

                              Following from the above pattern example, an URL "http://example.com/index.php/articles/2006/07/21" will be matched and valid. However, "http://example.com/index.php/articles/2006/07/hello" is not valid since the "day" parameter pattern is not satisfied. @@ -101,19 +101,19 @@ and valid. However, "http://example.com/index.php/articles/2006/07/hello/index.php/articles/2006/07/21" portion of the URL is considered.

                              -

                              +

                              The mapped request URL is equivalent to index.php?page=ArticleView&year=2006&month=07&day=21. The request parameter values are available through the standard Request object. For example, $this->Request['year'].

                              -

                              The URL mapping are evaluated in order they are place and only the first mapping that matches +

                              The URL mapping are evaluated in order they are place and only the first mapping that matches the URL will be used. Cascaded mapping can be achieved by placing the URL mappings in particular order. For example, placing the most specific mappings first.

                              -

                              Constructing Customized URLs

                              -

                              +

                              Constructing Customized URLs

                              +

                              Since version 3.0.6, TUrlMapping starts to support constructing customized URL formats. This is achieved by allowing users to extend TUrlMapping class and override the constructUrl method. In the applications, users can still use THttpRequest.constructUrl() or TPageService.constructUrl() to generate PRADO-recognizable URLS. The actual URL construction work is ultimately delegated to the TUrlMapping.constructUrl(), provided it is implemented.

                              diff --git a/demos/quickstart/protected/pages/Controls/Button.page b/demos/quickstart/protected/pages/Controls/Button.page index 37b90062..c145a4df 100644 --- a/demos/quickstart/protected/pages/Controls/Button.page +++ b/demos/quickstart/protected/pages/Controls/Button.page @@ -3,10 +3,10 @@

                              TButton

                              -

                              +

                              TButton creates a click button on a Web page. The button's caption is specified by Text property. A button is used to submit data to a page. TButton raises two server-side events, OnClick and OnCommand, when it is clicked on the client-side. The difference between OnClick and OnCommand events is that the latter event is bubbled up to the button's ancestor controls. An OnCommand event handler can use CommandName and CommandParameter associated with the event to perform specific actions.

                              -

                              +

                              Clicking on button can trigger form validation, if CausesValidation is true. And the validation may be restricted within a certain group of validator controls according to ValidationGroup.

                              diff --git a/demos/quickstart/protected/pages/Controls/CheckBox.page b/demos/quickstart/protected/pages/Controls/CheckBox.page index 7f2767c0..54417320 100644 --- a/demos/quickstart/protected/pages/Controls/CheckBox.page +++ b/demos/quickstart/protected/pages/Controls/CheckBox.page @@ -3,10 +3,10 @@

                              TCheckBox

                              -

                              +

                              TCheckBox displays a check box on a Web page. A caption can be specified via Text and displayed beside the check box. It can appear either on the right or left of the check box, which is determined by TextAlign. You may further specify attributes applied to the text by using LabelAttributes.

                              -

                              +

                              To determine whether the check box is checked, test the Checked property. A CheckedChanged event is raised if the state of Checked is changed between posts to the server. If AutoPostBack is true, changing the check box state will cause postback action. And if CausesValidation is also true, upon postback validation will be performed for validators within the specified ValidationGroup.

                              diff --git a/demos/quickstart/protected/pages/Controls/ClientScript.page b/demos/quickstart/protected/pages/Controls/ClientScript.page index d5687fb1..5b2147ec 100644 --- a/demos/quickstart/protected/pages/Controls/ClientScript.page +++ b/demos/quickstart/protected/pages/Controls/ClientScript.page @@ -3,7 +3,7 @@

                              TClientScript

                              Including Bundled Javascript Libraries in Prado

                              -

                              +

                              TClientScript allows Javascript code to be insert or linked to the page template. PRADO is bundled with a large library of Javascript functionality including effects, AJAX, basic event handlers, and many others. The bundled @@ -12,13 +12,13 @@ Javascript libraries can be linked to the current page template using the can be specified using comma delimited string of the name of Javascript library to include on the page. For following example will include the "ajax" and "effects" library.

                              - + <com:TClientScript PradoScripts="ajax, effects" /> -

                              - The available bundled libraries included in Prado are -

                                +

                                + The available bundled libraries included in Prado are

                                +
                                • prado : basic prado javascript framework based on Prototype
                                • effects : visual effects from script.aculo.us
                                • ajax : ajax and callback related based on Prototype
                                  • @@ -28,25 +28,24 @@ to include on the page. For following example will include the "ajax" and "effec
                                • rico : Rico library
                                • colorpicker : colorpicker
                                -

                                -

                                The dependencies for each library are automatically resolved. That is, +

                                The dependencies for each library are automatically resolved. That is, specifying, say the "ajax", will also include the "prado" library.

                                Including Custom Javascript Files

                                -

                                Custom Javascript files can be register using the ScriptUrl property. +

                                Custom Javascript files can be register using the ScriptUrl property. The following example includes the Javascript file "test.js" to the page. In this case, the file "test.js" is relative the current template you are using. Since the property value is dynamic asset tag, the file "test.js" will be published automatically, that is, the file will be copied to the assets directory if necessary.

                                - + <com:TClientScript ScriptUrl=<%~ test.js %> /> -

                                You can include Javascript files from other servers by specifying the full URL string in +

                                You can include Javascript files from other servers by specifying the full URL string in the ScriptUrl property.

                                Including Custom Javascript Code Blocks

                                -

                                Any content within the TClientScript control tag will be considered as +

                                Any content within the TClientScript control tag will be considered as Javascript code and will be rendered where it is declared.

                                \ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/ColorPicker.page b/demos/quickstart/protected/pages/Controls/ColorPicker.page index 8909ad98..e0de6712 100644 --- a/demos/quickstart/protected/pages/Controls/ColorPicker.page +++ b/demos/quickstart/protected/pages/Controls/ColorPicker.page @@ -3,7 +3,7 @@

                                TColorPicker

                                -

                                +

                                TBD

                                diff --git a/demos/quickstart/protected/pages/Controls/Data.page b/demos/quickstart/protected/pages/Controls/Data.page index 6a93ec6f..aea25ab7 100644 --- a/demos/quickstart/protected/pages/Controls/Data.page +++ b/demos/quickstart/protected/pages/Controls/Data.page @@ -2,7 +2,7 @@

                                Data Controls

                                -
                                  +
                                  • TDataList is used to display or modify a list of data items.
                                    • diff --git a/demos/quickstart/protected/pages/Controls/DataGrid.page b/demos/quickstart/protected/pages/Controls/DataGrid.page index 4697d0e5..83b5c3cf 100644 --- a/demos/quickstart/protected/pages/Controls/DataGrid.page +++ b/demos/quickstart/protected/pages/Controls/DataGrid.page @@ -2,24 +2,24 @@

                                    TDataGrid

                                    -

                                    +

                                    TDatagrid is an important control in building complex Web applications. It displays data in a tabular format with rows (also called items) and columns. A row is composed by cells, while columns govern how cells should be displayed according to their association with the columns. Data specified via DataSource or DataSourceID are bound to the rows and feed contents to cells.

                                    -

                                    +

                                    TDataGrid is highly interactive. Users can sort the data along specified columns, navigate through different pages of the data, and perform actions, such as editing and deleting, on rows of the data.

                                    -

                                    +

                                    Rows of TDataGrid can be accessed via its Items property. A row (item) can be in one of several modes: browsing, editing and selecting, which affects how cells in the row are displayed. To change an item's mode, modify EditItemIndex or SelectedItemIndex. Note, if an item is in edit mode, then selecting this item will have no effect.

                                    Columns

                                    -

                                    +

                                    Columns of a data grid determine how the associated cells are displayed. For example, cells associated with a TBoundColumn are displayed differently according to their modes. A cell is displayed as a static text if the cell is in browsing mode, a text box if it is in editing mode, and so on.

                                    -

                                    +

                                    PRADO provides five types of columns:

                                    -
                                      +
                                      • TBoundColumn associates cells with a specific field of data and displays the cells according to their modes.
                                      • TLiteralColumn associates cells with a specific field of data and displays the cells with static texts.
                                      • TCheckBoxColumn associates cells with a specific field of data and displays in each cell a checkbox whose check state is determined by the data field value.
                                        • @@ -31,18 +31,18 @@ PRADO provides five types of columns:

                                      Item Styles

                                      -

                                      +

                                      TDataGrid defines different styles applied to its items. For example, AlternatingItemStyle is applied to alternating items (item 2, 4, 6, etc.) Through these properties, one can set CSS style fields or CSS classes for the items.

                                      -

                                      +

                                      Item styles are applied in a hierarchical way. Styles in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, ItemStyle, AlternatingItemStyle, SelectedItemStyle, and EditItemStyle. Therefore, if background color is set as red in ItemStyle, EditItemStyle will also have red background color, unless it is explicitly set to a different value.

                                      Events

                                      -

                                      +

                                      TDataGrid provides several events to facilitate manipulation of its items,

                                      -
                                        +
                                        • OnItemCreated - raised each time an item is newly created. When the event is raised, data and child controls are both available for the new item.
                                        • OnItemDataBound - raised each time an item just completes databinding. When the event is raised, data and child controls are both available for the item, and the item has finished databindings of itself and all its child controls.
                                        • OnItemCommand - raised when a child control of some item (such as a TButton) raises an OnCommand event.
                                          • @@ -62,13 +62,13 @@ TDataGrid provides several events to facilitate manipulation of its items,

                                          Using TDataGrid

                                          Automatically Generated Columns

                                          -

                                          +

                                          TDataGrid by default will create a list of columns based on the structure of the bound data. TDataGrid will read the first row of the data, extract the field names of the row, and construct a column for each field. Each column is of type TBoundColumn.

                                          -

                                          +

                                          The following example displays a list of computer product information using a TDataGrid. Columns are automatically generated. Pay attention to how item styles are specified and inherited. The data are populated into the datagrid using the follow code, which is common among most datagrid applications,

                                          - + public function onLoad($param) { parent::onLoad($param); if(!$this->IsPostBack) { @@ -80,13 +80,13 @@ public function onLoad($param) {

                                          Manually Specified Columns

                                          -

                                          +

                                          Using automatically generated columns gives a quick way of browsing tabular data. In real applications, however, automatically generated columns are often not sufficient because developers have no way customizing their appearance. Manually specified columns are thus more desirable.

                                          -

                                          +

                                          To manually specify columns, set AutoGenerateColumns to false, and specify the columns in a template like the following,

                                          - + <com:TDataGrid ...> <com:TBoundColumn DataField="name" .../> <com:TBoundColumn DataField="price" .../> @@ -94,78 +94,78 @@ To manually specify columns, set AutoGenerateColumns to false, and spec ... </com:TDataGrid> -

                                          +

                                          Note, if AutoGenerateColumns is true and there are manually specified columns, the automatically generated columns will be appended to the manually specified columns. Also note, the datagrid's Columns property contains only manually specified columns and no automatically generated ones.

                                          -

                                          +

                                          The following example uses manually specified columns to show a list of book information,

                                          -
                                            +
                                            • Book title - displayed as a hyperlink pointing to the corresponding amazon.com book page. THyperLinkColumn is used.
                                            • Publisher - displayed as a piece of text using TBoundColumn.
                                            • Price - displayed as a piece of text using TBoundColumn with output formatting string and customized styles.
                                            • In-stock or not - displayed as a checkbox using TCheckBoxColumn.
                                            • Rating - displayed as an image using TTemplateColumn which allows maximum freedom in specifying cell contents.
                                            -

                                            Pay attention to how item (row) styles and column styles cooperate together to affect the appearance of the cells in the datagrid.

                                            +

                                            Pay attention to how item (row) styles and column styles cooperate together to affect the appearance of the cells in the datagrid.

                                            Interacting with TDataGrid

                                            -

                                            +

                                            Besides the rich data presentation functionalities as demonstrated in previous section, TDataGrid is also highly user interactive. An import usage of TDataGrid is editing or deleting rows of data. The TBoundColumn can adjust the associated cell presentation according to the mode of datagrid items. When an item is in browsing mode, the cell is displayed with a static text; when the item is in editing mode, a textbox is displayed to collect user inputs. TDataGrid provides TEditCommandColumn for switching item modes. In addition, TButtonColumn offers developers the flexibility of creating arbitrary buttons for various user interactions.

                                            -

                                            +

                                            The following example shows how to make the previous book information table an interactive one. It allows users to edit and delete book items from the table. Two additional columns are used in the example to allow users interact with the datagrid: TEditCommandColumn and TButtonColumn. In addition, TDropDownListColumn replaces the previous TTemplateColumn to allow users to select a rating from a dropdown list. Note, it is also possible to use TTemplateColumn to achieve the same task.

                                            Sorting

                                            -

                                            +

                                            TDataGrid supports sorting its items according to specific columns. To enable sorting, set AllowSorting to true. This will turn column headers into clickable buttons if their SortExpression property is not empty. When users click on the header buttons, an OnSortCommand event will be raised. Developers can write handlers to respond to the sort command and sort the data according to SortExpression which is specified in the corresponding column.

                                            -

                                            +

                                            The following example turns the datagrid in Example 2 into a sortable one. Users can click on the link button displayed in the header of any column, and the data will be sorted in ascending order along that column.

                                            Paging

                                            -

                                            +

                                            When dealing with large datasets, paging is helpful in reducing the page size and complexity. TDataGrid has an embedded pager that allows users to specify which page of data they want to see. The pager can be customized via PagerStyle. For example, PagerStyle.Visible determines whether the pager is visible or not; PagerStyle.Position indicates where the pager is displayed; and PagerStyle.Mode specifies what type of pager is displayed, a numeric one or a next-prev one.

                                            -

                                            +

                                            To enable paging, set AllowPaging to true. The number of rows of data displayed in a page is specified by PageSize, while the index (zero-based) of the page currently showing to users is by CurrentPageIndex. When users click on a pager button, TDataGrid raises OnPageIndexChanged event. Typically, the event handler is written as follows,

                                            - + public function pageIndexChanged($sender,$param) { $this->DataGrid->CurrentPageIndex=$param->NewPageIndex; $this->DataGrid->DataSource=$this->Data; $this->DataGrid->dataBind(); } -

                                            +

                                            The following example enables the paging functionality of the datagrid shown in Example 1. In this example, you can set various pager styles interactively to see how they affect the pager display.

                                            Custom Paging

                                            -

                                            +

                                            The paging functionality shown above requires loading all data into memory, even though only a portion of them is displayed in a page. For large datasets, this is inefficient and may not always be feasible. TDataGrid provides custom paging to solve this problem. Custom paging only requires the portion of the data to be displayed to end users.

                                            -

                                            +

                                            To enable custom paging, set both AllowPaging and AllowCustomPaging to true. Notify TDataGrid the total number of data items (rows) available by setting VirtualItemCount. And respond to the OnPageIndexChanged event. In the event handler, use the NewPageIndex property of the event parameter to fetch the new page of data from data source. For MySQL database, this can be done by using LIMIT clause in an SQL select statement.

                                            Extending TDataGrid

                                            -

                                            +

                                            Besides traditional class inheritance, extensibility of TDataGrid is mainly through developing new datagrid column components. For example, one may want to display an image column. He may use TTemplateColumn to accomplish this task. A better solution is to develop an image column component so that the work can be reused easily in other projects.

                                            -

                                            +

                                            All datagrid column components must inherit from TDataGridColumn. The main method that needs to be overridden is initializeCell() which creates content for cells in the corresponding column. Since each cell is also in an item (row) and the item can have different types (such as Header, AltneratingItem, etc.), different content may be created according to the item type. For the image column example, one may want to create a TImage control within cells residing in items of Item and AlterantingItem types.

                                            - + class ImageColumn extends TDataGridColumn { ... public function initializeCell($cell,$columnIndex,$itemType) { @@ -178,7 +178,7 @@ class ImageColumn extends TDataGridColumn { } } -

                                            +

                                            In initializeCell(), remember to call the parent implementation, as it initializes cells in items of Header and Footer types.

                                            diff --git a/demos/quickstart/protected/pages/Controls/DataList.page b/demos/quickstart/protected/pages/Controls/DataList.page index 75541564..1630ed96 100644 --- a/demos/quickstart/protected/pages/Controls/DataList.page +++ b/demos/quickstart/protected/pages/Controls/DataList.page @@ -1,16 +1,16 @@

                                            TDataList

                                            -

                                            +

                                            TDataList is used to display or modify a list of data items specified by its DataSource or DataSourceID property. Each data item is displayed by a data list item which is a child control of the data list. The Items property contains the list of all data list items.

                                            -

                                            +

                                            TDataList displays its items in either a Table or Flow layout, which is specified by the RepeatLayout property. A table layout uses HTML table cells to organize the items while a flow layout uses line breaks to organize the items. When the layout is Table, the table's cellpadding and cellspacing can be adjusted by CellPadding and CellSpacing properties, respectively. And Caption and CaptionAlign can be used to add a table caption with the specified alignment. The number of columns used to display the data list items is specified via RepeatColumns property, while the RepeatDirection governs the order of the items being rendered.

                                            -

                                            +

                                            Each data list item is created according to one of the seven kinds of templates that developers may specified for a TDataList,

                                            -
                                              +
                                              • HeaderTemplate - the template used for displaying content at the beginning of a data list;
                                              • FooterTemplate - the template used for displaying content at the end of a data list;
                                              • ItemTemplate - the template used for displaying every data list item. If AlternatingItemTemplate is also defined, ItemTemplate will be used for displaying item 1, 3, 5, etc.
                                                • @@ -19,19 +19,19 @@ Each data list item is created according to one of the seven kinds of templates
                                              • EditItemTemplate - the template used for displaying items in edit mode.
                                              • SelectedItemTemplate - the template used for displaying items in selected mode.
                                              -

                                              +

                                              Each of the above templates is associated with a style property that is applied to the items using the template. For example, ItemTemplate is associated with a property named AlternatingItemStyle. Through this property, one can set CSS style fields or CSS classes for the data list items.

                                              -

                                              +

                                              Item styles are applied in a hierarchical way. Style in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, ItemStyle, AlternatingItemStyle, SelectedItemStyle, and EditItemStyle. Therefore, if background color is set as red in ItemStyle, EditItemStyle will also have red background color, unless it is explicitly set to a different value.

                                              -

                                              +

                                              A data list item can be in normal mode, edit mode or selected mode. Different templates will apply to items of different modes. To change an item's mode, modify EditItemIndex or SelectedItemIndex. Note, if an item is in edit mode, then selecting this item will have no effect.

                                              -

                                              +

                                              TDataList provides several events to facilitate manipulation of its items,

                                              -
                                                +
                                                • OnItemCreated - raised each time an item is newly created. When the event is raised, data and child controls are both available for the new item.
                                                • OnItemDataBound - raised each time an item just completes databinding. When the event is raised, data and child controls are both available for the item, and the item has finished databindings of itself and all its child controls.
                                                • OnItemCommand - raised when a child control of some item (such as a TButton) raises an OnCommand event.
                                                  • @@ -45,17 +45,17 @@ TDataList provides several events to facilitate manipulation of its items,
                                              -

                                              +

                                              The following example shows how to use TDataList to display tabular data, with different layout and styles.

                                              -

                                              +

                                              A common use of TDataList is for maintaining tabular data, including browsing, editing, deleting data items. This is enabled by the command events and various item templates of TDataList.

                                              -

                                              +

                                              The following example displays a computer product information. Users can add new products, modify or delete existing ones. In order to locate the data item for updating or deleting, DataKeys property is used.

                                              -

                                              +

                                              Be aware, for simplicity, this application does not do any input validation. In real applications, make sure user inputs are valid before saving them into databases.

                                              diff --git a/demos/quickstart/protected/pages/Controls/DatePicker.page b/demos/quickstart/protected/pages/Controls/DatePicker.page index 36d2f435..039540ce 100644 --- a/demos/quickstart/protected/pages/Controls/DatePicker.page +++ b/demos/quickstart/protected/pages/Controls/DatePicker.page @@ -3,14 +3,14 @@

                                              TDatePicker

                                              -

                                              TDatePicker displays a text box for date input purpose. +

                                              TDatePicker displays a text box for date input purpose. When the text box receives focus, a calendar will pop up and users can pick up from it a date that will be automatically entered into the text box. The format of the date string displayed in the text box is determined by the DateFormat property. Valid formats are the combination of the following tokens: - + Character Format Pattern (en-US) --------------------------------------------------------------------- d day digit @@ -24,52 +24,50 @@ Character Format Pattern (en-US) --------------------------------------------------------------------- -

                                              +

                                              The date of the date picker can be set using the Date or Timestamp properties. The Date property value must be in the same format as the pattern specified in the DateFormat property. The Timestamp property only accepts integers such as the Unix timestamp.

                                              -

                                              -TDatePicker has three Mode to show the date picker popup. -

                                                +

                                                +TDatePicker has three Mode to show the date picker popup.

                                                +
                                                • Basic - Only shows a text input, focusing on the input shows the date picker.
                                                • Button - Shows a button next to the text input, clicking on the button shows the date, button text can be by the ButtonText property.
                                                • ImageButton - Shows an image next to the text input, clicking on the image shows the date picker, image source can be change through the ImageUrl property.
                                                -

                                                -

                                                The CssClass property can be used to override the CSS class name +

                                                The CssClass property can be used to override the CSS class name for the date picker panel. The CalendarStyle property changes the overall calendar style. -The following CalendarStyle values are available: -

                                                  +The following CalendarStyle values are available:

                                                  +
                                                  • default - The default calendar style.
                                                  -

                                                  -

                                                  The InputMode property can be set to "TextBox" or "DropDownList" with +

                                                  The InputMode property can be set to "TextBox" or "DropDownList" with default as "TextBox". In DropDownList mode, in addition to the popup date picker, three drop down list (day, month and year) are presented to select the date . When InputMode equals "DropDownList", the order and appearance of the date, month, and year will depend on the pattern specified in DateFormat property.

                                                  -

                                                  The popup date picker can be hidden by specifying ShowCalendar as false. Much of the +

                                                  The popup date picker can be hidden by specifying ShowCalendar as false. Much of the text of the popup date picker can be changed to a different language using the Culture property.

                                                  -

                                                  The calendar picker year limit can be set using the FromYear and UpToYear properties +

                                                  The calendar picker year limit can be set using the FromYear and UpToYear properties where FromYear is the starting year and UpToYear is the last year selectable. The starting day of the week can be changed by the FirstDayOfWeek property, with 0 as Sunday, 1 as Monday, etc.

                                                  -

                                                  Note 1: If the InputMode is "TextBox", the DateFormat should +

                                                  Note 1: If the InputMode is "TextBox", the DateFormat should only NOT contain MMM or MMMM patterns. The server side date parser will not be able to determine the correct date if MMM or MMMM are used. When InputMode equals "DropDownList", all patterns can be used.

                                                  -

                                                  Note 2: When the TDatePicker is used together +

                                                  Note 2: When the TDatePicker is used together with a validator, the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker AND must set DataType="Date" on the validator to ensure correct validation. See diff --git a/demos/quickstart/protected/pages/Controls/Expression.page b/demos/quickstart/protected/pages/Controls/Expression.page index 044808c6..71230fba 100644 --- a/demos/quickstart/protected/pages/Controls/Expression.page +++ b/demos/quickstart/protected/pages/Controls/Expression.page @@ -3,18 +3,18 @@

                                                  TExpression

                                                  -

                                                  +

                                                  TExpression evaluates a PHP expression and displays the evaluation result. To specify the expression to be evaluated, set the Expression property. Note, TExpression evaluates the expression during the rendering control lifecycle.

                                                  -

                                                  +

                                                  The context of the expression in a TExpression control is the control itself. That is, $this represents the control object if it is present in the expression. For example, the following template tag will display the title of the page containing the TExpression control.

                                                  - + <com:TExpression Expression="$this->Page->Title" /> -

                                                  +

                                                  Be aware, since TExpression allows execution of arbitrary PHP code, in general you should not use it to evaluate expressions submitted by your application users.

                                                  diff --git a/demos/quickstart/protected/pages/Controls/FileUpload.page b/demos/quickstart/protected/pages/Controls/FileUpload.page index 404a144e..1f2a2adb 100644 --- a/demos/quickstart/protected/pages/Controls/FileUpload.page +++ b/demos/quickstart/protected/pages/Controls/FileUpload.page @@ -3,22 +3,22 @@

                                                  TFileUpload

                                                  -

                                                  +

                                                  TFileUpload displays a file upload field on a Web page. Upon postback, the text entered into the field will be treated as the (local) name of the file that is uploaded to the server.

                                                  -

                                                  +

                                                  TFileUpload raises an OnFileUpload event when it is post back. The property HasFile indicates whether the file upload is successful or not. If successful, the uploaded file may be saved on the server by calling saveAs() method.

                                                  -

                                                  +

                                                  The following properties give the information about the uploaded file:

                                                  -
                                                    +
                                                    • FileName - the original client-side file name without directory information.
                                                    • FileType - the MIME type of the uploaded file.
                                                    • FileSize - the file size in bytes.
                                                    • LocalName - the absolute file path of the uploaded file on the server. Note, this file will be deleted after the current page request is completed. Call saveAs() to save the uploaded file.
                                                    -

                                                    +

                                                    If the file upload is unsuccessful, the property ErrorCode gives the error code describing the cause of failure. See PHP documentation for a complete explanation of the possible error codes.

                                                    diff --git a/demos/quickstart/protected/pages/Controls/Head.page b/demos/quickstart/protected/pages/Controls/Head.page index 227b5282..3ee2d6c0 100644 --- a/demos/quickstart/protected/pages/Controls/Head.page +++ b/demos/quickstart/protected/pages/Controls/Head.page @@ -3,7 +3,7 @@

                                                    THead

                                                    -

                                                    +

                                                    TBD

                                                    diff --git a/demos/quickstart/protected/pages/Controls/HiddenField.page b/demos/quickstart/protected/pages/Controls/HiddenField.page index aa2e7c87..7564573e 100644 --- a/demos/quickstart/protected/pages/Controls/HiddenField.page +++ b/demos/quickstart/protected/pages/Controls/HiddenField.page @@ -3,10 +3,10 @@

                                                    THiddenField

                                                    -

                                                    +

                                                    THiddenField represents a hidden field on a Web page. The value of the hidden field can be accessed via its Value property.

                                                    -

                                                    +

                                                    THiddenField raises an OnValueChanged event if its value is changed during postback.

                                                    diff --git a/demos/quickstart/protected/pages/Controls/HtmlArea.page b/demos/quickstart/protected/pages/Controls/HtmlArea.page index e40a4444..2b755802 100644 --- a/demos/quickstart/protected/pages/Controls/HtmlArea.page +++ b/demos/quickstart/protected/pages/Controls/HtmlArea.page @@ -3,18 +3,18 @@

                                                    THtmlArea

                                                    -

                                                    +

                                                    THtmlArea displays a WYSIWYG text input field on a Web page to collect input in HTML format. The text displayed in the THtmlArea control is specified or determined by using the Text property. To adjust the size of the input region, set Width and Height properties instead of Columns and Rows because the latter has no meaning under this situation. To disable the WYSIWYG feature, set EnableVisualEdit to false.

                                                    -

                                                    +

                                                    THtmlArea provides the WYSIWYG feature by wrapping the functionalities provided by the TinyMCE project.

                                                    -

                                                    +

                                                    The default editor gives only the basic tool bar. To change or add additional tool bars, use the Options property to add additional editor options with each options on a new line. See TinyMCE website for a complete list of options. The following example displays a toolbar specific for HTML table manipulation,

                                                    - + <com:THtmlArea> <prop:Options> plugins : "table" @@ -23,7 +23,7 @@ The default editor gives only the basic tool bar. To change or add additional to </com:THtmlArea> -

                                                    +

                                                    The client-side visual editing capability is supported by Internet Explorer 5.0+ for Windows and Gecko-based browser. If the browser does not support the visual editing, a traditional textarea will be displayed.

                                                    diff --git a/demos/quickstart/protected/pages/Controls/HyperLink.page b/demos/quickstart/protected/pages/Controls/HyperLink.page index 9fa6bde3..5861a00f 100644 --- a/demos/quickstart/protected/pages/Controls/HyperLink.page +++ b/demos/quickstart/protected/pages/Controls/HyperLink.page @@ -3,7 +3,7 @@

                                                    THyperLink

                                                    -

                                                    +

                                                    THyperLink displays a hyperlink on a page. The hyperlink URL is specified via the NavigateUrl property, and link text is via the Text property. The link target is specified via the Target property. It is also possible to display an image by setting the ImageUrl property. In this case, Text is displayed as the alternate text of the image. If both ImageUrl and Text are empty, the content enclosed within the control tag will be rendered.

                                                    diff --git a/demos/quickstart/protected/pages/Controls/Image.page b/demos/quickstart/protected/pages/Controls/Image.page index 1e8df3de..dc68a8bd 100644 --- a/demos/quickstart/protected/pages/Controls/Image.page +++ b/demos/quickstart/protected/pages/Controls/Image.page @@ -3,7 +3,7 @@

                                                    TImage

                                                    -

                                                    +

                                                    TImage displays an image on a page. The image is specified via the ImageUrl property which takes a relative or absolute URL to the image file. The alignment of the image displayed is set by the ImageAlign property. To set alternate text or long description of the image, use AlternateText or DescriptionUrl, respectively.

                                                    diff --git a/demos/quickstart/protected/pages/Controls/ImageButton.page b/demos/quickstart/protected/pages/Controls/ImageButton.page index a4f8d30f..22ec483f 100644 --- a/demos/quickstart/protected/pages/Controls/ImageButton.page +++ b/demos/quickstart/protected/pages/Controls/ImageButton.page @@ -3,7 +3,7 @@

                                                    TImageButton

                                                    -

                                                    +

                                                    TImageButton is also similar to TButton, except that TImageButton displays the button as an image. The image is specified via ImageUrl, and the alternate text is specified by Text. In addition, it is possible to obtain the coordinate of the point where the image is clicked. The coordinate information is contained in the event parameter of the OnClick event (not OnCommand).

                                                    diff --git a/demos/quickstart/protected/pages/Controls/ImageMap.page b/demos/quickstart/protected/pages/Controls/ImageMap.page index 002861a3..162500e3 100644 --- a/demos/quickstart/protected/pages/Controls/ImageMap.page +++ b/demos/quickstart/protected/pages/Controls/ImageMap.page @@ -3,16 +3,16 @@

                                                    TImageMap

                                                    -

                                                    +

                                                    TImageMap represents an image on a Web page with predefined hotspot regions that can respond differently to users' clicks on them. Depending on the HotSpotMode of the hotspot region, clicking on the hotspot may trigger a postback or navigate to a specified URL.

                                                    -

                                                    +

                                                    Each hotspot is described using a THotSpot object and is maintained in the HotSpots collection in TImageMap. A hotspot can be a circle, rectangle, polygon, etc.

                                                    -

                                                    +

                                                    Hotspots can be added to TImageMap via its HotSpots property or in a template like the following,

                                                    - + <com:TImageMap ... > <com:TCircleHotSpot ... /> <com:TRectangleHotSpot ... /> diff --git a/demos/quickstart/protected/pages/Controls/InlineFrame.page b/demos/quickstart/protected/pages/Controls/InlineFrame.page index efd5144d..08b47f21 100644 --- a/demos/quickstart/protected/pages/Controls/InlineFrame.page +++ b/demos/quickstart/protected/pages/Controls/InlineFrame.page @@ -3,20 +3,20 @@

                                                    TInlineFrame

                                                    -

                                                    +

                                                    TInlineFrame displays an inline frame (<iframe>) on a Web page. The location of the frame content is specified by the FrameUrl property.

                                                    -

                                                    +

                                                    The appearance of a TInlineFrame may be customized with the following properties, in addition to those inherited from TWebControl.

                                                    -
                                                      +
                                                      • Align - the alignment of the frame.
                                                      • DescriptionUrl - the URI of a long description of the frame's contents.
                                                      • MarginWidth and MarginHeight - the number of pixels to use as the left/right margins and top/bottom margins, respectively.
                                                      • ScrollBars - whether scrollbars are provided for the inline frame. By default, it is Auto, meaning the scroll bars appear as needed. Setting it as None or Both to explicitly hide or show the scroll bars.
                                                      -

                                                      +

                                                      The following samples show TInlineFrame with different property settings. The Google homepage is used as the frame content.

                                                      diff --git a/demos/quickstart/protected/pages/Controls/JavascriptLogger.page b/demos/quickstart/protected/pages/Controls/JavascriptLogger.page index 2c0032f8..a41495d2 100644 --- a/demos/quickstart/protected/pages/Controls/JavascriptLogger.page +++ b/demos/quickstart/protected/pages/Controls/JavascriptLogger.page @@ -3,28 +3,28 @@

                                                      TJavascriptLogger

                                                      -

                                                      +

                                                      TJavascriptLogger provides logging for client-side javascript. It is mainly a wrapper of the Javascript developed at http://gleepglop.com/javascripts/logger/.

                                                      -

                                                      +

                                                      To use TJavascriptLogger, simply place the following component tag in a page template.

                                                      - + <com:TJavascriptLogger /> -

                                                      +

                                                      Then, the client-side Javascript may contain the following statements. When they are executed, they will appear in the logger window.

                                                      - + Logger.info('something happend'); Logger.warn('A warning'); Logger.error('This is an error'); Logger.debug('debug information'); -

                                                      +

                                                      To toggle the visibility of the logger and console on the browser window, press ALT-D (or CTRL-D on OS X).

                                                      diff --git a/demos/quickstart/protected/pages/Controls/Label.page b/demos/quickstart/protected/pages/Controls/Label.page index b7d5b094..794c48de 100644 --- a/demos/quickstart/protected/pages/Controls/Label.page +++ b/demos/quickstart/protected/pages/Controls/Label.page @@ -3,7 +3,7 @@

                                                      TLabel

                                                      -

                                                      +

                                                      TLabel displays a piece of text on a Web page. The text to be displayed is set via its Text property. If Text is empty, content enclosed within the TLabel component tag will be displayed. TLabel may also be used as a form label associated with some control on the form. Since Text is not HTML-encoded when being rendered, make sure it does not contain dangerous characters that you want to avoid.

                                                      diff --git a/demos/quickstart/protected/pages/Controls/LinkButton.page b/demos/quickstart/protected/pages/Controls/LinkButton.page index e0255141..9c586ed3 100644 --- a/demos/quickstart/protected/pages/Controls/LinkButton.page +++ b/demos/quickstart/protected/pages/Controls/LinkButton.page @@ -3,7 +3,7 @@

                                                      TLinkButton

                                                      -

                                                      +

                                                      TLinkButton is similar to TButton in every aspect except that TLinkButton is displayed as a hyperlink. The link text is determined by its Text property. If the Text property is empty, then the body content of the button is displayed (therefore, you can enclose a <img> tag within the button body and get an image button.

                                                      diff --git a/demos/quickstart/protected/pages/Controls/List.page b/demos/quickstart/protected/pages/Controls/List.page index b5915693..c9fef3ab 100644 --- a/demos/quickstart/protected/pages/Controls/List.page +++ b/demos/quickstart/protected/pages/Controls/List.page @@ -1,12 +1,12 @@

                                                      List Controls

                                                      -

                                                      +

                                                      List controls covered in this section all inherit directly or indirectly from TListControl. Therefore, they share the same set of commonly used properties, including,

                                                      -
                                                        +
                                                        • Items - list of items in the control. The items are of type TListItem. The item list can be populated via databinding or specified in templates like the following: - + <com:TListBox> <com:TListItem Text="text 1" Value="value 1" /> <com:TListItem Text="text 2" Value="value 2" Selected="true" /> @@ -22,12 +22,12 @@ List controls covered in this section all inherit directly or indirectly from CausesValidation - whether validation should be performed when postback is triggered by the list control.
                                                        -

                                                        +

                                                        Since TListControl inherits from TDataBoundControl, these list controls also share a common operation known as databinding. The Items can be populated from preexisting data specified by DataSource or DataSourceID. A function call to dataBind() will cause the data population. For list controls, data can be specified in the following two kinds of format:

                                                        -
                                                          +
                                                          • one-dimensional array or objects implementing ITraversable : array keys will be used as list item values, and array values will be used as list item texts. For example - + $listbox->DataSource=array( 'key 1'=>'item 1', 'key 2'=>'item 2', @@ -36,7 +36,7 @@ $listbox->dataBind();
                                                          • tabular (two-dimensional) data : each row of data populates a single list item. The list item value is specified by the data member indexed with DataValueField, and the list item text by DataTextField. For example, - + $listbox->DataTextField='name'; $listbox->DataValueField='id'; $listbox->DataSource=array( @@ -49,22 +49,22 @@ $listbox->dataBind();

                                                          TListBox

                                                          -

                                                          +

                                                          TListBox displays a list box that allows single or multiple selection. Set the property SelectionMode as Single to make a single selection list box, and Multiple a multiple selection list box. The number of rows displayed in the box is specified via the Rows property value.

                                                          TDropDownList

                                                          -

                                                          +

                                                          TDropDownList displays a dropdown list box that allows users to select a single option from a few prespecified ones.

                                                          TCheckBoxList

                                                          -

                                                          +

                                                          TCheckBoxList displays a list of checkboxes on a Web page. The alignment of the text besides each checkbox can be specified TextAlign. The layout of the checkboxes can be controlled by the following properties:

                                                          -
                                                            +
                                                            • RepeatLayout - can be either Table or Flow. A Table uses HTML table cells to organize the checkboxes, while a Flow uses HTML span tags and breaks for the organization. With Table layout, you can set CellPadding and CellSpacing.
                                                            • RepeatColumns - how many columns the checkboxes should be displayed in.
                                                            • RepeatDirection - how to traverse the checkboxes, in a horizontal way or a vertical way (because the checkboxes are displayed in a matrix-like layout).
                                                              • @@ -73,19 +73,19 @@ $listbox->dataBind();

                                                              TRadioButtonList

                                                              -

                                                              +

                                                              TRadioButtonList is similar to TCheckBoxList in every aspect except that each TRadioButtonList displays a group of radiobuttons. Only one of the radiobuttions can be selected (TCheckBoxList allows multiple selections.)

                                                              TBulletedList

                                                              -

                                                              +

                                                              TBulletedList displays items in a bullet format on a Web page. The style of the bullets can be specified by BulletStyle. When the style is CustomImage, the bullets are displayed as images, which is specified by BulletImageUrl.

                                                              -

                                                              +

                                                              TBulletedList displays the item texts in three different modes,

                                                              -
                                                                +
                                                                • Text - the item texts are displayed as static texts;
                                                                • HyperLink - each item is displayed as a hyperlink whose URL is given by the item value, and Target property can be used to specify the target browser window;
                                                                • LinkButton - each item is displayed as a link button which posts back to the page if a user clicks on that, and the event OnClick will be raised under such a circumstance.
                                                                  • diff --git a/demos/quickstart/protected/pages/Controls/Literal.page b/demos/quickstart/protected/pages/Controls/Literal.page index d5d40a13..ade7bc07 100644 --- a/demos/quickstart/protected/pages/Controls/Literal.page +++ b/demos/quickstart/protected/pages/Controls/Literal.page @@ -3,20 +3,20 @@

                                                                  TLiteral

                                                                  -

                                                                  +

                                                                  TLiteral displays a static text on a Web page. TLiteral is similar to the TLabel control, except that the TLiteral * control has no style properties, such as BackColor, Font, etc.

                                                                  -

                                                                  +

                                                                  The text displayed by TLiteral can be programmatically controlled by setting the Text property. The text displayed may be HTML-encoded if the Encode is true (the default value is false).

                                                                  -

                                                                  +

                                                                  TLiteral will render the contents enclosed within its component tag if Text is empty.

                                                                  -

                                                                  +

                                                                  Be aware, if Encode is false, make sure Text does not contain unwanted characters that may bring security vulnerabilities.

                                                                  diff --git a/demos/quickstart/protected/pages/Controls/MultiView.page b/demos/quickstart/protected/pages/Controls/MultiView.page index a22711b6..03dca27e 100644 --- a/demos/quickstart/protected/pages/Controls/MultiView.page +++ b/demos/quickstart/protected/pages/Controls/MultiView.page @@ -3,13 +3,13 @@

                                                                  TMultiView

                                                                  -

                                                                  +

                                                                  TMultiView serves as a container for a group of TView controls, which can be retrieved by the Views property. Each view contains child controls. TMultiView determines which view and its child controls are visible. At any time, at most one view is visible (called active). To make a view active, set ActiveView or ActiveViewIndex. Note, by default there is no active view.

                                                                  -

                                                                  +

                                                                  To add a view to TMultiView, manipulate the Views collection or add it in template as follows,

                                                                  - + <com:TMultiView> <com:TView> view 1 content @@ -20,21 +20,21 @@ To add a view to TMultiView, manipulate the Views collection o </com:TMultiView> -

                                                                  +

                                                                  TMultiView responds to the following command events to manage the visibility of its views.

                                                                  -
                                                                    +
                                                                    • NextView : switch to the next view (with respect to the currently active view).
                                                                    • PreviousView : switch to the previous view (with respect to the currently active view).
                                                                    • SwitchViewID : switch to a view by its ID path. The ID path is fetched from the command parameter.
                                                                    • SwitchViewIndex : switch to a view by its zero-based index in the Views collection. The index is fetched from the command parameter.
                                                                    -

                                                                    +

                                                                    Upon postback, if the active view index is changed, TMultiView will raise an OnActiveViewChanged event.

                                                                    -

                                                                    +

                                                                    The Hangman game is a typical use of TMultiView. The following example demonstrates another usage of TMultiView.

                                                                    diff --git a/demos/quickstart/protected/pages/Controls/NewControl.page b/demos/quickstart/protected/pages/Controls/NewControl.page index 5662f848..d6cb52c5 100644 --- a/demos/quickstart/protected/pages/Controls/NewControl.page +++ b/demos/quickstart/protected/pages/Controls/NewControl.page @@ -1,39 +1,39 @@

                                                                    Writing New Controls

                                                                    -

                                                                    +

                                                                    Writing new controls is often desired by advanced programmers, because they want to reuse the code that they write for dealing with complex presentation and user interactions.

                                                                    -

                                                                    +

                                                                    In general, there are two ways of writing new controls: composition of existing controls and extending existing controls. They all require that the new control inherit from TControl or its child classes.

                                                                    Composition of Existing Controls

                                                                    -

                                                                    +

                                                                    Composition is the easiest way of creating new controls. It mainly involves instantiating existing controls, configuring them and making them the constituent components. The properties of the constituent components are exposed through subproperties.

                                                                    -

                                                                    +

                                                                    One can compose a new control in two ways. One is to extend TCompositeControl and override the TControl::createChildControls() method. The other is to extend TTemplateControl (or its child classes) and write a control template. The latter is easier to use and can organize the layout constituent components more intuitively, while the former is more efficient because it does not require parsing of the template.

                                                                    -

                                                                    +

                                                                    As an example, we show how to create a labeled textbox called LabeledTextBox using the above two approaches. A labeled textbox displays a label besides a textbox. We want reuse the PRADO provided TLabel and TTextBox to accomplish this task.

                                                                    Composition by Writing Templates

                                                                    -

                                                                    +

                                                                    We need two files: a control class file named LabeledTextBox.php and a control template file named LabeledTextBox.tpl. Both must reside under the same directory.

                                                                    -

                                                                    +

                                                                    Like creating a PRADO page, we can easily write down the content in the control template file.

                                                                    - + <com:TLabel ID="Label" ForControl="TextBox" /> <com:TTextBox ID="TextBox" /> -

                                                                    +

                                                                    The above template specifies a TLabel control named Label and a TTextBox control named TextBox. We would to expose these two controls. This can be done by defining a property for each control in the LabeledTextBox class file. For example, we can define a Label property as follows,

                                                                    - + class LabeledTextBox extends TTemplateControl { public function getLabel() { $this->ensureChildControls(); @@ -41,19 +41,19 @@ class LabeledTextBox extends TTemplateControl { } } -

                                                                    +

                                                                    In the above, the method call to ensureChildControls() ensures that both the label and the textbox controls are created (from template) when the Label property is accessed. The TextBox property can be implemented similarly.

                                                                    Composition by Overriding createChildControls()

                                                                    -

                                                                    +

                                                                    For a composite control as simple as LabeledTextBox, it is better to create it by extending TCompositeControl and overriding the createChildControls() method, because it does not use templates and thus saves template parsing time.

                                                                    -

                                                                    +

                                                                    Complete code for LabeledTextBox is shown as follows,

                                                                    - + class LabeledTextBox extends TCompositeControl { private $_label; private $_textbox; @@ -81,37 +81,37 @@ class LabeledTextBox extends TCompositeControl {

                                                                    Using LabeledTextBox

                                                                    -

                                                                    +

                                                                    To use LabeledTextBox control, first we need to include the corresponding class file. Then in a page template, we can write lines like the following,

                                                                    - + <com:LabeledTextBox ID="Input" Label.Text="Username" /> -

                                                                    +

                                                                    In the above, Label.Text is a subproperty of LabeledTextBox, which refers to the Text property of the Label property. For other details of using LabeledTextBox, see the above online examples.

                                                                    Extending Existing Controls

                                                                    -

                                                                    +

                                                                    Extending existing controls is the same as conventional class inheritance. It allows developers to customize existing control classes by overriding their properties, methods, events, or creating new ones.

                                                                    -

                                                                    +

                                                                    The difficulty of the task depends on how much an existing class needs to be customized. For example, a simple task could be to customize TLabel control, so that it displays a red label by default. This would merely involves setting the ForeColor property to "red" in the constructor. A difficult task would be to create controls that provide completely innovative functionalities. Usually, this requires the new controls extend from "low level" control classes, such as TControl or TWebControl.

                                                                    -

                                                                    +

                                                                    In this section, we mainly introduce the base control classes TControl and TWebControl, showing how they can be customized. We also introduce how to write controls with specific functionalities, such as loading post data, raising post data and databinding with data source.

                                                                    Extending TControl

                                                                    -

                                                                    +

                                                                    TControl is the base class of all control classes. Two methods are of the most importance for derived control classes:

                                                                    -
                                                                      +
                                                                      • addParsedObject() - this method is invoked for each component or text string enclosed within the component tag specifying the control in a template. By default, the enclosed components and text strings are added into the Controls collection of the control. Derived controls may override this method to do special processing about the enclosed content. For example, TListControl only accepts TListItem components to be enclosed within its component tag, and these components are added into the Items collection of TListControl.
                                                                      • render() - this method renders the control. By default, it renders items in the Controls collection. Derived controls may override this method to give customized presentation.
                                                                      Other important properties and methods include: -
                                                                        +
                                                                        • ID - a string uniquely identifying the control among all controls of the same naming container. An automatic ID will be generated if the ID property is not set explicitly.
                                                                        • UnqiueID - a fully qualified ID uniquely identifying the control among all controls on the current page hierarchy. It can be used to locate a control in the page hierarchy by calling TControl::findControl() method. User input controls often use it as the value of the name attribute of the HTML input element.
                                                                        • ClientID - similar to UniqueID, except that it is mainly used for presentation and is commonly used as HTML element id attribute value. Do not rely on the explicit format of ClientID.
                                                                          • @@ -126,27 +126,27 @@ Other important properties and methods include:

                                                                        Extending TWebControl

                                                                        -

                                                                        +

                                                                        TWebControl is mainly used as a base class for controls representing HTML elements. It provides a set of properties that are common among HTML elements. It breaks the TControl::render() into the following methods that are more suitable for rendering an HTML element:

                                                                        -
                                                                          +
                                                                          • addAttributesToRender() - adds attributes for the HTML element to be rendered. This method is often overridden by derived classes as they usually have different attributes to be rendered.
                                                                          • renderBeginTag() - renders the opening HTML tag.
                                                                          • renderContents() - renders the content enclosed within the HTML element. By default, it displays the items in the Controls collection of the control. Derived classes may override this method to render customized contents.
                                                                          • renderEndTag() - renders the closing HTML tag.
                                                                          -

                                                                          +

                                                                          When rendering the openning HTML tag, TWebControl calls getTagName() to obtain the tag name. Derived classes may override this method to render different tag names.

                                                                          Creating Controls with Special Functionalities

                                                                          -

                                                                          +

                                                                          If a control wants to respond to client-side events and translate them into server side events (called postback events), such as TButton, it has to implement the IPostBackEventHandler interface.

                                                                          -

                                                                          +

                                                                          If a control wants to be able to load post data, such as TTextBox, it has to implement the IPostBackDataHandler interface.

                                                                          -

                                                                          +

                                                                          If a control wants to get data from some external data source, it can extend TDataBoundControl. TDataBoundControl implements the basic properties and methods that are needed for populating data via databinding. In fact, controls like TListControl, TRepeater are TDataGrid are all derived from it.

                                                                          \ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/OutputCache.page b/demos/quickstart/protected/pages/Controls/OutputCache.page index 6c1e5554..65823a7f 100644 --- a/demos/quickstart/protected/pages/Controls/OutputCache.page +++ b/demos/quickstart/protected/pages/Controls/OutputCache.page @@ -1,21 +1,21 @@ -

                                                                          TOutputCache

                                                                          +

                                                                          TOutputCache

                                                                          -

                                                                          +

                                                                          TOutputCache enables caching a portion of a Web page, also known as partial caching. The content being cached are HTML page source coming from static texts on a PRADO template or rendered by one or several controls on the template. When the cached content is used, controls generating the content are no longer created for the page hierarchy and thus significant savings in page processing time can be achieved. The side-effect, as you might already find out, is that the content displayed may be stale if the cached version is shown to the users.

                                                                          -

                                                                          +

                                                                          To use TOutputCache, simply enclose the content to be cached within the TOutputCache component tag on a template (either page or non-page control template), e.g.,

                                                                          - + <com:TOutputCache> content to be cached </com:TOutputCache> -

                                                                          +

                                                                          where content to be cached can be static text and/or template tags. If the latter, the rendering results of the template tags will be cached. You can place one or several TOutputCache on a single template and they can be nested.

                                                                          @@ -23,23 +23,23 @@ where content to be cached can be static text and/or template tags. If the latte TOutputCache stores cached content via PRADO cache modules (e.g. TSqliteCache) and thus requires at least one cache module loaded when the application runs. -

                                                                          +

                                                                          The validity of the cached content is determined based on two factors: the Duration and the cache dependency. The former specifies the number of seconds that the data can remain valid in cache (defaults to 60s), while the latter specifies conditions that the cached data depends on. If a dependency changes (e.g. relevant data in DB are updated), the cached data will be invalidated and discarded.

                                                                          -

                                                                          +

                                                                          There are two ways to specify cache dependency. One may write event handlers to respond to the OnCheckDependency event and set the event parameter's IsValid property to indicate whether the cached data remains valid or not. One can also extend TOutputCache and override its getCacheDependency() method.

                                                                          -

                                                                          +

                                                                          The content fetched from cache may be variated with respect to some parameters. TOutputCache supports variation with respect to request parameters, which is specified by VaryByParam property. If a specified request parameter is different, a different version of cached content is used. This is extremely useful if a page's content may be variated according to some GET parameters. The content being cached may also be variated with user sessions if VaryBySession is set true. To variate the cached content by other factors, override calculateCacheKey() method.

                                                                          -

                                                                          +

                                                                          Output caches can be nested. An outer cache takes precedence over an inner cache in determining the validity of cached contents. This means, if the content cached by the inner cache expires or is invalidated, while that by the outer cache not, the outer cached content will be used.

                                                                          -

                                                                          +

                                                                          By default, TOutputCache is effective only for non-postback page requests and when a cache module is enabled. Do not attempt to address child controls of TOutputCache when the cached content is currently being used. Use ContentCached property to determine whether the content is cached or not.

                                                                          diff --git a/demos/quickstart/protected/pages/Controls/Pager.page b/demos/quickstart/protected/pages/Controls/Pager.page index 20b33b95..af2e4b0a 100644 --- a/demos/quickstart/protected/pages/Controls/Pager.page +++ b/demos/quickstart/protected/pages/Controls/Pager.page @@ -3,33 +3,33 @@

                                                                          TPager

                                                                          -

                                                                          +

                                                                          TPager creates a pager that provides UI for end-users to interactively specify which page of data to be rendered in a TDataBoundControl-derived control, such as TDataList, TRepeater, TCheckBoxList, etc. The target data-bound control is specified by the ControlToPaginate property, which must be the ID path of the target control reaching from the pager's naming container.

                                                                          -

                                                                          +

                                                                          Note, the target data-bound control must have its AllowPaging set to true. Otherwise the pager will be invisible. Also, in case when there is only one page of data available, the pager will also be invisible.

                                                                          -

                                                                          +

                                                                          TPager can display one of the following three types of user interface, specified via its Mode property:

                                                                          -
                                                                            +
                                                                            • NextPrev - a next page and a previous page button are rendered on each page.
                                                                            • Numeric - a list of page index buttons are rendered.
                                                                            • DropDownList - a dropdown list of page indices is rendered.
                                                                            -

                                                                            +

                                                                            These user interfaces may be further customized by configuring the following properties

                                                                            -
                                                                              +
                                                                              • NextPageText and PrevPageText - the label of the next/previous page button. These properties are used when the pager Mode is NextPrev or Numeric.
                                                                              • FirstPageText and LastPageText - the label of the first/last page button. If empty, the corresponding button will not be displayed. These properties are used when the pager Mode is NextPrev or Numeric.
                                                                              • PageButtonCount - the maximum number of page index buttons on a page. This property is used when the pager Mode is Numeric.
                                                                              • ButtonType - type of page buttons, either PushButton meaning normal form submission buttons, or LinkButton meaning hyperlink buttons.
                                                                              -

                                                                              +

                                                                              TPager raises an OnPageIndexChanged event when an end-user interacts with it and specifies a new page (e.g. by clicking on a next page button that would lead to the next page.) Developers may write handlers to respond to this event and obtain the desired new page index from the event parameter's property NewPageIndex. Using this new page index, one can feed a new page of data to the associated data-bound control.

                                                                              diff --git a/demos/quickstart/protected/pages/Controls/Panel.page b/demos/quickstart/protected/pages/Controls/Panel.page index be36095b..4f4f9b14 100644 --- a/demos/quickstart/protected/pages/Controls/Panel.page +++ b/demos/quickstart/protected/pages/Controls/Panel.page @@ -3,7 +3,7 @@

                                                                              TPanel

                                                                              -

                                                                              +

                                                                              TPanel acts as a presentational container for other control. It displays a <div> element on a page. The property Wrap specifies whether the panel's body content should wrap or not, while HorizontalAlign governs how the content is aligned horizontally and Direction indicates the content direction (left to right or right to left). You can set BackImageUrl to give a background image to the panel, and you can set GroupingText so that the panel is displayed as a field set with a legend text. Finally, you can specify a default button to be fired when users press 'return' key within the panel by setting the DefaultButton property.

                                                                              diff --git a/demos/quickstart/protected/pages/Controls/PlaceHolder.page b/demos/quickstart/protected/pages/Controls/PlaceHolder.page index b55d1616..482b3b85 100644 --- a/demos/quickstart/protected/pages/Controls/PlaceHolder.page +++ b/demos/quickstart/protected/pages/Controls/PlaceHolder.page @@ -3,7 +3,7 @@

                                                                              TPlaceHolder

                                                                              -

                                                                              +

                                                                              TPlaceHolder reserves a place on a template, where static texts or controls may be dynamically inserted.

                                                                              diff --git a/demos/quickstart/protected/pages/Controls/RadioButton.page b/demos/quickstart/protected/pages/Controls/RadioButton.page index b40f37bd..bdf5dee2 100644 --- a/demos/quickstart/protected/pages/Controls/RadioButton.page +++ b/demos/quickstart/protected/pages/Controls/RadioButton.page @@ -3,7 +3,7 @@

                                                                              TRadioButton

                                                                              -

                                                                              +

                                                                              TRadioButton is similar to TCheckBox in every aspect, except that TRadioButton displays a radio button on a Web page. The radio button can belong to a specific group specified by GroupName such that only one radio button within that group can be selected at most.

                                                                              diff --git a/demos/quickstart/protected/pages/Controls/Repeater.page b/demos/quickstart/protected/pages/Controls/Repeater.page index 3534c603..76a22e11 100644 --- a/demos/quickstart/protected/pages/Controls/Repeater.page +++ b/demos/quickstart/protected/pages/Controls/Repeater.page @@ -1,23 +1,23 @@

                                                                              TRepeater

                                                                              -

                                                                              +

                                                                              TRepeater displays its content defined in templates repeatedly based on the given data specified by the DataSource or DataSourceID property. The repeated contents can be retrieved from the Items property. Each item is created by instantiating a template and each is a child control of the repeater.

                                                                              -

                                                                              +

                                                                              Like normal control templates, the repeater templates can contain static text, controls and special tags, which after instantiation, become child contents of the corresponding item. TRepeater defines five templates for different purposes,

                                                                              -
                                                                                +
                                                                                • HeaderTemplate - the template used for displaying content at the beginning of a repeater;
                                                                                • FooterTemplate - the template used for displaying content at the end of a repeater;
                                                                                • ItemTemplate - the template used for displaying every repeater item. If AlternatingItemTemplate is also defined, ItemTemplate will be used for displaying item 1, 3, 5, etc.
                                                                                • AlternatingItemTemplate - the template used for displaying every alternating repeater item (i.e., item 2, 4, 6, etc.)
                                                                                • SeparatorTemplate - the template used for displaying content between items.
                                                                                -

                                                                                +

                                                                                To populate data into the repeater items, set DataSource to a valid data object, such as array, TList, TMap, or a database table, and then call dataBind() for the repeater. That is,

                                                                                - + class MyPage extends TPage { public function onLoad($param) { parent::onLoad($param); @@ -28,32 +28,32 @@ class MyPage extends TPage { } } -

                                                                                +

                                                                                Normally, you only need to do this when the page containing the repeater is initially requested. In postbacks, TRepeater is smart enough to remember the previous state, i.e., contents populated with datasource information.The following sample displays tabular data using TRepeater.

                                                                                -

                                                                                +

                                                                                TRepeater provides several events to facilitate manipulation of its items,

                                                                                -
                                                                                  +
                                                                                  • OnItemCreated - raised each time an item is newly created. When the event is raised, data and child controls are both available for the new item.
                                                                                  • OnItemDataBound - raised each time an item just completes databinding. When the event is raised, data and child controls are both available for the item, and the item has finished databindings of itself and all its child controls.
                                                                                  • OnItemCommand - raised when a child control of some item (such as a TButton) raises an OnCommand event.
                                                                                  -

                                                                                  +

                                                                                  The following example shows how to use TRepeater to display tabular data.

                                                                                  -

                                                                                  +

                                                                                  TRepeater can be used in more complex situations. As an example, we show in the following how to use nested repeaters, i.e., repeater in repeater. This is commonly seen in presenting master-detail data. To use a repeater within another repeater, for an item for the outer repeater is created, we need to set the detail data source for the inner repeater. This can be achieved by responding to the OnItemDataBound event of the outer repeater. An OnItemDataBound event is raised each time an outer repeater item completes databinding. In the following example, we exploit another event of repeater called OnItemCreated, which is raised each time a repeater item (and its content) is newly created. We respond to this event by setting different background colors for repeater items to achieve alternating item background display. This saves us from writing an AlternatingItemTemplate for the repeaters.

                                                                                  -

                                                                                  +

                                                                                  Besides displaying data, TRepeater can also be used to collect data from users. Validation controls can be placed in TRepeater templates to verify that user inputs are valid.

                                                                                  -

                                                                                  +

                                                                                  The PRADO component composer demo is a good example of such usage. It uses a repeater to collect the component property and event definitions. Users can also delete or adjust the order of the properties and events, which is implemented by responding to the OnItemCommand event of repeater.

                                                                                  -

                                                                                  +

                                                                                  See in the following yet another example showing how to use repeater to collect user inputs.

                                                                                  diff --git a/demos/quickstart/protected/pages/Controls/SafeHtml.page b/demos/quickstart/protected/pages/Controls/SafeHtml.page index 995ceb50..1e02bb9e 100644 --- a/demos/quickstart/protected/pages/Controls/SafeHtml.page +++ b/demos/quickstart/protected/pages/Controls/SafeHtml.page @@ -3,10 +3,10 @@

                                                                                  TSafeHtml

                                                                                  -

                                                                                  +

                                                                                  TSafeHtml is a control that strips down all potentially dangerous HTML content. It is mainly a wrapper of the SafeHTML project. According to the SafeHTML project, it tries to safeguard the following situations when the string is to be displayed to end-users:

                                                                                  -
                                                                                    +
                                                                                    • Opening tag without its closing tag
                                                                                    • closing tag without its opening tag
                                                                                    • any of these tags: base, basefont, head, html, body, applet, object, iframe, frame, frameset, script, layer, ilayer, embed, bgsound, link, meta, style, title, blink, xml, etc.
                                                                                      • @@ -16,7 +16,7 @@
                                                                                    • any other active content.
                                                                                    -

                                                                                    +

                                                                                    To use TSafeHtml, simply enclose the content to be secured within the TSafeHtml component tag in a template. The content may consist of both static text and PRADO controls. If the latter, the rendering result of the controls will be secured.

                                                                                    diff --git a/demos/quickstart/protected/pages/Controls/Standard.page b/demos/quickstart/protected/pages/Controls/Standard.page index f19bc07e..6ea2d52a 100644 --- a/demos/quickstart/protected/pages/Controls/Standard.page +++ b/demos/quickstart/protected/pages/Controls/Standard.page @@ -2,7 +2,7 @@

                                                                                    Standard Controls

                                                                                    * the tutorial for this control is not completed yet.

                                                                                    -
                                                                                      +
                                                                                      • TButton represents a click button on a Web page. It is mainly used to trigger page postback.
                                                                                        • diff --git a/demos/quickstart/protected/pages/Controls/Statements.page b/demos/quickstart/protected/pages/Controls/Statements.page index 3f3bd1fc..f8bb4928 100644 --- a/demos/quickstart/protected/pages/Controls/Statements.page +++ b/demos/quickstart/protected/pages/Controls/Statements.page @@ -3,10 +3,10 @@

                                                                                        TStatements

                                                                                        -

                                                                                        +

                                                                                        TStatements evaluates a sequence of PHP statements and displays the content rendered by the statements. To specify the PHP statements to be evaluated, set the Statements property. For example, the following component tag displays the current time on the Web page,

                                                                                        - + <com:TStatements> <prop:Statements> setlocale(LC_ALL, 'nl_NL'); @@ -15,14 +15,14 @@ </com:TStatements> -

                                                                                        +

                                                                                        Note, TStatements evaluates the PHP statements during the rendering control lifecycle. Unlike TExpression, TStatements only displays the content 'echoed' within the statements.

                                                                                        -

                                                                                        +

                                                                                        The context of the statements in a TStatements control is the control itself. That is, $this represents the control object if it is present in the statements. For example, the following statement tag will display the title of the page containing the TStatements control.

                                                                                        - + <com:TStatements> <prop:Statements> $page=$this->Page; @@ -31,7 +31,7 @@ The context of the statements in a TStatements control is the control i </com:TStatements> -

                                                                                        +

                                                                                        Be aware, since TStatements allows execution of arbitrary PHP code, in general you should not use it to evaluate PHP code submitted by your application users.

                                                                                        diff --git a/demos/quickstart/protected/pages/Controls/Table.page b/demos/quickstart/protected/pages/Controls/Table.page index e0f5586e..ab9e6c1f 100644 --- a/demos/quickstart/protected/pages/Controls/Table.page +++ b/demos/quickstart/protected/pages/Controls/Table.page @@ -3,7 +3,7 @@

                                                                                        TTable

                                                                                        -

                                                                                        +

                                                                                        TTable displays an HTML table on a page. It is used together with TTableRow and TTableCell to allow programmatically manipulating HTML tables. The rows of the table is stored in Rows property. You may set the table cellspacing and cellpadding via the CellSpacing and CellPadding properties, respectively. The table caption can be specified via Caption whose alignment is specified by CaptionAlign. The GridLines property indicates how the table should display its borders, and the BackImageUrl allows the table to have a background image.

                                                                                        diff --git a/demos/quickstart/protected/pages/Controls/TextBox.page b/demos/quickstart/protected/pages/Controls/TextBox.page index b4d1576f..c5fee17e 100644 --- a/demos/quickstart/protected/pages/Controls/TextBox.page +++ b/demos/quickstart/protected/pages/Controls/TextBox.page @@ -3,7 +3,7 @@

                                                                                        TTextBox

                                                                                        -

                                                                                        +

                                                                                        TTextBox displays a text box on a Web page. The content in the text box is determined by the Text property. You can create a SingleLine, a MultiLine, or a Password text box by setting the TextMode property. The Rows and Columns properties specify their dimensions. If AutoPostBack is true, changing the content in the text box and then moving the focus out of it will cause postback action.

                                                                                        diff --git a/demos/quickstart/protected/pages/Controls/TextHighlighter.page b/demos/quickstart/protected/pages/Controls/TextHighlighter.page index 285a6f3e..b9ac1834 100644 --- a/demos/quickstart/protected/pages/Controls/TextHighlighter.page +++ b/demos/quickstart/protected/pages/Controls/TextHighlighter.page @@ -3,16 +3,16 @@

                                                                                        TTextHighlighter

                                                                                        -

                                                                                        +

                                                                                        TTextHighlighter does syntax highlighting for its body content, including both static text and the rendering results of its child controls. The text being highlighted follows the syntax of the specified Language, which can be 'php' (default), 'prado', 'css', 'html', etc. Here, 'prado' stands for the syntax of PRADO control templates.

                                                                                        -

                                                                                        +

                                                                                        If line numbers are desired in front of each line, set ShowLineNumbers to true.

                                                                                        -

                                                                                        +

                                                                                        To use TTextHighlighter, simply enclose the contents to be syntax highlighted within the body of a TTextHighlighter control. The following example highlights a piece of PHP code,

                                                                                        - + <com:TTextHighlighter ShowLineNumbers="true"> Validation Controls -

                                                                                        +

                                                                                        Validation controls, called validators, perform validation on user-entered data values when they are post back to the server. The validation is triggered by a postback control, such as a TButton, a TLinkButton or a TTextBox (under AutoPostBack mode) whose CausesValidation property is true.

                                                                                        -

                                                                                        +

                                                                                        Validation is always performed on server side. If EnableClientScript is true and the client browser supports JavaScript, validators may also perform client-side validation. Client-side validation will validate user input before it is sent to the server. The form data will not be submitted if any error is detected. This avoids the round-trip of information necessary for server-side validation.

                                                                                        -

                                                                                        +

                                                                                        Validators share a common set of properties, which are defined in the base class TBaseValidator class and listed as follows,

                                                                                        -
                                                                                          +
                                                                                          • ControlToValidate specifies the input control to be validated. This property must be set to the ID path of an input control. An ID path is the dot-connected IDs of the controls reaching from the validator's naming container to the target control.
                                                                                          • ErrorMessage specifies the error message to be displayed in case the corresponding validator fails.
                                                                                          • Text is similar to ErrorMessage. If they are both present, Text takes precedence. This property is useful when used together with TValidationSummary.
                                                                                            • @@ -33,17 +33,17 @@ Validators share a common set of properties, which are defined in the base class

                                                                                            TRequiredFieldValidator

                                                                                            -

                                                                                            +

                                                                                            TRequiredFieldValidator ensures that the user enters some data in the specified input field. By default, TRequiredFieldValidator will check if the user input is empty or not. The validation fails if the input is empty. By setting InitialValue, the validator can check if the user input is different from InitialValue. If not, the validation fails.

                                                                                            TRegularExpressionValidator

                                                                                            -

                                                                                            +

                                                                                            TRegularExpressionValidator verifies the user input against a regular pattern. The validation fails if the input does not match the pattern. The regular expression can be specified by the RegularExpression property. Some commonly used regular expressions include:

                                                                                            -
                                                                                              +
                                                                                              • At least 6 characters: [\w]{6,}
                                                                                              • Japanese Phone Number: (0\d{1,4}-|\(0\d{1,4}\) ?)?\d{1,4}-\d{4}
                                                                                              • Japanese Postal Code: \d{3}(-(\d{4}|\d{2}))?
                                                                                                • @@ -54,49 +54,49 @@ TRegularExpressionValidator verifies the user input against a regular pattern. T
                                                                                              • U.S. ZIP Code: \d{5}(-\d{4})?
                                                                                              • U.S. Social Security Number: \d{3}-\d{2}-\d{4}
                                                                                              -

                                                                                              +

                                                                                              More regular expression patterns can be found on the Internet, e.g. http://regexlib.com/.

                                                                                              -

                                                                                              +

                                                                                              Note, TRegularExpressionValidator only checks for nonempty user input. Use a TRequiredFieldValidator to ensure the user input is not empty.

                                                                                              TEmailAddressValidator

                                                                                              -

                                                                                              +

                                                                                              TEmailAddressValidator verifies that the user input is a valid email address. The validator uses a regular expression to check if the input is in a valid email address format. If CheckMXRecord is true, the validator will also check whether the MX record indicated by the email address is valid, provided checkdnsrr() is available in the installed PHP.

                                                                                              -

                                                                                              +

                                                                                              Note, if the input being validated is empty, TEmailAddressValidator will not do validation. Use a TRequiredFieldValidator to ensure the value is not empty.

                                                                                              TCompareValidator

                                                                                              -

                                                                                              +

                                                                                              TCompareValidator compares the user input with a constant value specified by ValueToCompare, or another user input specified by ControlToCompare. The Operator property specifies how to compare the values, which includes Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan and LessThanEqual. Before comparison, the values being compared will be converted to the type specified by DataType listed as follows,

                                                                                              -
                                                                                                +
                                                                                                • String - A string data type.
                                                                                                • Integer - A 32-bit signed integer data type.
                                                                                                • Float - A double-precision floating point number data type.
                                                                                                • Date - A date data type. The date format can be specified by setting DateFormat property, which must be recognizable by TSimpleDateFormatter. If the property is not set, the GNU date syntax is assumed.
                                                                                                -

                                                                                                +

                                                                                                Note, if the input being validated is empty, TEmailAddressValidator will not do validation. Use a TRequiredFieldValidator to ensure the value is not empty.

                                                                                                -

                                                                                                +

                                                                                                N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.

                                                                                                TDataTypeValidator

                                                                                                -

                                                                                                +

                                                                                                TDataTypeValidator verifies if the input data is of specific type indicated by DataType. The data types that can be checked against are the same as those in TCompareValidator.

                                                                                                -

                                                                                                +

                                                                                                N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.

                                                                                                @@ -105,10 +105,10 @@ TDataTypeValidator verifies if the input data is of specific type indicated by <

                                                                                                TRangeValidator

                                                                                                -

                                                                                                +

                                                                                                TRangeValidator verifies whether an input value is within a specified range. TRangeValidator uses three key properties to perform its validation. The MinValue and MaxValue properties specify the minimum and maximum values of the valid range. The DataType property specifies the data type of the value being validated. The value will be first converted into the specified type and then compare with the valid range. The data types that can be checked against are the same as those in TCompareValidator.

                                                                                                -

                                                                                                +

                                                                                                N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.

                                                                                                @@ -116,16 +116,16 @@ TRangeValidator verifies whether an input value is within a specified range. TRa

                                                                                                TCustomValidator

                                                                                                -

                                                                                                +

                                                                                                TCustomValidator performs user-defined validation (either server-side or client-side or both) on an input control.

                                                                                                -

                                                                                                +

                                                                                                To create a server-side validation function, provide a handler for the OnServerValidate event that performs the validation. The data string of the input control to validate can be accessed by the event parameter's Value property. The result of the validation should be stored in the IsValid property of the parameter.

                                                                                                -

                                                                                                +

                                                                                                To create a client-side validation function, add the client-side validation javascript function to the page template and assign its name to the ClientValidationFunction property. The function should have the following signature:

                                                                                                - +