diff options
| author | wei <> | 2007-01-14 02:10:24 +0000 |
|---|---|---|
| committer | wei <> | 2007-01-14 02:10:24 +0000 |
| commit | 45b0fe42a979d444d547a5248eb2e9e915aaf16a (patch) | |
| tree | 2480dae3350e4a70949956c41984cceb8dce3efc /demos/quickstart/protected/pages/Advanced | |
| parent | 898049a4012eaecd99e7a418726215e656677809 (diff) | |
Add "block-content" to allow user comments on block level elements in quickstart docs.
Diffstat (limited to 'demos/quickstart/protected/pages/Advanced')
22 files changed, 355 insertions, 353 deletions
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 @@ <com:TContent ID="body" >
<h1 id="5701">Assets</h1>
-<p>
+<p id="740577" class="block-content">
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 <tt>down.gif</tt> and <tt>up.gif</tt>, to show different toggle states. If we require the image files be stored under <tt>images</tt> 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.
</p>
-<p>
+<p id="740578" class="block-content">
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.
</p>
<h2 id="5702">Asset Publishing</h2>
-<p>
+<p id="740579" class="block-content">
PRADO provides several methods for publishing assets or directories containing assets:
</p>
-<ul>
+<ul id="u1" class="block-content">
<li>In a template file, you can use <a href="?page=Configurations.Templates2#at">asset tags</a> to publish assets and obtain their URLs. Note, the assets must be relative to the directory containing the template file.</li>
<li>In PHP code, you can call <tt>$object->publishAsset($assetPath)</tt> to publish an asset and obtain its URL. Here, <tt>$object</tt> refers to an instance of <tt>TApplicationComponent</tt> or derived class, and <tt>$assetPath</tt> is a file or directory relative to the directory containing the class file.</li>
<li>If you want to publish an arbitrary asset, you need to call <tt>TAssetManager::publishFilePath($path)</tt>.</li>
</ul>
-<p>
+<p id="740580" class="block-content">
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.
</p>
<h2 id="5703">Customization</h2>
-<p>
+<p id="740581" class="block-content">
Asset publishing is managed by the <tt>System.Web.TAssetManager</tt> module. By default, all published asset files are stored under the <tt>[AppEntryPath]/assets</tt> directory, where <tt>AppEntryPath</tt> refers to the directory containing the application entry script. Make sure the <tt>assets</tt> directory is writable by the Web server process. You may change this directory to another by configuring the <tt>BasePath</tt> and <tt>BaseUrl</tt> properties of the <tt>TAssetManager</tt> module in application configuration,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code1">
<modules>
<module id="asset"
class="System.Web.TAssetManager"
@@ -35,18 +35,18 @@ Asset publishing is managed by the <tt>System.Web.TAssetManager</tt> module. By </com:TTextHighlighter>
<h2 id="5704">Performance</h2>
-<p>
+<p id="740582" class="block-content">
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, <tt>System.Web.TAssetManager</tt> only publishes an asset when it has a newer file modification time than the published file. When an application runs under the <tt>Performance</tt> mode, such timestamp checking is also omitted.
</p>
-<p>
+<p id="740583" class="block-content">
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.
</p>
<h2 id="5705">A Toggle Button Example</h2>
-<p>
+<p id="740584" class="block-content">
We now use the toggle button example to explain the usage of assets. The control uses two image files <tt>up.gif</tt> and <tt>down.gif</tt>, which are stored under the directory containing the control class file. When the button is in <tt>Up</tt> state, we would like to show the <tt>up.gif</tt> image. This can be done as follows,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code2">
class ToggleButton extends TWebControl {
...
protected function addAttributesToRender($writer) {
@@ -60,10 +60,10 @@ class ToggleButton extends TWebControl { ...
}
</com:TTextHighlighter>
-<p>
+<p id="740585" class="block-content">
In the above, the call <tt>$this->getAsset('up.gif')</tt> will publish the <tt>up.gif</tt> image file and return a URL for the published image file. The URL is then rendered as the <tt>src</tt> attribute of the HTML image tag.
</p>
-<p>
+<p id="740586" class="block-content">
To redistribute <tt>ToggleButton</tt>, simply pack together the class file and the image files. Users of <tt>ToggleButton</tt> merely need to unpack the file, and they can use it right away, without worrying about where to copy the image files to.
</p>
</com:TContent>
\ 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 @@ <com:TContent ID="body" >
<h1 id="5501">Authentication and Authorization</h1>
-<p>
+<p id="720549" class="block-content">
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.
</p>
-<p>
+<p id="720550" class="block-content">
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.
</p>
<h2 id="5502">How PRADO Auth Framework Works</h2>
-<p>
+<p id="720551" class="block-content">
PRADO provides an extensible authentication/authorization framework. As described in <a href="?page=Fundamentals.Applications">application lifecycles</a>, <tt>TApplication</tt> reserves several lifecycles for modules responsible for authentication and authorization. PRADO provides the <tt>TAuthManager</tt> module for such purposes. Developers can plug in their own auth modules easily. <tt>TAuthManager</tt> is designed to be used together with <tt>TUserManager</tt> module, which implements a read-only user database.
</p>
-<p>
+<p id="720552" class="block-content">
When a page request occurs, <tt>TAuthManager</tt> 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, <tt>TAuthManager</tt> provides two commonly used methods: <tt>login()</tt> and <tt>logout()</tt>. A user is logged in (verified) if his username and password entries match a record in the user database managed by <tt>TUserManager</tt>. 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.
</p>
-<p>
+<p id="720553" class="block-content">
During <tt>Authorization</tt> application lifecycle, which occurs after <tt>Authentication</tt> lifecycle, <tt>TAuthManager</tt> 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, <tt>TAuthManager</tt> will redirect user browser to the login page which is specified by <tt>LoginPage</tt> property.
</p>
<h2 id="5503">Using PRADO Auth Framework</h2>
-<p>
+<p id="720554" class="block-content">
To enable PRADO auth framework, add the <tt>TAuthManager</tt> module and <tt>TUserManager</tt> module to <a href="?page=Configurations.AppConfig">application configuration</a>,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code1">
<service id="page" class="TPageService">
<modules>
<module id="auth" class="System.Security.TAuthManager"
@@ -36,13 +36,13 @@ To enable PRADO auth framework, add the <tt>TAuthManager</tt> module and <tt>TUs </modules>
</service>
</com:TTextHighlighter>
-<p>
+<p id="720555" class="block-content">
In the above, the <tt>UserManager</tt> property of <tt>TAuthManager</tt> is set to the <tt>users</tt> module which is <tt>TUserManager</tt>. Developers may replace it with a different user management module that is derived from <tt>TUserManager</tt>.
</p>
-<p>
+<p id="720556" class="block-content">
Authorization rules for pages are specified in <a href="?page=Configurations.PageConfig">page configurations</a> as follows,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code2">
<authorization>
<allow pages="PageID1,PageID2"
users="User1,User2"
@@ -52,41 +52,41 @@ Authorization rules for pages are specified in <a href="?page=Configurations.Pag verb="post" />
</authorization>
</com:TTextHighlighter>
-<p>
+<p id="720557" class="block-content">
An authorization rule can be either an <tt>allow</tt> rule or a <tt>deny</tt> rule. Each rule consists of four optional properties:
</p>
-<ul>
+<ul id="u1" class="block-content">
<li><tt>pages</tt> - 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.</li>
<li><tt>users</tt> - 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.</li>
<li><tt>roles</tt> - list of comma-separated user roles that this rule applies to.</li>
<li><tt>verb</tt> - page access method that this rule applies to. It can be either <tt>get</tt> or <tt>post</tt>. If empty or not set, the rule applies to both methods.</li>
</ul>
-<p>
+<p id="720558" class="block-content">
When a page request is being processed, a list of authorization rules may be available. However, only the <i>first effective</i> rule <i>matching</i> the current user will render the authorization result.
</p>
-<ul>
+<ul id="u2" class="block-content">
<li>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.</li>
<li>A rule is effective if the current page is in the listed pages of the rule AND the current user action (<tt>get</tt> or <tt>post</tt>) is in the listed actions.</li>
<li>A rule matching occurs if the current user name is in the listed user names of an <i>effective</i> rule OR if the user's role is in the listed roles of that rule.</li>
<li>If no rule matches, the user is authorized.</li>
</ul>
-<p>
+<p id="720559" class="block-content">
In the above example, anonymous users will be denied from posting to <tt>PageID1</tt> and <tt>PageID2</tt>, while <tt>User1</tt> and <tt>User2</tt> and all users of role <tt>Role1</tt> can access the two pages (in both <tt>get</tt> and <tt>post</tt> methods).
</p>
<h2 id="5504">Using <tt>TUserManager</tt></h2>
-<p>
+<p id="720560" class="block-content">
As aforementioned, <tt>TUserManager</tt> implements a read-only user database. The user information are specified in either application configuration or an external XML file.
</p>
-<p>
+<p id="720561" class="block-content">
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,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code3">
<user name="demo" password="demo" roles="demo,admin" />
<role name="admin" users="demo,demo2" />
</com:TTextHighlighter>
-<p>
+<p id="720562" class="block-content">
where the <tt>roles</tt> attribute in <tt>user</tt> element is optional. User roles can be specified in either the <tt>user</tt> element or in a separate <tt>role</tt> element.
</p>
</com:TContent>
\ 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 @@ <com:TContent ID="body" >
<h1 id="5501">Collections</h1>
-<p>
+<p id="710529" class="block-content">
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.
</p>
-<p>
+<p id="710530" class="block-content">
To enable object-oriented manipulation of collections, PRADO provides a set of powerful collection classes. Among them, the <tt>TList</tt> and <tt>TMap</tt> 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.
</p>
<h2 id="5502">Using <tt>TList</tt></h2>
-<p>
+<p id="710531" class="block-content">
A <tt>TList</tt> object represents a cardinal-indexed array, i.e., an array (object) with the index 0, 1, 2, ...
</p>
-<p>
+<p id="710532" class="block-content">
<tt>TList</tt> may be used like a PHP array. For example,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code1">
$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
</com:TTextHighlighter>
-<p>
+<p id="710533" class="block-content">
To obtain the number of items in the list, use the <tt>Count</tt> property. Note, do not use <tt>count($list)</tt>, as it always returns 1.
</p>
-<p>
+<p id="710534" class="block-content">
In addition, <tt>TList</tt> implements a few commonly used convenient methods for manipulating the data in a list. These include
</p>
-<ul>
+<ul id="u1" class="block-content">
<li><tt>clear()</tt>: removes all items in the list.</li>
<li><tt>contains()</tt>: tests if the list contains the specified item.</li>
<li><tt>indexOf()</tt>: obtains the zero-based index of the specified item in the list.</li>
@@ -43,30 +43,30 @@ In addition, <tt>TList</tt> implements a few commonly used convenient methods fo </ul>
<h3 id="5504">Using <tt>TList</tt>-based component properties</h3>
-<p>
+<p id="710535" class="block-content">
As aforementioned, many PRADO component properties are based on <tt>TList</tt> or <tt>TList</tt>-derived collection classes. These properties all share the above usages.
</p>
-<p>
+<p id="710536" class="block-content">
For example, <tt>TControl</tt> (the base class for all PRADO controls) has a property called <tt>Controls</tt> which represents the collection of child controls. The type of <tt>Controls</tt> is <tt>TControlCollection</tt> which extends <tt>TList</tt>. Therefore, to append a new child control, we can use the following,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code2">
$control->Controls[]=$newControl;
</com:TTextHighlighter>
-<p>
+<p id="710537" class="block-content">
To traverse through the child controls, we can use,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code3">
foreach($control->Controls as $childControl) ...
</com:TTextHighlighter>
-<p>
+<p id="710538" class="block-content">
Another example is the <tt>Items</tt> property, available in list controls, <tt>TRepeater</tt>, <tt>TDataList</tt> and <tt>TDataGrid</tt>. In these controls, the ancestor class of <tt>Items</tt> is <tt>TList</tt>.
</p>
<h3 id="5505">Extending <tt>TList</tt></h3>
-<p>
+<p id="710539" class="block-content">
Often, we want to extend <tt>TList</tt> to perform additional operations for each addition or removal of an item. The only methods that the child class needs to override are <tt>insertAt()</tt> and <tt>removeAt()</tt>. For example, to ensure the list only contains items that are of <tt>TControl</tt> type, we can override <tt>insertAt()</tt> as follows,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code4">
public function insertAt($index,$item)
{
if($item instanceof TControl)
@@ -78,13 +78,13 @@ public function insertAt($index,$item) <h2 id="5503">Using <tt>TMap</tt></h2>
-<p>
+<p id="710540" class="block-content">
A <tt>TMap</tt> object represents a hash table (or we say string-indexed array).
</p>
-<p>
+<p id="710541" class="block-content">
Similar to <tt>TList</tt>, <tt>TMap</tt> may be used like an array,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code5">
$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
</com:TTextHighlighter>
-<p>
+<p id="710542" class="block-content">
The <tt>Count</tt> property gives the number of items in the map while the <tt>Keys</tt> property returns a list of keys used in the map.
</p>
-<p>
+<p id="710543" class="block-content">
The following methods are provided by <tt>TMap</tt> for convenience,
</p>
-<ul>
+<ul id="u2" class="block-content">
<li><tt>clear()</tt>: removes all items in the map.</li>
<li><tt>contains()</tt>: tests if the map contains the specified key.</li>
<li><tt>toArray()</tt>: returns an array representation of the items in the map.</li>
@@ -108,28 +108,28 @@ The following methods are provided by <tt>TMap</tt> for convenience, </ul>
<h3 id="5506">Using of <tt>TAttributeCollection</tt></h3>
-<p>
+<p id="710544" class="block-content">
<tt>TAttributeCollection</tt> is a special class extending from <tt>TMap</tt>. It is mainly used by the <tt>Attributes</tt> property of <tt>TControl</tt>.
</p>
Besides the normal functionalities provided by <tt>TMap</tt>, <tt>TAttributeCollection</tt> allows you to get and set collection items like getting and setting properties. For example,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code6">
$collection->Label='value'; // equivalent to: $collection['Label']='value';
echo $collection->Label; // equivalent to: echo $collection['Label'];
</com:TTextHighlighter>
-<p>
+<p id="710545" class="block-content">
Note, in the above <tt>$collection</tt> does NOT have a <tt>Label</tt> property.
</p>
-<p>
+<p id="710546" class="block-content">
Unlike <tt>TMap</tt>, keys in <tt>TAttributeCollection</tt> are case-insensitive. Therefore, <tt>$collection->Label</tt> is equivalent to <tt>$collection->LABEL</tt>.
</p>
-<p>
+<p id="710547" class="block-content">
Because of the above new features, when dealing with the <tt>Attributes</tt> property of controls, we may take advantage of the subproperty concept and configure control attribute values in a template as follows,
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code7">
<com:TButton Attributes.onclick="if(!confirm('Are you sure?')) return false;" .../>
</com:TTextHighlighter>
-<p>
+<p id="710548" class="block-content">
which adds an attribute named <tt>onclick</tt> to the <tt>TButton</tt> control.
</p>
</com:TContent>
\ 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 @@ <com:TContent ID="body" >
<h1 id="6301">Error Handling and Reporting</h1>
-<p>
+<p id="800666" class="block-content">
PRADO provides a complete error handling and reporting framework based on the PHP 5 exception mechanism.
</p>
<h2 id="6302">Exception Classes</h2>
-<p>
+<p id="800667" class="block-content">
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.
</p>
-<p>
+<p id="800668" class="block-content">
All errors in PRADO applications are represented as exceptions. The base class for all PRADO exceptions is <tt>TException</tt>. 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.
</p>
-<p>
+<p id="800669" class="block-content">
Exceptions raised due to improper usage of the PRADO framework inherit from <tt>TSystemException</tt>, which can be one of the following exception classes:
</p>
-<ul>
+<ul id="u1" class="block-content">
<li><tt>TConfigurationException</tt> - improper configuration, such as error in application configuration, control templates, etc.</li>
<li><tt>TInvalidDataValueException</tt> - data value is incorrect or unexpected.</li>
<li><tt>TInvalidDataTypeException</tt> - data type is incorrect or unexpected.</li>
@@ -28,46 +28,46 @@ Exceptions raised due to improper usage of the PRADO framework inherit from <tt> <li><tt>TNotSupportedException</tt> - errors caused by requesting for unsupported feature.</li>
<li><tt>THttpException</tt> - errors to be displayed to Web client users.</li>
</ul>
-<p>
+<p id="800670" class="block-content">
Errors due to improper usage of the Web application by client users inherit from <tt>TApplicationException</tt>.
</p>
<h2 id="6303">Raising Exceptions</h2>
-<p>
+<p id="800671" class="block-content">
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 <tt>THttpException</tt>, while exceptions shown to developers should use other exception classes.
</p>
<h2 id="6304">Error Capturing and Reporting</h2>
-<p>
+<p id="800672" class="block-content">
Exceptions raised during the runtime of PRADO applications are captured by <tt>System.Exceptions.TErrorHandler</tt> module. Different output templates are used to display the captured exceptions. <tt>THttpException</tt> 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.
</p>
<a href="<%~ exception2.gif %>" target="_blank"><img src="<%~ exception.gif %>" alt="exception page" style="border:0px"/></a>
<h2 id="6305">Customizing Error Display</h2>
-<p>
+<p id="800673" class="block-content">
Developers can customize the presentation of exception messages. By default, all error output templates are stored under <tt>framework/Exceptions/templates</tt>. The location can be changed by configuring <tt>TErrorHandler</tt> in application configuration,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_800226">
<module id="error"
class="TErrorHandler"
ErrorTemplatePath="Application.ErrorTemplates" />
</com:TTextHighlighter>
-<p>
+<p id="800674" class="block-content">
<tt>THttpException</tt> uses a set of templates that are differentiated according to different <tt>StatusCode</tt> property value of <tt>THttpException</tt>. <tt>StatusCode</tt> 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 <tt>StatusCode</tt> value is used to select which output template to use. The output template files use the following naming convention:
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_800227">
error<status code>-<language code>.html
</com:TTextHighlighter>
-<p>
+<p id="800675" class="block-content">
where <tt>status code</tt> refers to the <tt>StatusCode</tt> property value of <tt>THttpException</tt>, and <tt>language code</tt> must be a valid language such as <tt>en</tt>, <tt>zh</tt>, <tt>fr</tt>, etc. When a <tt>THttpException</tt> 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.
</p>
-<p>
+<p id="800676" class="block-content">
The naming convention for the template files used for all other exceptions is as follows,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_800228">
exception-<language code>.html
</com:TTextHighlighter>
-<p>
+<p id="800677" class="block-content">
Again, if the preferred language is not found, PRADO will try to use <tt>exception.html</tt>, instead.
</p>
<div class="note">
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 @@ <com:TContent ID="body" >
<h1 id="6201">Internationalization (I18N) and Localization (L10N)</h1>
-<p>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.</p>
+<p id="790625" class="block-content">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.</p>
<h2 id="6203">Separate culture/locale sensitive data</h2>
-<p>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
+<p id="790626" class="block-content">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
</p>
-<ul>
+<ul id="u1" class="block-content">
<li> Strings, Messages, Text, in relatively small units (e.g. phrases, sentences, paragraphs, but not the full text of a book).</li>
<li> Labels on buttons.</li>
<li> Help files, large units of text, static text.</li>
@@ -23,20 +23,20 @@ <li> Page layout.</li>
</ul>
-<p>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).</p>
+<p id="790627" class="block-content">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).</p>
<h2 id="6204">Configuration</h2>
-<p>To enable the localization features in PRADO, you need to add a few configuration options in your <a href="?page=Configurations.AppConfig">application configuration</a>.
+<p id="790628" class="block-content">To enable the localization features in PRADO, you need to add a few configuration options in your <a href="?page=Configurations.AppConfig">application configuration</a>.
First you need to include the <tt>System.I18N.*</tt> namespace to your paths.
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_790203">
<paths>
<using namespace="System.I18N.*" />
</paths>
</com:TTextHighlighter>
-<p>Then, if you wish to translate some text in your application, you need to add one translation message data source.</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<p id="790629" class="block-content">Then, if you wish to translate some text in your application, you need to add one translation message data source.</p>
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_790204">
<module id="globalization" class="TGlobalization">
<translation type="XLIFF"
source="MyApp.messages"
@@ -45,19 +45,19 @@ First you need to include the <tt>System.I18N.*</tt> namespace to your paths. </module>
</com:TTextHighlighter>
-<p>Where <tt>source</tt> in <tt>translation</tt> is the dot path to a directory
+<p id="790630" class="block-content">Where <tt>source</tt> in <tt>translation</tt> is the dot path to a directory
where you are going to store your translate message catalogue. The <tt>autosave</tt>
attribute if enabled, saves untranslated messages back into the message catalogue.
With <tt>cache</tt> enabled, translated messages are saved in the application <tt>runtime/i18n</tt> directory.
The <tt>marker</tt> value is used to surround any untranslated text.
</p>
-<p>With the configuration complete, we can now start to localize your application. If you have <tt>autosave</tt> enabled, after running your application with some localization activity (i.e. translating some text), you will see a directory and a <tt>messages.xml</tt> created within your <tt>source</tt> directory.</p>
+<p id="790631" class="block-content">With the configuration complete, we can now start to localize your application. If you have <tt>autosave</tt> enabled, after running your application with some localization activity (i.e. translating some text), you will see a directory and a <tt>messages.xml</tt> created within your <tt>source</tt> directory.</p>
<h2 id="6205">What to do with <tt>messages.xml</tt>?</h2>
-<p>The translation message catalogue file, if using <tt>type="XLIFF"</tt>, 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.</p>
+<p id="790632" class="block-content">The translation message catalogue file, if using <tt>type="XLIFF"</tt>, 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.</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_790205">
<?xml version="1.0"?>
<xliff version="1.0">
<file original="I18N Example IndexPage"
@@ -80,23 +80,23 @@ Each translation message is wrapped within a <tt>trans-unit</tt> tag, where <tt> <h2 id="6206">Setting and Changing Culture</h2>
-<p>Once globalization is enabled, you can access the globalization settings, such as, <tt>Culture</tt>, <tt>Charset</tt>, etc, using </p>
-<com:TTextHighlighter CssClass="source">
+<p id="790633" class="block-content">Once globalization is enabled, you can access the globalization settings, such as, <tt>Culture</tt>, <tt>Charset</tt>, etc, using </p>
+<com:TTextHighlighter CssClass="source block-content" id="code_790206">
$globalization = $this->getApplication()->getGlobalization();
echo $globalization->Culture;
$globalization->Charset= "GB-2312"; //change the charset
</com:TTextHighlighter>
-<p>You also change the way the culture is determined by changing the <tt>class</tt> attribute in the module configuration. For example, to set the culture that depends on the browser settings, you can use the <tt>TGlobalizationAutoDetect</tt> class.
-<com:TTextHighlighter Language="xml" CssClass="source">
+<p id="790634" class="block-content">You also change the way the culture is determined by changing the <tt>class</tt> attribute in the module configuration. For example, to set the culture that depends on the browser settings, you can use the <tt>TGlobalizationAutoDetect</tt> class.
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_790207">
<module id="globalization" class="TGlobalizationAutoDetect">
...
</module>
</com:TTextHighlighter>
-<p>You may also provide your own globalization class to change how the application culture is set.
+<p id="790635" class="block-content">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 <a href="?page=Configurations.Templates1#tct">template control tags</a>. For example, changing the <tt>Culture</tt> to "zh".</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790208">
<%@ Application.Globalization.Culture="zh" %>
</com:TTextHighlighter>
@@ -104,16 +104,16 @@ Lastly, you can change the globalization settings on page by page basis using <a There are two areas in your application that may need message or string localization, in PHP code and in the templates. To localize strings within PHP, use the <tt>localize</tt> function detailed below. To localize text in the template, use the <a href="#ttranslate">TTranslate</a> component.
<h2 id="6208">Using <tt>localize</tt> function to translate text within PHP</h2>
-<p>The <tt>localize</tt> 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 <tt>$sender</tt> (assuming, say, the sender is a button). The original code before localization is as follows.
-<com:TTextHighlighter CssClass="source">
+<p id="790636" class="block-content">The <tt>localize</tt> 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 <tt>$sender</tt> (assuming, say, the sender is a button). The original code before localization is as follows.
+<com:TTextHighlighter CssClass="source block-content" id="code_790209">
function clickMe($sender,$param)
{
$sender->Text="Hello, world!";
}
</com:TTextHighlighter>
-<p>The hard coded message "Hello, world!" is to be localized using the <tt>localize</tt> function. </p>
-<com:TTextHighlighter CssClass="source">
+<p id="790637" class="block-content">The hard coded message "Hello, world!" is to be localized using the <tt>localize</tt> function. </p>
+<com:TTextHighlighter CssClass="source block-content" id="code_790210">
function clickMe($sender,$param)
{
$sender->Text=Prado::localize("Hello, world!");
@@ -122,60 +122,60 @@ function clickMe($sender,$param) <h2 id="6209">Compound Messages</h2>
-<p>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.</p>
-<com:TTextHighlighter CssClass="source">
+<p id="790638" class="block-content">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.</p>
+<com:TTextHighlighter CssClass="source block-content" id="code_790211">
$num_users = 12;
$message = "There are " . $num_users . " users online.";
</com:TTextHighlighter>
This problem can be solved using the <tt>localize</tt> function with string substitution. For example, the <tt>$message</tt> string above can be constructed as follows.
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_790212">
$num_users = 12;
$message = Prado::localize("There are {num_users} users online.", array('num_users'=>$num_users));
</com:TTextHighlighter>
-<p>Where the second parameter in <tt>localize</tt> takes an associative array with the key as the substitution to find in the text and replaced it with the associated value.
+<p id="790639" class="block-content">Where the second parameter in <tt>localize</tt> takes an associative array with the key as the substitution to find in the text and replaced it with the associated value.
The <tt>localize</tt> function does not solve the problem of localizing languages that have plural forms, the solution is to use <a href="#choice-format">TChoiceFormat</a>.</p>
-<p>The following sample demonstrates the basics of localization in PRADO.</p>
+<p id="790640" class="block-content">The following sample demonstrates the basics of localization in PRADO.</p>
<com:RunBar PagePath="Advanced.Samples.I18N.Home" />
<h1 id="6202">I18N Components</h1>
<a name="ttranslate"></a>
<h2 id="6210">TTranslate</h2>
-<p>Messages and strings can be localized in PHP or in templates.
+<p id="790641" class="block-content">Messages and strings can be localized in PHP or in templates.
To translate a message or string in the template, use <tt>TTranslate</tt>.</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790213">
<com:TTranslate>Hello World</com:TTranslate>
<com:TTranslate Text="Goodbye" />
</com:TTextHighlighter>
-<p><tt>TTranslate</tt> can also perform string substitution.
+<p id="790642" class="block-content"><tt>TTranslate</tt> can also perform string substitution.
The <tt>Parameters</tt> 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 "<tt>Parameters.time=<%= time() %></tt>".
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790214">
<com:TTranslate Parameters.time=<%= time() %> >
The time is {time}.
</com:TTranslate>
</com:TTextHighlighter>
-<p>A short for <tt>TTranslate</tt> is also provided using the following syntax.</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<p id="790643" class="block-content">A short for <tt>TTranslate</tt> is also provided using the following syntax.</p>
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790215">
<%[string]%>
</com:TTextHighlighter>
-<p>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.</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<p id="790644" class="block-content">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.</p>
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790216">
<com:TLabel Text="<%[ Hello World! ]%>" />
</com:TTextHighlighter>
<h2 id="6211">TDateFormat</h2>
-<p>Formatting localized date and time is straight forward.</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<p id="790645" class="block-content">Formatting localized date and time is straight forward.</p>
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790217">
<com:TDateFormat Value="12/01/2005" />
</com:TTextHighlighter>
-<p>The <tt>Pattern</tt> property accepts 4 predefined localized date patterns and 4 predefined localized time patterns.
-<ul>
+<p id="790646" class="block-content">The <tt>Pattern</tt> property accepts 4 predefined localized date patterns and 4 predefined localized time patterns.</p>
+<ul id="u2" class="block-content">
<li><tt>fulldate</tt></li>
<li><tt>longdate</tt></li>
<li><tt>mediumdate</tt></li>
@@ -185,19 +185,20 @@ The time is {time}. <li><tt>mediumtime</tt></li>
<li><tt>shorttime</tt></li>
</ul>
+<p id="p1" class="block-content">
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 <tt>Culture</tt> property.</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790218">
<com:TDateFormat Pattern="fulldate shorttime" />
</com:TTextHighlighter>
-<p>You can also specify a custom pattern using the following sub-patterns.
+<p id="790647" class="block-content">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:
-<com:TTextHighlighter Language="text" CssClass="source">
+<com:TTextHighlighter Language="text" CssClass="source block-content" id="code_790219">
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 </com:TTextHighlighter>
</p>
-<p>The count of pattern letters determine the format.</p>
+<p id="790648" class="block-content">The count of pattern letters determine the format.</p>
-<p>(Text): 4 letters uses full form, less than 4, use short or abbreviated form
+<p id="790649" class="block-content">(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")</p>
-<p>(Number): the minimum number of digits. Shorter numbers are zero-padded
+<p id="790650" class="block-content">(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.</p>
-<p>(Text and Number): 3 or over, use text, otherwise use number. (e.g.,
+<p id="790651" class="block-content">(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".)</p>
-<p>Any characters in the pattern that are not in the ranges of ['a'..'z']
+<p id="790652" class="block-content">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.</p>
-<p>Examples using the US locale:
+<p id="790653" class="block-content">Examples using the US locale:
-<com:TTextHighlighter Language="text" CssClass="source">
+<com:TTextHighlighter Language="text" CssClass="source block-content" id="code_790220">
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 </com:TTextHighlighter>
</p>
-<p>If the <tt>Value</tt> property is not specified, the current date and time is used.</p>
+<p id="790654" class="block-content">If the <tt>Value</tt> property is not specified, the current date and time is used.</p>
<h2 id="6212">TNumberFormat</h2>
-<p>PRADO's Internationalization framework provide localized currency formatting and number formatting. Please note that the <tt>TNumberFormat</tt> component provides formatting only, it does not perform current conversion or exchange.</p>
+<p id="790655" class="block-content">PRADO's Internationalization framework provide localized currency formatting and number formatting. Please note that the <tt>TNumberFormat</tt> component provides formatting only, it does not perform current conversion or exchange.</p>
-<p>Numbers can be formatted as currency, percentage, decimal or scientific
-numbers by specifying the <tt>Type</tt> attribute. The valid types are:
-<ul>
+<p id="790656" class="block-content">Numbers can be formatted as currency, percentage, decimal or scientific
+numbers by specifying the <tt>Type</tt> attribute. The valid types are:</p>
+<ul id="u3" class="block-content">
<li><tt>currency</tt></li>
<li><tt>percentage</tt></li>
<li><tt>decimal</tt></li>
<li><tt>scientific</tt></li>
</ul>
-</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790221">
<com:TNumberFormat Type="currency" Value="100" />
</com:TTextHighlighter>
-<p><tt>Culture</tt> and <tt>Currency</tt> properties may be specified to format locale specific numbers. </p>
+<p id="790657" class="block-content"><tt>Culture</tt> and <tt>Currency</tt> properties may be specified to format locale specific numbers. </p>
-<p>If someone from US want to see sales figures from a store in
+<p id="790658" class="block-content">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 <tt>Culture="de_DE"</tt> to get
the currency right, e.g. 100,00$. The decimal and grouping separator is
then also from the <tt>de_DE</tt> locale. This may lead to some confusion because
people from US uses the "," (comma) as thousand separator. Therefore a <tt>Currency</tt>
attribute is available, so that the output from the following example results in $100.00
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790222">
<com:TNumberFormat Type="currency"
Culture="en_US" Currency="EUR" Value="100" />
</com:TTextHighlighter>
</p>
-<p>The <tt>Pattern</tt> property determines the number of digits, thousand grouping
+<p id="790659" class="block-content">The <tt>Pattern</tt> 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 <tt>Culture</tt> property. The valid
-<tt>Pattern</tt> characters are:
-<ul>
+<tt>Pattern</tt> characters are:</p>
+<ul id="u6" class="block-content">
<li><tt># (hash)</tt> - represents the optional digits</li>
<li><tt>0 (zero)</tt> - represents the mandatory digits, zero left filled</li>
<li><tt>. (full stop)</tt> - the position of the decimal point (only 1 decimal point is allowed)</li>
<li><tt>, (comma)</tt> - thousand point separation (up to 2 commas are allowed)</li>
</ul>
+<p id="p2" class="block-content">
For example, consider the <tt>Value="1234567.12345"</tt> and
with <tt>Culture="en_US"</tt> (which uses "," for thousand point separator and "." for decimal separators).
-<com:TTextHighlighter Language="text" CssClass="source">
+</p>
+<com:TTextHighlighter Language="text" CssClass="source block-content" id="code_790223">
Pattern Output
------- ------
##,###.00 ->> 1,234,567.12
@@ -315,11 +317,11 @@ Pattern Output </p>
<h2 id="6213">TTranslateParameter</h2>
-<p>Compound messages, i.e., string substitution, can be accomplished with <tt>TTranslateParameter</tt>.
+<p id="790660" class="block-content">Compound messages, i.e., string substitution, can be accomplished with <tt>TTranslateParameter</tt>.
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 <tt>TTranslate</tt>.
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790224">
<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 <a name="choice-format"></a>
<h2 id="6214">TChoiceFormat</h2>
-<p>Using the <tt>localize</tt> function or <tt>TTranslate</tt> 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 <tt>number</tt> of apples.</p>
+<p id="790661" class="block-content">Using the <tt>localize</tt> function or <tt>TTranslate</tt> 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 <tt>number</tt> of apples.</p>
-<p>The <tt>TChoiceFormat</tt> component performs message/string choice translation. The following example demonstrated a simple 2 choice message translation.</p>
+<p id="790662" class="block-content">The <tt>TChoiceFormat</tt> component performs message/string choice translation. The following example demonstrated a simple 2 choice message translation.</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_790225">
<com:TChoiceFormat Value="1"/>[1] One Apple. |[2] Two Apples</com:TChoiceFormat>
</com:TTextHighlighter>
-<p>In the above example, the <tt>Value</tt> "1" (one), thus the translated string
+<p id="790663" class="block-content">In the above example, the <tt>Value</tt> "1" (one), thus the translated string
is "One Apple". If the <tt>Value</tt> was "2", then it will show "Two Apples".</p>
-<p>The message/string choices are separated by the pipe "|" followed by a set notation of the form.</p>
-<ul>
+<p id="790664" class="block-content">The message/string choices are separated by the pipe "|" followed by a set notation of the form.</p>
+<ul id="u7" class="block-content">
<li><tt>[1,2]</tt> -- accepts values between 1 and 2, inclusive.</li>
<li><tt>(1,2)</tt> -- accepts values between 1 and 2, excluding 1 and 2.</li>
<li><tt>{1,2,3,4}</tt> -- only values defined in the set are accepted.</li>
@@ -351,7 +353,7 @@ is "One Apple". If the <tt>Value</tt> was "2", then it will show "Two Apples".</ and strictly less than 0</li>
</ul>
-<p>Any non-empty combinations of the delimiters of square and round brackets are acceptable.
+<p id="790665" class="block-content">Any non-empty combinations of the delimiters of square and round brackets are acceptable.
The string chosen for display depends on the <tt>Value</tt> property. The <tt>Value</tt> is evaluated for each set until the <tt>Value</tt> is found to belong to a particular set.</p>
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 @@ <com:TContent ID="body" >
<h1 id="6101">Logging</h1>
-<p>
+<p id="780615" class="block-content">
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,
</p>
<img src="<%~ logrouter.gif %>" alt="Log router" />
<h2 id="6102">Using Logging Functions</h2>
-<p>
+<p id="780616" class="block-content">
The following two methods are provided for logging messages in PRADO,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_780201">
Prado::log($message, $logLevel, $category);
Prado::trace($message, $category);
</com:TTextHighlighter>
-<p>
+<p id="780617" class="block-content">
The difference between <tt>Prado::log()</tt> and <tt>Prado::trace()</tt> is that the latter automatically selects the log level according to the application mode. If the application is in <tt>Debug</tt> mode, stack trace information is appended to the messages. <tt>Prado::trace()</tt> is widely used in the core code of the PRADO framework.
</p>
<h2 id="6103">Message Routing</h2>
-<p>
+<p id="780618" class="block-content">
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 <tt>System.Util.TLogRouter</tt> module. When plugged into an application, it can route the messages to different destination in parallel. Currently, PRADO provides three types of routes:
</p>
-<ul>
+<ul id="u1" class="block-content">
<li><tt>TFileLogRoute</tt> - filtered messages are stored in a specified log file. By default, this file is named <tt>prado.log</tt> under the runtime directory of the application. File rotation is provided.</li>
<li><tt>TEmailLogRoute</tt> - filtered messages are sent to pre-specified email addresses.</li>
<li><tt>TBrowserLogRoute</tt> - filtered messages are appended to the end of the current page output.</li>
</ul>
-<p>
+<p id="780619" class="block-content">
To enable message routing, plug in and configure the <tt>TLogRouter</tt> module in application configuration,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_780202">
<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 <tt>TLogRouter</tt> module Categories="System.Web" />
</module>
</com:TTextHighlighter>
-<p>
+<p id="780620" class="block-content">
In the above, the <tt>Levels</tt> and <tt>Categories</tt> specify the log and category filters to selectively retrieve the messages to the corresponding destinations.
</p>
<h2 id="6104">Message Filtering</h2>
-<p>
+<p id="780621" class="block-content">
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.
</p>
-<p>
+<p id="780622" class="block-content">
Log levels defined in <tt>System.Util.TLogger</tt> include : <tt>DEBUG</tt>, <tt>INFO</tt>, <tt>NOTICE</tt>, <tt>WARNING</tt>, <tt>ERROR</tt>, <tt>ALERT</tt>, <tt>FATAL</tt>. Messages can be filtered according log level criteria. For example, if a filter specifies <tt>WARNING</tt> and <tt>ERROR</tt> levels, then only those messages that are of <tt>WARNING</tt> and <tt>ERROR</tt> will be returned.
</p>
-<p>
+<p id="780623" class="block-content">
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, <tt>System.Web</tt> category is the ancestor of <tt>System.Web.UI</tt> and <tt>System.Web.UI.WebControls</tt> categories. Messages can be selectively retrieved using such hierarchical category filters. For example, if the category filter is <tt>System.Web</tt>, then all messages in the <tt>System.Web</tt> are returned. In addition, messages in the child categories, such as <tt>System.Web.UI.WebControls</tt>, are also returned.
</p>
-<p>
+<p id="780624" class="block-content">
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 <tt>TPage</tt> will be of category <tt>System.Web.UI.TPage</tt>.
</p>
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 @@ <com:TContent ID="body" >
<h1 id="5801">Master and Content</h1>
-<p>
+<p id="750587" class="block-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.
</p>
-<p>
+<p id="750588" class="block-content">
Master and content only apply to template controls (controls extending <tt>TTemplateControl</tt> or its child classes). A template control can have at most one master control and one or several contents (each represented by a <tt>TContent</tt> control). Contents will be inserted into the master control at places reserved by <tt>TContentPlaceHolder</tt> controls. And the presentation of the template control is that of the master control with <tt>TContentPlaceHolder</tt> replaced by <tt>TContent</tt>.
</p>
-<p>
+<p id="750589" class="block-content">
For example, assume a template control has the following template:
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_750192">
<%@ MasterClass="MasterControl" %>
<com:TContent ID="A" >
content A
@@ -22,10 +22,10 @@ content B content B
</com:TContent >
</com:TTextHighlighter>
-<p>
+<p id="750590" class="block-content">
which uses <tt>MasterControl</tt> as its master control. The master control has the following template,
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_750193">
other stuff
<com:TContentPlaceHolder ID="A" />
other stuff
@@ -34,23 +34,23 @@ other stuff <com:TContentPlaceHolder ID="C" />
other stuff
</com:TTextHighlighter>
-<p>
+<p id="750591" class="block-content">
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.
</p>
<img src=<%~ mastercontent.gif %> alt="Master and Content" />
<img src=<%~ pcrelation.gif %> alt="Parent-child relationship between master and content" />
<h2 id="6301">Master vs. External Template</h2>
-<p>
+<p id="750592" class="block-content">
Master is very similar to external templates which are introduced since version 3.0.5. A special <a href="?page=Configurations.Templates1">include tag</a> is used to include an external template file into a base template.
</p>
-<p>
+<p id="750593" class="block-content">
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.
</p>
-<p>
+<p id="750594" class="block-content">
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.
</p>
-<p>
+<p id="750595" class="block-content">
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.
</p>
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 @@ <com:TContent ID="body" >
<h1 id="6401">Performance Tuning</h1>
-<p>
+<p id="810678" class="block-content">
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.
</p>
<h2 id="6402">Caching</h2>
-<p>
+<p id="810679" class="block-content">
PRADO provides a generic caching technique used by in several core parts of the framework. For example, when caching is enabled, <tt>TTemplateManager</tt> will save parsed templates in cache and reuse them in the following requests, which saves time for parsing templates. The <tt>TThemeManager</tt> adopts the similar strategy to deal with theme parsing.
</p>
-<p>
+<p id="810680" class="block-content">
Enabling caching is very easy. Simply add the cache module in the application configuration, and PRADO takes care of the rest.
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_810229">
<modules>
<module id="cache" class="System.Caching.TSqliteCache" />
</modules>
</com:TTextHighlighter>
-<p>
+<p id="810681" class="block-content">
Developers can also take advantage of the caching technique in their applications. The <tt>Cache</tt> property of <tt>TApplication</tt> returns the plugged-in cache module when it is available. To save and retrieve a data item in cache, use the following commands,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_810230">
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);
}
</com:TTextHighlighter>
-<p>
+<p id="810682" class="block-content">
where <tt>$keyName</tt> should be a string that uniquely identifies the data item stored in cache.
</p>
<h2 id="6403">Using <tt>pradolite.php</tt></h2>
-<p>
+<p id="810683" class="block-content">
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 <tt>pradolite.php</tt> is also included. The file is a merge of all core PRADO class files with comments being stripped off and message logging removed.
</p>
-<p>
+<p id="810684" class="block-content">
To use <tt>pradolite.php</tt>, in your application entry script, replace the inclusion of <tt>prado.php</tt> with <tt>pradolite.php</tt>.
</p>
<h2 id="6404">Changing Application Mode</h2>
-<p>
+<p id="810685" class="block-content">
Application mode also affects application performance. A PRADO application can be in one of the following modes: <tt>Off</tt>, <tt>Debug</tt>, <tt>Normal</tt> and <tt>Performance</tt>. The <tt>Debug</tt> mode should mainly be used during application development, while <tt>Normal</tt> 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 <tt>Performance</tt> to further improve the performance.
</p>
-<p>
+<p id="810686" class="block-content">
The difference between <tt>Debug</tt>, <tt>Normal</tt> and <tt>Performance</tt> modes is that under <tt>Debug</tt> mode, application logs will contain debug information, and under <tt>Performance</tt> mode, timestamp checking is not performed for cached templates and published assets. Therefore, under <tt>Performance</tt> mode, application may not run properly if templates or assets are modified. Since <tt>Performance</tt> mode is mainly used when an application is stable, change of templates or assets are not likely.
</p>
-<p>
+<p id="810687" class="block-content">
To switch application mode, configure it in application configuration:
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_810231">
<application Mode="Performance" >
......
</application >
</com:TTextHighlighter>
<h2 id="6405">Reducing Page Size</h2>
-<p>
+<p id="810688" class="block-content">
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 <tt>TDataGrid</tt>, is used. To reduce the size of the network transmitted page size, two strategies can be used.
</p>
-<p>
+<p id="810689" class="block-content">
First, you may disable viewstate by setting <tt>EnableViewState</tt> 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.
</p>
-<p>
+<p id="810690" class="block-content">
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 <tt>StatePersisterClass</tt> property of the page determines which state persistence class to use. By default, it uses <tt>System.Web.UI.TPageStatePersister</tt> 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 <tt>IPageStatePersister</tt> interface. You may configure this property in several places, such as application configuration or page configuration using <pages> or <page> tags,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_810232">
<pages StatePersisterClass="MyPersister1" ... >
<page ID="SpecialPage" StatePersisterClass="MyPersister2" ... />
</pages>
</com:TTextHighlighter>
-<p>
+<p id="810691" class="block-content">
Note, in the above the <tt>SpecialPage</tt> will use <tt>MyPersister2</tt> as its persister class, while the rest pages will use <tt>MyPersister1</tt>. Therefore, you can have different state persister strategies for different pages.
</p>
<h2 id="6406">Other Techniques</h2>
-<p>
+<p id="810692" class="block-content">
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.
</p>
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 <dd>Nachfolgender Prozess der Übersetzung und Anpassung eines Produktes an die kulturellen Konventionen eines gegebenen Marktes.</dd>
</dl>
<p> Die folgenden Merkmale werden von PRADO unterstützt: </p>
-<ul>
+<ul id="u1" class="block-content">
<li>Textübersetzung </li>
<li>Attributübersetzung (noch zu implementieren) </li>
<li>Parameteraustausch (falls erforderlich mit Übersetzung) </li>
diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.es.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.es.page index 31e7de07..b682a0e9 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.es.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.es.page @@ -25,7 +25,7 @@ <dd> Proceso subsecuente de traducir y de adaptar un producto a las convenciones culturales de un mercado dado. </dd>
</dl>
<p> Las características siguientes son utilizadas por PRADO: </p>
-<ul>
+<ul id="u1" class="block-content">
<li>Traducción del texto </li>
<li>Traducción del atributo (todo) </li>
<li>Substitución de parámetro (con la traducción si es necesario) </li>
diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.fr.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.fr.page index 66d01c90..09def8f5 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.fr.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.fr.page @@ -45,7 +45,7 @@ <p>
PRADO offrent les fonctionnalités suivantes :
</p>
- <ul>
+ <ul id="u1" class="block-content">
<li>
Traduction de contenu
<li>
diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.page index 466bbca8..40dbe591 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.page @@ -26,7 +26,7 @@ Your current culture is <%= $this->Page->CurrentCulture %>. <dd>Subsequent process of translating and adapting a product to a given market's cultural conventions.</dd>
</dl>
<p>The following features are supported by PRADO: </p>
-<ul>
+<ul id="u1" class="block-content">
<li>Text translation</li>
<li>Attribute translation</li>
<li>Parameter substitution (with translation if needed) </li>
diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.pl.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.pl.page index 61882fee..7a30aac3 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.pl.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.pl.page @@ -25,7 +25,7 @@ Twoim obecnym językiem jest: <%= $this->Page->CurrentCulture %>. <dd> To kolejny etap, jest to proces tłumaczenia i dostosowywania produktu do konkretnych wymagań językowo-kulturowych.</dd>
</dl>
<p>PRADO obsługuje następujące mechanizmy: </p>
-<ul>
+<ul id="u1" class="block-content">
<li>Tłumaczenie tekstu </li>
<li>Tłumaczenie atrybutów (todo) </li>
<li>Podstawianie parametrów (wraz z koniecznym tłumaczeniem) </li>
diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.zh.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.zh.page index 959f0b8e..c6858a3e 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.zh.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/Home.zh.page @@ -31,7 +31,7 @@ PRADO提供了gettext，XML，SQLite以及MySQL等手段用于存放消息的各 <dd>国际化的一个细节步骤，它针对某个特定的市场文化对产品进行翻译和调整。</dd>
</dl>
<p>PRADO支持以下功能：</p>
-<ul>
+<ul id="u1" class="block-content">
<li>文本翻译</li>
<li>属性翻译（尚未完成）</li>
<li>参数替换（如需要可进行翻译）</li>
diff --git a/demos/quickstart/protected/pages/Advanced/Samples/I18N/zh_TW/Home.page b/demos/quickstart/protected/pages/Advanced/Samples/I18N/zh_TW/Home.page index 329a7669..d9129c14 100644 --- a/demos/quickstart/protected/pages/Advanced/Samples/I18N/zh_TW/Home.page +++ b/demos/quickstart/protected/pages/Advanced/Samples/I18N/zh_TW/Home.page @@ -30,7 +30,7 @@ <dd>國際化的一個細節步驟，它針對某個特定的市場文化對產品進行翻譯和調整。</dd>
</dl>
<p>PRADO支持以下功能：</p>
- <ul>
+ <ul id="u1" class="block-content">
<li>文本翻譯</li>
<li>屬性翻譯（尚未完成）</li>
<li>參數替換（如需要可進行翻譯）</li>
diff --git a/demos/quickstart/protected/pages/Advanced/Scripts.page b/demos/quickstart/protected/pages/Advanced/Scripts.page index 8fa1e27e..08061182 100644 --- a/demos/quickstart/protected/pages/Advanced/Scripts.page +++ b/demos/quickstart/protected/pages/Advanced/Scripts.page @@ -4,11 +4,11 @@ This guide is based on the <a href="http://www.sergiopereira.com/articles/advjs. Quick guide to somewhat advanced JavaScript tour of some OO features</a> by Sergio Pereira.
<h2 id="6502">Hey, I didn't know you could do that</h2>
-<p>
+<p id="820693" class="block-content">
If you are a web developer and come from the same place I do, you have probably
used quite a bit of Javascript in your web pages, mostly as UI glue.
</p>
-<p>
+<p id="820694" class="block-content">
Until recently, I knew that Javascript had more OO capabilities than I was employing,
but I did not feel like I needed to use it. As the browsers started to support a more
@@ -16,7 +16,7 @@ Quick guide to somewhat advanced JavaScript tour of some OO features</a> by Serg complex and functional code to run on the client. That helped giving birth to the
AJAX phenomena.
</p>
-<p>
+<p id="820695" class="block-content">
As we all start to learn what it takes to write our cool, AJAX applications, we begin
to notice that the Javascript we used to know was really just the tip of the iceberg.
We now see Javascript being used beyond simple UI chores like input validation and frivolous
@@ -25,7 +25,7 @@ Quick guide to somewhat advanced JavaScript tour of some OO features</a> by Serg hierarchies, patterns, and many other things we got used to seeing only in our server
side code.
</p>
-<p>
+<p id="820696" class="block-content">
In many ways we can say that suddenly the bar was put much higher than before. It takes
a heck lot more proficiency to write applications for the new Web and we need to improve
our Javascript skills to get there.
@@ -43,28 +43,28 @@ Quick guide to somewhat advanced JavaScript tour of some OO features</a> by Serg that before.
</p>
-<p>
+<p id="820697" class="block-content">
The purpose of this article is precisely explaining the types of constructs that
many of us are not familiar with yet.
</p>
<h2 id="6503">JSON (JavaScript Object Notation)</h2>
-<p>
+<p id="820698" class="block-content">
JavaScript Object Notation (<a href="http://www.json.org/">JSON</a>,) is one of the new
buzzwords popping up around the AJAX theme. JSON, simply put, is a way of
declaring an object in Javascript. Let's see an example right away and note
how simple it is.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820233">
var myPet = { color: 'black', leg_count: 4, communicate: function(repeatCount){
for(i=0;i<repeatCount;i++) alert('Woof!');} };
</com:TTextHighlighter>
-<p>
+<p id="820699" class="block-content">
Let's just add little bit of formatting so it looks more like how we usually find out there:
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820234">
var myPet =
{
color: 'black',
@@ -76,7 +76,7 @@ var myPet = }
};
</com:TTextHighlighter>
-<p>
+<p id="820700" class="block-content">
Here we created a reference to an object with two properties (<tt>color</tt>
and <tt>legCount</tt>) and a method (<tt>communicate</tt>.)
It's not hard to figure out that the object's properties and methods
@@ -88,28 +88,28 @@ var myPet = we can use it like this:
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820235">
alert('my pet is ' + myPet.color);
alert('my pet has ' + myPet.legCount + ' legs');
//if you are a dog, bark three times:
myPet.communicate(3);
</com:TTextHighlighter>
-<p>
+<p id="820701" class="block-content">
You'll see JSON used pretty much everywhere in JS these days, as arguments to functions,
as return values, as server responses (in strings,) etc.
</p>
<h2 id="6504">What do you mean? A function is an object too?</h2>
-<p>
+<p id="820702" class="block-content">
This might be unusual to developers that never thought about that, but in JS a function is
also an object. You can pass a function around as an argument to another function just like
you can pass a string, for example. This is extensively used and very handy.
</p>
-<p>
+<p id="820703" class="block-content">
Take a look at this example. We will pass functions to another function that will use them.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820236">
var myDog =
{
bark: function()
@@ -137,56 +137,56 @@ annoyThePet(myDog.bark); //annoy the cat:
annoyThePet(myCat.meow);
</com:TTextHighlighter>
-<p>
+<p id="820704" class="block-content">
Note that we pass myDog.bark and myCat.meow without appending parenthesis
<tt>"()"</tt> to them. If we did that we would not be passing
the function, rather we would be calling the method and passing the return value,
<tt>undefined</tt> in both cases here.
</p>
-<p>
+<p id="820705" class="block-content">
If you want to make my lazy cat start barking, you can easily do this:
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820237">
myCat.meow = myDog.bark;
myCat.meow(); //alerts 'Woof!'
</com:TTextHighlighter>
<h2 id="6505">Arrays, items, and object members</h2>
-<p>
+<p id="820706" class="block-content">
The following two lines in JS do the same thing.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820238">
var a = new Array();
var b = [];
</com:TTextHighlighter>
-<p>
+<p id="820707" class="block-content">
As I'm sure you already know, you can access individual items in an array
by using the square brackets:
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820239">
var a = ['first', 'second', 'third'];
var v1 = a[0];
var v2 = a[1];
var v3 = a[2];
</com:TTextHighlighter>
-<p>
+<p id="820708" class="block-content">
But you are not limited to numeric indices. You can access any member of a JS
object by using its name, in a string. The following example creates an empty
object, and adds some members by name.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820240">
var obj = {}; //new, empty object
obj['member_1'] = 'this is the member value';
obj['flag_2'] = false;
obj['some_function'] = function(){ /* do something */};
</com:TTextHighlighter>
-<p>
+<p id="820709" class="block-content">
The above code has identical effect as the following:
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820241">
var obj =
{
member_1:'this is the member value',
@@ -195,24 +195,24 @@ var obj = };
</com:TTextHighlighter>
-<p>
+<p id="820710" class="block-content">
In many ways, the idea of objects and associative arrays (hashes) in JS are not
distiguishable. The following two lines do the same thing too.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820242">
obj.some_function();
obj['some_function']();
</com:TTextHighlighter>
<h2 id="6506">Enough about objects, may I have a class now?</h2>
-<p>
+<p id="820711" class="block-content">
The great power of object oriented programming languages derive from the use
of classes. I don't think I would have guessed how classes are defined in JS
using only my previous experience with other languages. Judge for yourself.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820243">
//defining a new class called Pet
var Pet = function(petName, age)
{
@@ -224,7 +224,7 @@ var Pet = function(petName, age) var famousDog = new Pet('Santa\'s Little Helper', 15);
alert('This pet is called ' + famousDog.name);
</com:TTextHighlighter>
-<p>
+<p id="820712" class="block-content">
Let's see how we add a method to our <tt>Pet</tt> class. We will be using the
<tt>prototype</tt> property that all classes have. The <tt>prototype</tt>
property is an object that contains all the members that any object of the class will have.
@@ -233,17 +233,17 @@ alert('This pet is called ' + famousDog.name); can add methods and properties to and make any object of that class automatically gain this new member.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820244">
Pet.prototype.communicate = function()
{
alert('I do not know what I should say, but my name is ' + this.name);
};
</com:TTextHighlighter>
-<p>
+<p id="820713" class="block-content">
That's when a library like <a href="http://www.sergiopereira.com/articles/prototype.js.html">prototype.js</a> comes in
handy. If we are using prototype.js, we can make our code look cleaner (at least in my opinion.)
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820245">
var Pet = Class.create();
Pet.prototype =
{
@@ -262,23 +262,23 @@ Pet.prototype = </com:TTextHighlighter>
<h2 id="6507">Functions as arguments, an interesting pattern</h2>
-<p>
+<p id="820714" class="block-content">
If you have never worked with languages that support closures
you may find the following idiom too funky.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820246">
var myArray = ['first', 'second', 'third'];
myArray.each( function(item, index)
{
alert('The item in the position #' + index + ' is:' + item);
});
</com:TTextHighlighter>
-<p>
+<p id="820715" class="block-content">
Whoa! Let's explain what is going on here before you decide I've gone too
far and navigate to a better article than this one.
</p>
-<p>
+<p id="820716" class="block-content">
First of all, in the above example we are using the prototype.js library, which
adds the each function to the Array class. The each function accepts one
argument that is a function object. This function, in turn, will be called once
@@ -286,7 +286,7 @@ myArray.each( function(item, index) for the current item. Let's call this function our iterator function.
We could have also written the code like this.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820247">
function myIterator(item, index)
{
alert('The item in the position #' + index + ' is:' + item);
@@ -295,7 +295,7 @@ function myIterator(item, index) var myArray = ['first', 'second', 'third'];
myArray.each( myIterator );
</com:TTextHighlighter>
-<p>
+<p id="820717" class="block-content">
But then we would not be doing like all the cool kids in school, right?
More seriously, though, this last format is simpler to understand but causes
us to jump around in the code looking for the myIterator function. It's nice
@@ -305,20 +305,20 @@ myArray.each( myIterator ); </p>
<h2 id="6508">This is <tt>this</tt> but sometimes <tt>this</tt> is also that</h2>
-<p>
+<p id="820718" class="block-content">
One of the most common troubles we have with JS when we start writing our code
it the use of the <tt>this</tt> keyword. It could be a real
tripwire.
</p>
-<p>
+<p id="820719" class="block-content">
As we mentioned before, a function is also an object in JS, and sometimes we
do not notice that we are passing a function around.
</p>
-<p>
+<p id="820720" class="block-content">
Take this code snippet as an example.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820248">
function buttonClicked()
{
alert('button ' + this.id + ' was clicked');
@@ -329,28 +329,28 @@ var myButton2 = document.getElementById('someOtherButtonID'); myButton.onclick = buttonClicked;
myButton2.onclick = buttonClicked;
</com:TTextHighlighter>
-<p>
+<p id="820721" class="block-content">
Because the buttonClicked function is defined outside any object we may tend to
think the <tt>this</tt> keyword will contain a reference to
the <tt>window</tt> or <tt>document</tt>
object (assuming this code is in the middle of an HTML page viewed in a browser.)
</p>
-<p>
+<p id="820722" class="block-content">
But when we run this code we see that it works as intended and displays the <tt>id</tt> of
the clicked button. What happened here is that we made the onclick method of each button contain the
<tt>buttonClicked</tt> object reference, replacing whatever was there before. Now
whenever the button is clicked, the browser will execute something similar to the following line.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820249">
myButton.onclick();
</com:TTextHighlighter>
-<p>
+<p id="820723" class="block-content">
That isn't so confusing afterall, is it? But see what happens you start having other
objects to deal with and you want to act on these object upon events like the button's click.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820250">
var myHelper =
{
formFields: [ ],
@@ -376,7 +376,7 @@ myHelper.emptyAllFields(); var clearButton = document.getElementById('btnClear');
clearButton.onclick = myHelper.emptyAllFields;
</com:TTextHighlighter>
-<p>
+<p id="820724" class="block-content">
So you think, nice, now I can click the Clear button on my page and those three text boxes
will be emptied. Then you try clicking the button only to get a runtime error. The error
will be related to (guess what?) the <tt>this</tt> keyword.
@@ -385,13 +385,13 @@ clearButton.onclick = myHelper.emptyAllFields; precisely what's happening. One quick solution would be to rewrite our last line of code.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_820251">
clearButton.onclick = function()
{
myHelper.emptyAllFields();
};
</com:TTextHighlighter>
-<p>
+<p id="820725" class="block-content">
That way we create a brand new function that calls our helper method within the helper object's context.
</p>
</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Advanced/Scripts1.page b/demos/quickstart/protected/pages/Advanced/Scripts1.page index 7079582a..35efb2c1 100644 --- a/demos/quickstart/protected/pages/Advanced/Scripts1.page +++ b/demos/quickstart/protected/pages/Advanced/Scripts1.page @@ -5,20 +5,20 @@ This guide is based on the <a href="http://www.sergiopereira.com/articles/protot Developer Notes for prototype.js</a> by Sergio Pereira.
<h2 id="6603">What is that?</h2>
-<p>
+<p id="830726" class="block-content">
In case you haven't already used it, <a href="http://prototype.conio.net">prototype.js</a> is a
JavaScript library written by <a href="http://www.conio.net">Sam Stephenson</a>.
This amazingly well thought and well written piece of <b>standards-compliant</b> code takes a lot of
the burden associated with creating rich, highly interactive web pages that characterize the Web 2.0 off your back.
</p>
-<p>
+<p id="830727" class="block-content">
If you tried to use this library recently, you probably noticed that documentation is not one
of its strongest points. As many other developers before me, I got my head around prototype.js by
reading the source code and experimenting with it. I thought it would be nice to take notes while
I learned and share with everybody else.
</p>
-<p>
+<p id="830728" class="block-content">
As you read the examples and the reference, developers familiar with the Ruby
programming language will notice an intentional similarity between Ruby's
built-in classes and many of the extensions implemented by this library.
@@ -26,24 +26,24 @@ In case you haven't already used it, <a href="http://prototype.conio.net">protot <h2 id="6604">Using the <tt>$()</tt> function</h2>
-<p>
+<p id="830729" class="block-content">
The <tt>$()</tt> function is a handy shortcut to the all-too-frequent <tt>document.getElementById()</tt> function
of the DOM. Like the DOM function, this one returns the element that has the id passed as an argument.
</p>
-<p>
+<p id="830730" class="block-content">
Unlike the DOM function, though, this one goes further. You can pass more than one id and
<tt>$()</tt> will return an <tt>Array</tt> object with
all the requested elements. The example below should illustrate this.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_830252">
<com:TClientScript UsingClientScripts="prado" />
<div id="myDiv">
- <p>This is a paragraph</p>
+ <p id="830731" class="block-content">This is a paragraph</p>
</div>
<div id="myOtherDiv">
- <p>This is another paragraph</p>
+ <p id="830732" class="block-content">This is another paragraph</p>
</div>
<input type="button" value=Test1 onclick="test1();" />
@@ -68,18 +68,18 @@ function test2() /*]]>*/
</script>
</com:TTextHighlighter>
-<p>
+<p id="830733" class="block-content">
Another nice thing about this function is that you can pass either the <tt>id</tt> string or the element object itself,
which makes this function very useful when creating other functions that can also take either form of argument.
</p>
<h2 id="6605">Using the <tt>$F()</tt> function</h2>
-<p>
+<p id="830734" class="block-content">
The <tt>$F()</tt> function is a another welcome shortcut. It returns the value of any field input control,
like text boxes or drop-down lists. The function can take as argument either the element <tt>id</tt> or the element object itself.
</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_830253">
<input type="text" id="userName" value="Joe Doe" />
<input type="button" value=Test3 onclick="test3();" />
diff --git a/demos/quickstart/protected/pages/Advanced/Scripts2.page b/demos/quickstart/protected/pages/Advanced/Scripts2.page index 2c9ce220..97d05897 100644 --- a/demos/quickstart/protected/pages/Advanced/Scripts2.page +++ b/demos/quickstart/protected/pages/Advanced/Scripts2.page @@ -3,16 +3,16 @@ <h2 id="6702">Basic event handling</h2>
-<p>The syntax for working with events looks like the code below.</p>
+<p id="840735" class="block-content">The syntax for working with events looks like the code below.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840254">
Event.observe(element, name, observer, [useCapture]);
</com:TTextHighlighter>
-<p>Assuming for a moment that we want to observe when a link was clicked,
+<p id="840736" class="block-content">Assuming for a moment that we want to observe when a link was clicked,
we could do the following:</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840255">
// <a id="clicker" href="http://foo.com">Click me</a>
Event.observe('clicker', 'click', function(event)
{
@@ -20,9 +20,9 @@ Event.observe('clicker', 'click', function(event) });
</com:TTextHighlighter>
-<p>If we wanted to get the element that fired the event, we'd do this:</p>
+<p id="840737" class="block-content">If we wanted to get the element that fired the event, we'd do this:</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840256">
Event.observe('clicker', 'click', function(event)
{
alert(Event.element(event));
@@ -31,9 +31,9 @@ Event.observe('clicker', 'click', function(event) <h2 id="6703">Observing keystrokes</h2>
-<p>If we wanted to observe keystrokes for the entire document, we could do the following:</p>
+<p id="840738" class="block-content">If we wanted to observe keystrokes for the entire document, we could do the following:</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840257">
Event.observe(document, 'keypress', function(event)
{
if(Event.keyCode(event) == Event.KEY_TAB)
@@ -41,31 +41,31 @@ Event.observe(document, 'keypress', function(event) });
</com:TTextHighlighter>
-<p>And lets say we wanted to keep track of what has been typed :</p>
+<p id="840739" class="block-content">And lets say we wanted to keep track of what has been typed :</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840258">
Event.observe('search', 'keypress', function(event)
{
Element.update('search-results', $F(Event.element(event)));
});
</com:TTextHighlighter>
-<p>Prototype defines properties inside the event object for some
+<p id="840740" class="block-content">Prototype defines properties inside the event object for some
of the more common keys, so feel free to dig around in Prototype to
see which ones those are.</p>
-<p>A final note on keypress events; If you'd like to detect a
+<p id="840741" class="block-content">A final note on keypress events; If you'd like to detect a
left click you can use <tt>Event.isLeftClick(event)</tt>.</p>
<h2 id="6704">Getting the coordinates of the mouse pointer</h2>
-<p>Drag and drop, dynamic element resizing, games, and
+<p id="840742" class="block-content">Drag and drop, dynamic element resizing, games, and
much more all require the ability to track the X and Y location of
the mouse. Prototype makes this fairly simple. The code below tracks
the X and Y position of the mouse and spits out those values into
an input box named mouse.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840259">
Event.observe(document, 'mousemove', function(event)
{
$('mouse').value = "X: " + Event.pointerX(event) +
@@ -73,23 +73,23 @@ Event.observe(document, 'mousemove', function(event) });
</com:TTextHighlighter>
-<p>If we wanted to observe the mouse location when it was
+<p id="840743" class="block-content">If we wanted to observe the mouse location when it was
hovering over a certain element, we'd just change the document argument to
the id or element that was relevant.</p>
<h2 id="6705">Stopping Propagation</h2>
-<p><tt>Event.stop(event)</tt> will stop the propagation of an event .</p>
+<p id="840744" class="block-content"><tt>Event.stop(event)</tt> will stop the propagation of an event .</p>
<h2 id="6706">Events, Binding, and Objects</h2>
-<p>Everything has been fairly straight forward so far, but things
+<p id="840745" class="block-content">Everything has been fairly straight forward so far, but things
start getting a little trickier when you need to work with events in
and object-oriented environment. You have to deal with binding and funky
looking syntax that might take a moment to get your head around.</p>
-<p>Lets look at some code so you can get a better understanding of what I'm talking about.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<p id="840746" class="block-content">Lets look at some code so you can get a better understanding of what I'm talking about.</p>
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840260">
EventDispenser = Class.create();
EventDispenser.prototype =
{
@@ -141,15 +141,15 @@ EventDispenser.prototype = }
}
</com:TTextHighlighter>
-<p>Whoa! What's going on here? Well, we've defined our a
+<p id="840747" class="block-content">Whoa! What's going on here? Well, we've defined our a
custom class <tt>EventDispenser</tt>. We're going to be using this class
to setup events for our document. Most of this code is a
rewrite of the code we looked at earlier except this time, we
are working from inside an object.</p>
-<p>Looking at the <tt>initialize</tt> method, we can really see how
+<p id="840748" class="block-content">Looking at the <tt>initialize</tt> method, we can really see how
things are different now. Take a look at the code below:</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840261">
// Observe clicks on our list items
$$(this.list + " li").each(function(item)
{
@@ -157,82 +157,82 @@ $$(this.list + " li").each(function(item) }.bind(this));
</com:TTextHighlighter>
-<p>We've got iterators, binding and all sorts of stuff going on.
+<p id="840749" class="block-content">We've got iterators, binding and all sorts of stuff going on.
Lets break down what this chunk of code is doing.</p>
-<p>First we are hunting for a collection of elements based on
+<p id="840750" class="block-content">First we are hunting for a collection of elements based on
it's CSS selector. This uses the Prototype selector function <tt>$$()</tt>.
After we've found the list items we are dealing with we send
those into an each iteration where we will add our observers.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840262">
Event.observe(item, 'click', this.showTagName.bindEvent(this));
</com:TTextHighlighter>
-<p>Now looking at the code above, you'll notice the <tt>bindEvent</tt> function.
+<p id="840751" class="block-content">Now looking at the code above, you'll notice the <tt>bindEvent</tt> function.
This takes the method before it <tt>showTagName</tt> and treats it as the
method that will be triggered when, in this case,
someone clicks one of our list items.</p>
-<p>You'll also notice we pass this as an argument to the <tt>bindEvent</tt> function.
+<p id="840752" class="block-content">You'll also notice we pass this as an argument to the <tt>bindEvent</tt> function.
This simply allows us to reference the object in context <tt>EventDispenser</tt>
inside our function <tt>showTagName(event)</tt>. If the <tt>showTagName</tt> function
requires additional parameters, you can attach them to the later parameters of <tt>bindEvent</tt>. For example</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840263">
this.showTagName.bindEvent(this, param1, param2);
//where the showTagName function is defined as
showTime : function (event, param1, param2) { ... }
</com:TTextHighlighter>
-<p>Moving on, you'll see <tt>bind(this)</tt> attached to our iterator function.
+<p id="840753" class="block-content">Moving on, you'll see <tt>bind(this)</tt> attached to our iterator function.
This really has nothing to do with events, it is only here to allow me to
use <tt>this</tt> inside the iterator. If we did not use <tt>bind(this)</tt>, I could not
reference the method <tt>showTagName</tt> inside the iterator.</p>
-<p>Ok, so we'll move on to looking at our methods that actually get
+<p id="840754" class="block-content">Ok, so we'll move on to looking at our methods that actually get
called when an event occurs. Since we've been dealing with <tt>showTagName</tt>, lets look at it.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840264">
showTagName: function(event)
{
alert(Event.element(event).tagName);
}
</com:TTextHighlighter>
-<p>As you can see, this function accepts one argument--the event.
+<p id="840755" class="block-content">As you can see, this function accepts one argument--the event.
In order for us to get the element which fired the event we need to
pass that argument to <tt>Event.element</tt>. Now we can manipulate it at will.</p>
-<p>This covers the most confusing parts of our code. The text above is also
+<p id="840756" class="block-content">This covers the most confusing parts of our code. The text above is also
relevant to the remaining parts of our code. If there is anything about
this you don't understand, feel free to ask questions in the forum.</p>
<h2 id="6707">Removing Event Listeners</h2>
-<p>This one threw me for a loop the first time I tried to use it.
+<p id="840757" class="block-content">This one threw me for a loop the first time I tried to use it.
I tried something similar to what I did in the <tt>Event.observe</tt>
call with the exception of using <tt>stopObserving</tt>, but nothing seemed
to change. In other words, the code below does <b>NOT</b> work.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840265">
$$(this.list + " li").each(function(item)
{
Event.stopObserving(item, 'click', this.showTagName);
}.bind(this));
</com:TTextHighlighter>
-<p>What's the deal here? The reason this does not work is because there
+<p id="840758" class="block-content">What's the deal here? The reason this does not work is because there
is no pointer to the observer. This means that when we passed <tt>this.showTagName</tt>
in the <tt>Event.observe</tt> method before hand, we passed it as an
anonymous function. We can't reference an anonymous function
because it simply does not have a pointer.</p>
-<p>So how do we get the job done? All we need to do is give the
+<p id="840759" class="block-content">So how do we get the job done? All we need to do is give the
observing function a pointer, or the jargon free version: Set a variable
that points to <tt>this.showTagName</tt>. Ok, lets change our code a bit.</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840266">
this.showTagObserver = this.showTagName.bindEvent(this);
// Observe clicks on our list items
@@ -242,8 +242,8 @@ $$(this.list + " li").each(function(item) }.bind(this));
</com:TTextHighlighter>
-<p>Now we can remove the event listeners from our list like this:</p>
-<com:TTextHighlighter Language="javascript" CssClass="source">
+<p id="840760" class="block-content">Now we can remove the event listeners from our list like this:</p>
+<com:TTextHighlighter Language="javascript" CssClass="source block-content" id="code_840267">
$$(this.list + " li").each(function(item)
{
Event.stopObserving(item, 'click', this.showTagObserver);
diff --git a/demos/quickstart/protected/pages/Advanced/Scripts3.page b/demos/quickstart/protected/pages/Advanced/Scripts3.page index 8ba6d5c8..1839f782 100644 --- a/demos/quickstart/protected/pages/Advanced/Scripts3.page +++ b/demos/quickstart/protected/pages/Advanced/Scripts3.page @@ -1,19 +1,19 @@ <com:TContent ID="body" >
<h1 id="6801">Javascript in PRADO, Questions and Answers</h1>
<h2 id="6802">How do I include the predefined Javascript libraries?</h2>
-<ul><li>Adding libraries in the template
-<com:TTextHighlighter Language="prado" CssClass="source">
+<ul id="u1" class="block-content"><li>Adding libraries in the template
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_850268">
<com:TClientScript UsingPradoScripts="effects" />
</com:TTextHighlighter>
</li>
<li>Adding libraries in PHP code
- <com:TTextHighlighter Language="php" CssClass="source">
+ <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_850269">
$this->getPage()->getClientScript()->registerPradoScript("effects");
</com:TTextHighlighter>
</li>
</ul>
The available packaged libraries included in Prado are
-<ul>
+<ul id="u2" class="block-content">
<li><tt>prado</tt> : basic PRADO javascript framework based on Prototype</li>
<li><tt>effects</tt> : visual effects from script.aculo.us</li>
<li><tt>ajax</tt> : ajax and callback related based on Prototype</li>
@@ -24,12 +24,12 @@ The available packaged libraries included in Prado are <li><tt>colorpicker</tt> : colorpicker</li>
</ul>
-<p>The dependencies for each library are automatically resolved. Components
+<p id="850761" class="block-content">The dependencies for each library are automatically resolved. Components
that require a particular library will also automatically load the necessary libraries.
For example, if you add a TDatePicker component on the page, the <tt>datepicker</tt>
and its dependencies will be automatically included on the page.</p>
-<p>See <a href="?page=Controls.ClientScript">TClientScript</a> for options of adding
+<p id="850762" class="block-content">See <a href="?page=Controls.ClientScript">TClientScript</a> for options of adding
your custom Javascript code to the page.</p>
</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Advanced/Security.page b/demos/quickstart/protected/pages/Advanced/Security.page index 3dbfe0ab..89a335dd 100644 --- a/demos/quickstart/protected/pages/Advanced/Security.page +++ b/demos/quickstart/protected/pages/Advanced/Security.page @@ -3,75 +3,75 @@ <h1 id="5601">Security</h1>
<h2 id="5602">Viewstate Protection</h2>
-<p>
+<p id="730563" class="block-content">
Viewstate lies at the heart of PRADO. Viewstate represents data that can be used to restore pages to the state that is last seen by end users before making the current request. By default, PRADO uses hidden fields to store viewstate information.
</p>
-<p>
+<p id="730564" class="block-content">
It is extremely important to ensure that viewstate is not tampered by end users. Without protection, malicious users may inject harmful code into viewstate and unwanted instructions may be performed when page state is being restored on server side.
</p>
-<p>
+<p id="730565" class="block-content">
To prevent viewstate from being tampered, PRADO enforces viewstate HMAC (Keyed-Hashing for Message Authentication) check before restoring viewstate. Such a check can detect if the viewstate has been tampered or not by end users. Should the viewstate is modified, PRADO will stop restoring the viewstate and return an error message.
</p>
-<p>
+<p id="730566" class="block-content">
HMAC check requires a private key that should be secret to end users. Developers can either manually specify a key or let PRADO automatically generate a key. Manually specified key is useful when the application runs on a server farm. To do so, configure <tt>TSecurityManager</tt> in application configuration,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_730186">
<modules>
<module id="security"
class="TSecurityManager"
ValidationKey="my private key" />
</modules>
</com:TTextHighlighter>
-<p>
+<p id="730567" class="block-content">
HMAC check does not prevent end users from reading the viewstate content. An added security measure is to encrypt the viewstate information so that end users cannot decipher it. To enable viewstate encryption, set the <tt>EnableStateEncryption</tt> of pages to true. This can be done in <a href="?page=Configurations.PageConfig">page configurations</a> or in page code. Note, encrypting viewstate may degrade the application performance. A better strategy is to store viewstate on the server side, rather than the default hidden field.
</p>
<h2 id="5603">Cross Site Scripting Prevention</h2>
-<p>
+<p id="730568" class="block-content">
Cross site scripting (also known as XSS) occurs when a web application gathers malicious data from a user. Often attackers will inject JavaScript, VBScript, ActiveX, HTML, or Flash into a vulnerable application to fool other application users and gather data from them. For example, a poorly design forum system may display user input in forum posts without any checking. An attacker can then inject a piece of malicious JavaScript code into a post so that when other users read this post, the JavaScript runs unexpectedly on their computers.
</p>
-<p>
+<p id="730569" class="block-content">
One of the most important measures to prevent XSS attacks is to check user input before displaying them. One can do HTML-encoding with the user input to achieve this goal. However, in some situations, HTML-encoding may not be preferable because it disables all HTML tags.
</p>
-<p>
+<p id="730570" class="block-content">
PRADO incorporates the work of <a href="http://pixel-apes.com/safehtml/">SafeHTML</a> and provides developers with a useful component called <tt>TSafeHtml</tt>. By enclosing content within a <tt>TSafeHtml</tt> component tag, the enclosed content are ensured to be safe to end users. In addition, the commonly used <tt>TTextBox</tt> has a <tt>SafeText</tt> property which contains user input that are ensured to be safe if displayed directly to end users.
</p>
<h2 id="5604">Cookie Attack Prevention</h2>
-<p>
+<p id="730571" class="block-content">
Protecting cookies from being attacked is of extreme important, as session IDs are commonly stored in cookies. If one gets hold of a session ID, he essentially owns all relevant session information.
</p>
-<p>
+<p id="730572" class="block-content">
There are several countermeasures to prevent cookies from being attacked.
</p>
-<ul>
+<ul id="u1" class="block-content">
<li>An application can use SSL to create a secure communication channel and only pass the authentication cookie over an HTTPS connection. Attackers are thus unable to decipher the contents in the transferred cookies.</li>
<li>Expire sessions appropriately, including all cookies and session tokens, to reduce the likelihood of being attacked.</li>
<li>Prevent <a href="?page=Security.XSS">cross-site scripting (XSS)</a> which causes arbitrary code to run in a user's browser and expose his cookies.</li>
<li>Validate cookie data and detect if they are altered.</li>
</ul>
-<p>
+<p id="730573" class="block-content">
PRADO implements a cookie validation scheme that prevents cookies from being modified. In particular, it does HMAC check for the cookie values if cookie validation is enable.
</p>
-<p>
+<p id="730574" class="block-content">
Cookie validation is disabled by default. To enable it, configure the <tt>THttpRequest</tt> module as follows,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_730187">
<modules>
<module id="request" class="THttpRequest" EnableCookieValidation="true" />
</modules>
</com:TTextHighlighter>
-<p>
+<p id="730575" class="block-content">
To make use of cookie validation scheme provided by PRADO, you also need to retrieve cookies through the <tt>Cookies</tt> collection of <tt>THttpRequest</tt> by using the following PHP statements,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_730188">
foreach($this->Request->Cookies as $cookie)
// $cookie is of type THttpCookie
</com:TTextHighlighter>
-<p>
+<p id="730576" class="block-content">
To send cookie data encoded with validation information, create new <tt>THttpCookie</tt> objects and add them to the <tt>Cookies</tt> collection of <tt>THttpResponse</tt>,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_730189">
$cookie=new THttpCookie($name,$value);
$this->Response->Cookies[]=$cookie;
</com:TTextHighlighter>
diff --git a/demos/quickstart/protected/pages/Advanced/State.page b/demos/quickstart/protected/pages/Advanced/State.page index 6e7e7f99..02958e05 100644 --- a/demos/quickstart/protected/pages/Advanced/State.page +++ b/demos/quickstart/protected/pages/Advanced/State.page @@ -1,53 +1,53 @@ <com:TContent ID="body" >
<h1 id="6001">Persistent State</h1>
-<p>
+<p id="770606" class="block-content">
Web applications often need to remember what an end user has done in previous page requests so that the new page request can be served accordingly. State persistence is to address this problem. Traditionally, if a page needs to keep track of user interactions, it will resort to session, cookie, or hidden fields. PRADO provides a new line of state persistence schemes, including view state, control state, and application state.
</p>
<h2 id="6002">View State</h2>
-<p>
+<p id="770607" class="block-content">
View state lies at the heart of PRADO. With view state, Web pages become stateful and are capable of restoring pages to the state that end users interacted with before the current page request. Web programming thus resembles to Windows GUI programming, and developers can think continuously without worrying about the round trips between end users and the Web server. For example, with view state, a textbox control is able to detect if the user input changes the content in the textbox.
</p>
-<p>
+<p id="770608" class="block-content">
View state is only available to controls. View state of a control can be disabled by setting its <tt>EnableViewState</tt> property to false. To store a variable in view state, call the following,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_770197">
$this->setViewState('Caption',$caption);
</com:TTextHighlighter>
-<p>
+<p id="770609" class="block-content">
where <tt>$this</tt> refers to the control object, <tt>Caption</tt> is a unique key identifying the <tt>$caption</tt> variable stored in viewstate. To retrieve the variable back from view state, call the following,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_770198">
$caption = $this->getViewState('Caption');
</com:TTextHighlighter>
<h2 id="6003">Control State</h2>
-<p>
+<p id="770610" class="block-content">
Control state is like view state in every aspect except that control state cannot be disabled. Control state is intended to be used for storing crucial state information without which a page or control may not work properly.
</p>
-<p>
+<p id="770611" class="block-content">
To store and retrieve a variable in control state, use the following commands,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_770199">
$this->setControlState('Caption',$caption);
$caption = $this->getControlState('Caption');
</com:TTextHighlighter>
<h2 id="6004">Application State</h2>
-<p>
+<p id="770612" class="block-content">
Application state refers to data that is persistent across user sessions and page requests. A typical example of application state is the user visit counter. The counter value is persistent even if the current user session terminates. Note, view state and control state are lost if the user requests for a different page, while session state is lost if the user session terminates.
</p>
-<p>
+<p id="770613" class="block-content">
To store and retrieve a variable in application state, use the following commands,
</p>
-<com:TTextHighlighter CssClass="source">
+<com:TTextHighlighter CssClass="source block-content" id="code_770200">
$application->setGlobalState('Caption',$caption);
$caption = $application->getGlobalState('Caption');
</com:TTextHighlighter>
<h2 id="6005">Session State</h2>
-<p>
+<p id="770614" class="block-content">
PRADO encapsulates the traditional session management in <tt>THttpSession</tt> module. The module can be accessed from within any component by using <tt>$this->Session</tt>, where <tt>$this</tt> refers to the component object.
</p>
diff --git a/demos/quickstart/protected/pages/Advanced/Themes.page b/demos/quickstart/protected/pages/Advanced/Themes.page index 07435928..876078b7 100644 --- a/demos/quickstart/protected/pages/Advanced/Themes.page +++ b/demos/quickstart/protected/pages/Advanced/Themes.page @@ -3,40 +3,40 @@ <h1 id="5901">Themes and Skins</h1>
<h2 id="5902">Introduction</h2>
-<p>
+<p id="760596" class="block-content">
Themes in PRADO provide a way for developers to provide a consistent look-and-feel across an entire web application. A theme contains a list of initial values for properties of various control types. When applying a theme to a page, all controls on that page will receive the corresponding initial property values from the theme. This allows themes to interact with the rich property sets of the various PRADO controls, meaning that themes can be used to specify a large range of presentational properties that other theming methods (e.g. CSS) cannot. For example, themes could be used to specify the default page size of all data grids across an application by specifying a default value for the <tt>PageSize</tt> property of the <tt>TDataGrid</tt> control.
</p>
<h2 id="5903">Understanding Themes</h2>
-<p>
+<p id="760597" class="block-content">
A theme is a directory consists of skin files, javascript files and CSS files. Any javascript or CSS files contained in a theme will be registered with the page that the theme is applied to. A skin is a set of initial property values for a particular control type. A control type may have one or several skins, each identified by a unique <tt>SkinID</tt>. When applying a theme to a page, a skin is applied to a control if the control type and the <tt>SkinID</tt> value both match to those of the skin. Note, if a skin has an empty <tt>SkinID</tt> value, it will apply to all controls of the particular type whose <tt>SkinID</tt> is not set or empty. A skin file consists of one or several skins, for one or several control types. A theme is the union of skins defined in all skin files.
</p>
<h2 id="5904">Using Themes</h2>
-<p>
+<p id="760598" class="block-content">
To use a theme, you need to set the <tt>Theme</tt> property of the page with the theme name, which is the theme directory name. You may set it in either <a href="?page=Configurations.PageConfig">page configurations</a> or in the constructor or <tt>onPreInit()</tt> method of the page. You cannot set the property after <tt>onPreInit()</tt> because by that time, child controls of the page are already created (skins must be applied to controls right after they are created.)
</p>
-<p>
+<p id="760599" class="block-content">
To use a particular skin in the theme for a control, set <tt>SkinID</tt> property of the control in template like following,
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_760194">
<com:TButton SkinID="Blue" ... />
</com:TTextHighlighter>
-<p>
+<p id="760600" class="block-content">
This will apply the 'Blue' skin to the button. Note, the initial property values specified by the 'Blue' skin will overwrite any existing property values of the button. Use stylesheet theme if you do not want them to be overwritten. To use stylesheet theme, set the <tt>StyleSheetTheme</tt> property of the page instead of <tt>Theme</tt> (you can have both <tt>StyleSheetTheme</tt> and <tt>Theme</tt>).
</p>
-<p>
+<p id="760601" class="block-content">
To use the Javascript files and CSS files contained in a theme, a <tt>THead</tt> control must be placed on the page template. This is because the theme will register those files with the page and <tt>THead</tt> is the right place to load those files.
</p>
-<p>
+<p id="760602" class="block-content">
It is possible to specify media types of CSS files contained in a theme. By default, a CSS file applies to all media types. If the CSS file is named like <tt>mystyle.print.css</tt>, it will be applied only to <tt>print</tt> media type. As another example, <tt>mystyle.screen.css</tt> applies to <tt>screen</tt> media only, and <tt>mystyle.css</tt> applies to all media types.
</p>
<h2 id="5905">Theme Storage</h2>
-<p>
+<p id="760603" class="block-content">
All themes by default must be placed under the <tt>[AppEntryPath]/themes</tt> directory, where <tt>AppEntryPath</tt> refers to the directory containing the application entry script. If you want to use a different directory, configure the <tt>BasePath</tt> and <tt>BaseUrl</tt> properties of the <tt>System.Web.UI.TThemeManager</tt> module in application configuration,
</p>
-<com:TTextHighlighter Language="xml" CssClass="source">
+<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_760195">
<service id="page" class="TPageService">
<modules>
<module id="theme"
@@ -48,13 +48,13 @@ All themes by default must be placed under the <tt>[AppEntryPath]/themes</tt> di </com:TTextHighlighter>
<h2 id="5906">Creating Themes</h2>
-<p>
+<p id="760604" class="block-content">
Creating a theme involves creating the theme directory and writing skin files (and possibly Javascript and CSS files). The name of skin files must be terminated with <tt>.skin</tt>. The format of skin files are the same as that of control template files. Since skin files do not define parent-child presentational relationship among controls, you cannot place a component tag within another. And any static texts between component tags are discarded. To define the aforementioned 'Blue' skin for <tt>TButton</tt>, write the following in a skin file,
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_760196">
<com:TButton SkinID="Blue" BackColor="blue" />
</com:TTextHighlighter>
-<p>
+<p id="760605" class="block-content">
As aforementioned, you can put several skins within a single skin file, or split them into several files. A commonly used strategy is that each skin file only contains skins for one type of controls. For example, <tt>Button.skin</tt> would contain skins only for the <tt>TButton</tt> control type.
</p>
</com:TContent>
\ No newline at end of file |