diff options
| author | xue <> | 2005-12-26 15:54:54 +0000 |
|---|---|---|
| committer | xue <> | 2005-12-26 15:54:54 +0000 |
| commit | 9be8859d92e4bbec2462e82457d014f0a0d720db (patch) | |
| tree | 8d674a443ab0785d2a68dbfa326abfae3230bbb5 /demos/quickstart | |
| parent | a433c6c39bdaa5a53238596853617228be8ad07f (diff) | |
Diffstat (limited to 'demos/quickstart')
18 files changed, 552 insertions, 19 deletions
diff --git a/demos/quickstart/protected/pages/Configurations/AppConfig.page b/demos/quickstart/protected/pages/Configurations/AppConfig.page new file mode 100644 index 00000000..b6bf89f5 --- /dev/null +++ b/demos/quickstart/protected/pages/Configurations/AppConfig.page @@ -0,0 +1,40 @@ +<com:TContent ID="body" >
+
+<h1>Application Configurations</h1>
+<p>
+Application configurations are used to specify the global behavior of an application. This consists of specifying the paths, modules, services and parameters that will be used in an application.
+</p>
+<p>
+Application configurations are stored in an XML file which is passed as a parameter to the <code>TApplication</code> instance. The format of application configurations is shown in the following,
+<pre class="source">
+<application PropertyName="PropertyValue" ...>
+ <paths>
+ <alias id="AliasID" path="AliasPath" />
+ <using namespace="Namespace" />
+ </paths>
+ <modules>
+ <module id="ModuleID" class="ModuleClass" PropertyName="PropertyValue" ... />
+ </modules>
+ <services>
+ <service id="ServiceID" class="ServiceClass" PropertyName="PropertyValue" ... />
+ </services>
+ <parameters>
+ <parameter id="ParameterID" class="ParameterClass" PropertyName="PropertyValue" ... />
+ </parameters>
+</application>
+</pre>
+<ul>
+<li>The outermost element <code><application></code> corresponds to the <code>TApplication</code> instance. The <code>PropertyName="PropertyValue"</code> pairs specify the initial values for the properties of <code>TApplication</code>.</li>
+<li>The <code><paths></code> element contains the definition of path aliases and the PHP inclusion paths for the application. Each path alias is specified via an <code><alias></code> whose <code>path</code> attribute takes an absolute path or a path relative to the directory containing the application configuration file. The <code><using></code> element specifies a particular path (in terms of namespace) to be appended to the PHP include paths when the application runs. PRADO defines two default aliases: <code>System</code> and <code>Application</code>. The former refers to the PRADO framework root directory, and the latter refers to the directory containing the application configuration file.</li>
+<li>The <code><modules></code> element contains the configurations for a list of modules. Each module is specified by a <code><module></code> element. Each module is uniquely identified by the <code>id</code> attribute and is of type <code>class</code>. The <code>PropertyName="PropertyValue"</code> pairs specify the initial values for the properties of the module.</li>
+<li>The <code><services></code> element is similar to the <code><modules></code> element. It mainly specifies the services provided by the application.</li>
+<li>The <code><parameters></code> element contains a list of application-level parameters that are accessible from anywhere in the application. You may specify component-typed parameters like specifying modules, or you may specify string-typed parameters which take a simpler format as follows,
+<pre class="source">
+<parameter id="ParameterID">ParameterValue</parameter>
+</pre>
+</li>
+</ul>
+By default without explicit configuration, a PRADO application when running will load a few core modules, such as <code>THttpRequest</code>, <code>THttpResponse</code>, etc. It will also provide the <code>TPageService</code> as a default service. Configuration and usage of these modules and services are covered in individual sections of this tutorial. Note, if your application takes default settings for these modules and service, you do not need to provide an application configuration. However, if these modules or services are not sufficient, or you want to change their behavior by configuring their property values, you will need an application configuration.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Configurations/Overview.page b/demos/quickstart/protected/pages/Configurations/Overview.page new file mode 100644 index 00000000..4a23f306 --- /dev/null +++ b/demos/quickstart/protected/pages/Configurations/Overview.page @@ -0,0 +1,10 @@ +<com:TContent ID="body" >
+<h1>Configuration Overview</h1>
+<p>
+PRADO uses configurations to glue together components into pages and applications. There are <a href="?page=Configurations.AppConfig">application configurations</a>, <a href="?page=Configurations.PageConfig">page configurations</a>, and <a href="?page=Configurations.Templates1">templates</a>.
+</p>
+<p>
+Application and page configurations are optional if default values are used. Templates are mainly used by pages and template controls. They are optional, too.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Configurations/PageConfig.page b/demos/quickstart/protected/pages/Configurations/PageConfig.page new file mode 100644 index 00000000..7842e4f3 --- /dev/null +++ b/demos/quickstart/protected/pages/Configurations/PageConfig.page @@ -0,0 +1,36 @@ +<com:TContent ID="body" >
+
+<h1>Page Configurations</h1>
+<p>
+Page configurations are mainly used by <code>TPageService</code> to modify or append the application configuration. As the name indicates, a page configuration is associated with a directory storing some page files. It is stored as an XML file named <code>config.xml</code>.
+</p>
+<p>
+When a user requests a page stored under <code><BasePath>/dir1/dir2</code>, the <code>TPageService</code> will try to parse and load <code>config.xml</code> files under <code><BasePath>/dir1</code> and <code><BasePath>/dir1/dir2</code>. Paths, modules, and parameters specified in these configuration files will be appended or merged into the existing application configuration.
+</p>
+<p>
+The format of a page configuration file is as follows,
+<pre class="source">
+<configuration>
+ <paths>
+ <alias id="AliasID" path="AliasPath" />
+ <using namespace="Namespace" />
+ </paths>
+ <modules>
+ <module id="ModuleID" class="ModuleClass" PropertyName="PropertyValue" ... />
+ </modules>
+ <authorization>
+ <allow pages="PageID1,PageID2" users="User1,User2" roles="Role1,Role2" verb="post" />
+ <deny pages="PageID1,PageID2" users="User1,User2" roles="Role1,Role2" verb="post" />
+ </authorization>
+ <pages PropertyName="PropertyValue" ...>
+ <page id="PageID" PropertyName="PropertyValue" ... />
+ </pages>
+ <parameters>
+ <parameter id="ParameterID" class="ParameterClass" PropertyName="PropertyValue" ... />
+ </parameters>
+</configuration>
+</pre>
+The <code><paths></code>, <code><modules></code> and <code><parameters></code> are similar to those in an application configuration. The <code><authorization></code> specifies the authorization rules that apply to the current page directory and all its subdirectories. It will be explained in more detail in future sections. The <code><pages></code> element specifies the initial values for the properties of pages. Each <code><page></code> element specifies the initial property values for a particular page identified by the <code>id</code attribute. Initial property values given in the <code><pages></code> element apply to all pages in the current directory and all its subdirectories.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Configurations/Templates1.page b/demos/quickstart/protected/pages/Configurations/Templates1.page new file mode 100644 index 00000000..c406cfad --- /dev/null +++ b/demos/quickstart/protected/pages/Configurations/Templates1.page @@ -0,0 +1,69 @@ +<com:TContent ID="body" >
+<h1>Templates: Part I</h1>
+<p>
+Templates are used to specify the presentational layout of controls. A template can contain static text, components, or controls that contribute to the ultimate presentation of the associated control. By default, an instance of <code>TTemplateControl</code> or its subclass may automatically load a template from a file whose name is the same as the control class name. For page templates, the file name suffix must be <code>.page</code>; for other regular template controls, the suffix is <code>.tpl</code>.
+</p>
+<p>The template format is like HTML, with a few PRADO-specifc tags, including <a href="#ct">component tags</a>, <a href="#tct">template control tags</a>, <a href="#cot">comment tags</a>, <a href="?page=Configurations.Templates2#dct">dynamic content tags</a>, and <a href="?page=Configurations.Templates3#dpt">dynamic property tags</a>. .
+</p>
+
+<a name="ct" />
+<h2>Component Tags</h2>
+<p>
+A component tag specifies a component as part of the body content of the template control. If the component is a control, it usually will become a child or grand child of the template control, and its rendering result will be inserted at the place where it is appearing in the template.
+</p>
+<p>
+The format of a component tag is as follows,
+<pre class="source">
+<com:ComponentType PropertyName="PropertyValue" ... EventName="EventHandler" ...>
+body content
+</com:ComponentType>
+</pre>
+<code>ComponentType</code> can be either the class name or the dotted type name (e.g. <code>System.Web.UI.TControl</code>) of the component. <code>PropertyName</code> and <code>EventName</code> are both case-insensitive. <code>PropertyName</code> can be a property or subproperty name (e.g. <code>Font.Name</code>). Note, <code>PropertyValue</code> will be HTML-decoded when assigned to the corresponding property. Content enclosed between the opening and closing component tag are normally treated the body of the component.
+</p>
+<p>
+It is required that component tags nest properly with each other and an opening component tag be paired with a closing tag, similar to that in XML. The following shows a component tag specifying the <code>Text</code> property and <code>Click</code> event of a button control,
+<pre class="source">
+<com:TButton Text="Register" Click="registerUser" />
+</pre>
+</p>
+<p>
+To deal conveniently with properties taking take big trunk of initial data, the following property initialization tag is introduced,
+<pre class="source">
+<prop:PropertyName>
+PropertyValue
+</prop:PropertyName>
+</pre>
+It is equivalent to <code>...PropertyName="PropertyValue"...</code> in a component tag. Property initialization tags must be directly enclosed between the corresponding opening and closing component tag.
+</p>
+
+<a name="tct" />
+<h2>Template Control Tags</h2>
+A template control tag is used to configure the initial property values of the control owning the template. Its format is as follows,
+<pre class="source">
+<%@ PropertyName="PropertyValue" ... %>
+</pre>
+Like in component tags, <code>PropertyName</code> is case-insensitive and can be a property or subproperty name.
+</p>
+<p>
+Initial values specified via the template control tag are assigned to the corresponding properties when the template control is being constructed. Therefore, you may override these property values in a later stage, such as the <code>Init</code> stage of the control.
+</p>
+<p>
+Template control tag is optional in a template. Each template can contain at most one template control tag. You can place the template control tag anywhere in the template. It is recommended that you place it at the beginning of the template for better visibility.
+</p>
+
+<a name="cot" />
+<h2>Comment Tags</h2>
+<p>
+Comment tags are used to put comments in the template or the ultimate rendering result. There are two types of comment tags. One is like that in HTML and will be displayed to the end-users. The other only appear in a template and will be stripped out when the template is instantiated and displayed to the end-users. The format of these two comment tags is as follows,
+<pre class="source">
+<!--
+Comments VISIBLE to end-users
+-->
+
+<!
+Comments INVISIBLE to end-users
+!>
+</pre>
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Configurations/Templates2.page b/demos/quickstart/protected/pages/Configurations/Templates2.page new file mode 100644 index 00000000..b7eaaf7a --- /dev/null +++ b/demos/quickstart/protected/pages/Configurations/Templates2.page @@ -0,0 +1,78 @@ +<com:TContent ID="body" >
+<h1>Templates: Part II</h1>
+
+<a name="dct" />
+<h2>Dynamic Content Tags</h2>
+<p>
+Dynamic content tags are introduced as shortcuts to some commonly used <a href="?page=Configurations.Templates1#ct">component tags</a>. These tags are mainly used to render contents resulted from evaluating some PHP expressions or statements. They include <a href="#et">expression tags</a>, <a href="#st">statement tags</a>, <a href="#dt">databind tags</a>, <a href="#pt">parameter tags</a> and <a href="#at">asset tags</a>.
+</p>
+
+<a name="et" />
+<h3>Expression Tags</h3>
+<p>
+An expression tag represents a PHP expression that is evaluated when the template control is being rendered. The expression evaluation result is inserted at the place where the tag resides in the template. Its format is as follows,
+<pre class="source">
+<%= PhpExpression %>
+</pre>
+Inernally, an expression tag is represented by a <code>TExpression</code> control. Therefore, in the expression <code>$this</code> refers to the <code>TExpression</code> control. For example, the following expression tag will display the current page title at the place,
+<pre class="source">
+<%= $this->Page->Title %>
+</pre>
+</p>
+
+<a name="st" />
+<h3>Statement Tags</h3>
+<p>
+Statement tags are similar to expression tags, except that statement tags contain PHP statements rather than expressions. The output of the PHP statements (using for example <code>echo</code> or <code>print</code> in PHP) are displayed at the place where the statement tag resides in the template. Inernally, a statement tag is represented by a <code>TStatements</code> control. Therefore, in the statements <code>$this</code> refers to the <code>TStatements</code> control. The format of statement tags is as follows,
+<pre class="source">
+<%%
+PHP Statements
+%>
+</pre>
+</p>
+<p>
+The following example displays the current time in Dutch at the place,
+<pre class="source">
+<%%
+setlocale(LC_ALL, 'nl_NL');
+echo strftime("%A %e %B %Y",time());
+%>
+</pre>
+</p>
+
+<a name="dt" />
+<h3>Databind Tags</h3>
+<p>
+Databind tags are similar to expression tags, except that the expressions are evaluated only when a <code>dataBind()</code> call is invoked on the controls representing the databind tags. Internally, a <code>TLiteral</code> control is used to represent a databind tag and <code>$this</code> in the expression would refer to the control. The format of databind tags is as follows,
+<pre class="source">
+<%# PhpExpression %>
+</pre>
+</p>
+
+<a name="pt" />
+<h3>Parameter Tags</h3>
+<p>
+Parameter tags are used to insert application parameters at the place where they appear in the template. The format of parameter tags is as follows,
+<pre class="source">
+<%$ ParameterName %>
+</pre>
+Note, application parameters are usually defined in application configurations or page directory configurations. The parameters are evaluated when the template is instantiated.
+</p>
+
+<a name="at" />
+<h3>Asset Tags</h3>
+<p>
+Asset tags are used to publish private files and display the corresponding the URLs. For example, if you have an image file that is not Web-accessible and you want to make it visible to end-users, you can use asset tags to publish this file and show the URL to end-users so that they can fetch the published image.
+</p>
+<p>
+The format of asset tags is as follows,
+<pre class="source">
+<%~ LocalFileName %>
+</pre>
+where <code>LocalFileName</code> refers to a file path that is relative to the directory containing the current template file. The file path can be a single file or a directory. If the latter, the content in the whole directory will be made accessible by end-users.
+</p>
+<p>
+BE VERY CAUTIOUS when you are using asset tags as it may expose to end-users files that you probably do not want them to see.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Configurations/Templates3.page b/demos/quickstart/protected/pages/Configurations/Templates3.page new file mode 100644 index 00000000..328687fb --- /dev/null +++ b/demos/quickstart/protected/pages/Configurations/Templates3.page @@ -0,0 +1,73 @@ +<com:TContent ID="body" >
+<h1>Templates: Part III</h1>
+
+<a name="dpt" />
+<h2>Dynamic Property Tags</h2>
+<p>
+Dynamic property tags are very similar to dynamic content tags, except that they are applied to component properties. The purpose of dynamic property tags is to allow more versatile component property configuration. Note, you are not required to use dynamic property tags because what can be done using dynamic property tags can also be done in PHP code. However, using dynamic property tags bring you much more convenience at accomplishing the same tasks. The basic usage of dynamic property tags is as follows,
+<pre class="source">
+<com:ComponentType PropertyName=DynamicPropertyTag ...>
+body content
+</com:ComponentType>
+</pre>
+where you may enclose <code>DynamicPropertyTag</code> within single or double quotes for better readability.
+</p>
+<p>
+We now introduce the available types of dynamic property tags that may be used in the above. Like dynamic content tags, we have <a href="#et">expression tags</a>, <a href="#dt">databind tags</a>, <a href="#pt">parameter tags</a> and <a href="#at">asset tags</a>. (Note, there is no statement tag here.)
+</p>
+
+<a name="et" />
+<h3>Expression Tags</h3>
+<p>
+An expression tag represents a PHP expression that is evaluated when the template is being instantiated. The expression evaluation result is assigned to the corresponding component property. The format of expression tags is as follows,
+<pre class="source">
+<%= PhpExpression %>
+</pre>
+In the expression, <code>$this</code> refers to the component specified by the component tag. The following example specifies a <code>TLabel</code> control whose <code>Text</code> property is initialized as the current page title when the <code>TLabel</code> control is being constructed,
+<pre class="source">
+<com:TLabel Text=<%= $this->Page->Title %> />
+</pre>
+</p>
+<p>
+Note, unlike dynamic content tags, the expressions tags for component properties are evaluated when the components are being constructed, while for the dynamic content tags, the expressions are evaluated when the controls are being rendered.
+</p>
+
+<a name="dt" />
+<h3>Databind Tags</h3>
+<p>
+Databind tags are similar to expression tags, except that the expressions are evaluated only when a <code>dataBind()</code> call is invoked on the controls represented by the component tags. In the expression, <code>$this</code> refers to the control itself. Databind tags do not apply to all components. They can only be used for controls.
+</p>
+<p>
+The format of databind tags is as follows,
+<pre class="source">
+<%# PhpExpression %>
+</pre>
+</p>
+
+<a name="pt" />
+<h3>Parameter Tags</h3>
+<p>
+Parameter tags are used to assign application parameter values to the corresponding component properties. The format of parameter tags is as follows,
+<pre class="source">
+<%$ ParameterName %>
+</pre>
+Note, application parameters are usually defined in application configurations or page directory configurations. The parameters are evaluated when the template is instantiated.
+</p>
+
+<a name="at" />
+<h3>Asset Tags</h3>
+<p>
+Asset tags are used to publish private files and assign the corresponding the URLs to the component properties. For example, if you have an image file that is not Web-accessible and you want to make it visible to end-users, you can use asset tags to publish this file and show the URL to end-users so that they can fetch the published image.
+</p>
+<p>
+The format of asset tags is as follows,
+<pre class="source">
+<%~ LocalFileName %>
+</pre>
+where <code>LocalFileName</code> refers to a file path that is relative to the directory containing the current template file. The file path can be a single file or a directory. If the latter, the content in the whole directory will be made accessible by end-users.
+</p>
+<p>
+BE VERY CAUTIOUS when you are using asset tags as it may expose to end-users files that you probably do not want them to see.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Overview.page b/demos/quickstart/protected/pages/Controls/Overview.page new file mode 100644 index 00000000..7c3fbea6 --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Overview.page @@ -0,0 +1,15 @@ +<com:TContent ID="body" >
+<h1>Controls Overview</h1>
+<p>
+A control is an instance of class <code>TControl</code> or its subclass. A control is a component defined in addition with user interface. The base class <code>TControl</code> defines the parent-child relationship among controls which reflects the containment relationship among user interface elements.
+</p>
+<p>
+Control classes constitute one of the major part of PRADO framework. Nearly every generic HTML element can find its representation in terms of a PRADO control. Mastering these controls becomes extremely important to effectively and efficiently compose applications using PRADO.
+</p>
+<p>
+In this section, we will first introduce the ...., then....
+</p>
+<p>
+To be continued...
+</p>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Simple1.page b/demos/quickstart/protected/pages/Controls/Simple1.page new file mode 100644 index 00000000..a608c8d2 --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Simple1.page @@ -0,0 +1,2 @@ +<com:TContent ID="body" >
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Fundamentals/Components.page b/demos/quickstart/protected/pages/Fundamentals/Components.page new file mode 100644 index 00000000..ec6dbd48 --- /dev/null +++ b/demos/quickstart/protected/pages/Fundamentals/Components.page @@ -0,0 +1,49 @@ +<com:TContent ID="body" >
+<h1>Components</h1>
+<p>
+A component is an instance of <code>TComponent</code> or its child class. The base class <code>TComponent</code> implements the mechanism of component properties and events.
+</p>
+
+<h2>Component Properties</h2>
+<p>
+A component property can be viewed as a public variable describing a specific aspect of the component, such as the background color, the font size, etc. A property is defined by the existence of a getter and/or a setter method in the component class. For example, in <code>TControl</code>, we have
+<pre class="source">
+class TControl extends TComponent {
+ public function getID() {
+ ...
+ }
+ public function setID($value) {
+ ...
+ }
+}
+</pre>
+This defines a property named <code>ID</code>. Reading the property (e.g. <code>echo $component->ID;</code>) is equivalent to invoking the getter method (e.g. <code>echo $component->getID();</code>); and writing the property (e.g. <code>$component->ID='Button';</code>) is equivalent to invoking the setter method (e.g. <code>$component->setID('Button');</code>).
+</p>
+<p>
+A property is read-only if it has a getter method but no setter method. Since PHP method names are case-insensitive, property names are also case-insensitive. A component class inherits all its ancestor classes' properties.
+</p>
+
+<h2>Component Events</h2>
+<p>
+Component events are special properties that take method names as their values. Attaching (setting) a method to an event will hook up the method to the places at which the event is raised. Therefore, the behavior of a component can be modified in a way that may not be foreseen during the development of the component.
+</p>
+<p>
+A component event is defined by the existence of an <code>on</code>-method. For example, in <code>TButton</code>, we have
+<pre class="source">
+class TButton extends TWebControl {
+ public function onClick($param) {
+ ...
+ }
+}
+</pre>
+This defines an event named <code>Click</code>, and a handler can be attached to the event using one of the following ways,
+<pre class="source">
+$button->Click=$callback;
+$button->Click->add($callback);
+$button->Click[]=$callback;
+$button->attachEventHandler('Click',$callback);
+</pre>
+where <code>$callback</code> refers to a valid PHP callback (e.g. a function name, a class method <code>array($object,'method')</code>, etc.)
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Fundamentals/Controls.page b/demos/quickstart/protected/pages/Fundamentals/Controls.page new file mode 100644 index 00000000..7703003d --- /dev/null +++ b/demos/quickstart/protected/pages/Fundamentals/Controls.page @@ -0,0 +1,19 @@ +<com:TContent ID="body" >
+<h1>Controls</h1>
+<p>
+A control is an instance of class <code>TControl</code> or its subclass. A control is a component defined in addition with user interface. The base class <code>TControl</code> defines the parent-child relationship among controls which reflects the containment relationship among user interface elements.
+</p>
+
+<h3>Parent-Child Relationship</h3>
+<p>
+A parent control is in charge of the state transition of its child controls. The rendering result of the child controls are usually used to compose the parent control's presentation.
+</p>
+<p>
+The parent-child relationship is usually established by the framework via <a href="?page=Configurations.Templates1">templates</a>. In code, you may explicitly specify a control as a child of another using the following method,
+<pre class="source">
+$parent->Controls->add($child);
+</pre>
+where the property <code>Controls</code> refers to the child control collection of the parent.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Fundamentals/Pages.page b/demos/quickstart/protected/pages/Fundamentals/Pages.page new file mode 100644 index 00000000..71434ae1 --- /dev/null +++ b/demos/quickstart/protected/pages/Fundamentals/Pages.page @@ -0,0 +1,8 @@ +<com:TContent ID="body" >
+
+<h1>Pages</h1>
+<p>
+Pages are top-most controls that have no parent (you may consider application as their container though). The presentation of pages are directly displayed to end-users.
+</p>
+
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page b/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page new file mode 100644 index 00000000..03d9afe8 --- /dev/null +++ b/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page @@ -0,0 +1,19 @@ +<com:TContent ID="body" >
+<h1>What is PRADO?</h1>
+<p>
+PRADO stands for <b>P</b>HP <b>R</b>apid <b>A</b>pplication <b>D</b>evelopment
+<b>O</b>bject-oriented.
+</p>
+<p>
+PRADO is a component-based and event-driven programming framework for developing Web applications in PHP 5.
+</p>
+<p>
+PRADO stipulates a protocol of writing and using components to construct Web applications. A component is a software unit that is self-contained and can be reused with trivial customization. New components can be developed by either inheriting or composing from existing ones. Component-based programming brings great freedom in teamwork anf offers the ultimate extensibility and maintenability to the code. PRADO implements a set of elementary components that represent commonly used Web elements, such as input field, checkbox, dropdown list, etc.
+</p>
+<p>
+PRADO implements an event-driven programming scheme that allows delegation of extensible behavior to components. End-user activities, such as clicking on a submit button, changing the content in an input field, are captured as server events. Methods or functions may be attached to these events so that when the events happen, they are invoked automatically to respond to the events. Compared with the traditional Web programming in which developers have to deal with the raw POST or GET variables, event-driven programming helps developers better focus on the necessary logic and reduces significantly the low-level repetitive coding.
+</p>
+<p>
+Developing a PRADO Web application mainly involves instantiating prebuilt component types, configuring them by setting their properties, responding to their events by writing handler functions, and composing them into pages for the application. It is very similar to RAD toolkits, such as Borland Delphi and Microsoft Visual Basic, that are used to develop desktop GUI applications.
+</p>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/GettingStarted/Installation.page b/demos/quickstart/protected/pages/GettingStarted/Installation.page new file mode 100644 index 00000000..619d613f --- /dev/null +++ b/demos/quickstart/protected/pages/GettingStarted/Installation.page @@ -0,0 +1,21 @@ +<com:TContent ID="body" >
+<h1>Installing PRADO</h1>
+<p>
+If you are viewing this page from your own Web server, you are already done with the installation. The instructions at the end of this page, however, may still be useful for you to troubleshoot issues happened during your development based on PRADO.
+</p>
+<p>
+Installation of PRADO is very easy. Follow the following steps,
+<ol>
+<li>Go to <a href="http://www.pradosoft.com/">pradosoft.com</a> to grab a latest version of PRADO.</li>
+<li>Unpack the PRADO release file using <i>unzip</i> on Linux or <i>winzip</i> on Windows. A directory named <i>prado</i> will be created under the working directory.</li>
+<li>Copy or upload everything under the <i>prado</i> directory to the DocumentRoot directory (or a subdirectory) of the Web server.</li>
+<li>Your installation of PRADO is done and you can start to play with the demo applications included in the PRADO release via URL <i>http://web-server-address/demos/</i>. This QuickStart Tutorial is one of such applications.</li>
+</ol>
+</p>
+<p>
+If you encounter any problems with the demo applications, please use the PRADO requirement checker script to check if your server configuration fullfils the conditions required by PRADO.
+</p>
+<p>
+The minimum requirement by PRADO is that the Web server support PHP 5. PRADO has been tested with Apache Web server on Windows and Linux. Highly possibly it may also run on other platforms with other Web servers, as long as PHP 5 is supported.
+</p>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/GettingStarted/Introduction.page b/demos/quickstart/protected/pages/GettingStarted/Introduction.page new file mode 100644 index 00000000..dc7a0497 --- /dev/null +++ b/demos/quickstart/protected/pages/GettingStarted/Introduction.page @@ -0,0 +1,6 @@ +<com:TContent ID="body" >
+<h1>Welcome to the PRADO QuickStart Tutorial</h1>
+<p>
+This QuickStart tutorial is meant to get you quickly started to build your own Web applications based on PRADO.
+</p>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Samples/Hangman.page b/demos/quickstart/protected/pages/Samples/Hangman.page new file mode 100644 index 00000000..4541c8f9 --- /dev/null +++ b/demos/quickstart/protected/pages/Samples/Hangman.page @@ -0,0 +1,16 @@ +<com:TContent ID="body" >
+<h1>Sample: Hangman Game</h1>
+<p>
+Having seen the simple "Hello World" application, we now build a more complex application called "Hangman Game". In this game, the player is asked to guess a word, a letter at a time. If he guesses a letter right, the letter will be shown in the word. The player can continue to guess as long as the number of his misses is within a prespecified bound. The player wins the game if he finds out the word within the miss bound, or he loses.
+</p>
+<p>
+To facilitate the building of this game, we show the state transition diagram of the gaming process in the following,
+</p>
+<p>
+To be continued...
+</p>
+<div class="runbar">
+<a href="?page=Samples.Hangman.Home" target="_blank">Run Sample</a>
+<a href="?page=ViewSource&path=/Samples/Hangman/Home.php" target="_blank">View Source</a>
+</div>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Samples/HelloWorld.page b/demos/quickstart/protected/pages/Samples/HelloWorld.page new file mode 100644 index 00000000..98d29265 --- /dev/null +++ b/demos/quickstart/protected/pages/Samples/HelloWorld.page @@ -0,0 +1,26 @@ +<com:TContent ID="body" >
+<h1>Sample: Hello World</h1>
+<p>
+"Hello World" is the simplest <i>interactive</i> PRADO application that you can build. It displays to end-users a page with a submit button whose caption is <i>Click Me</i>. When the user clicks on the button, the button changes the caption to <i>Hello World</i>.
+</p>
+<p>
+There are many approaches that can achieve the above goal. One can submit the page to the server, examine the POST variable, and generate a new page with the button caption updated. Or one can simply use JavaScript to update the button caption upon its <i>onclick</i> event.
+</p>
+<p>
+PRADO promotes component-based and event-driven Web programming. The button is represented by a <i>TButton</i> object. It encapsulates the button caption as the <i>Text</i> property and associates the user button click action with a server-side <i>Click</i> event. Therefore, the "Hello World" task can be handled intuitively and easily. One simply needs to attach a function to the button's <i>Click</i> event. Within the function, the button's <i>Text</i> property is modified as "Hello World". The following diagram shows the above sequence,
+</p>
+<img src="<%~HelloWorld/sequence.gif%>" />
+<p>
+The code that a developer needs to write is merely the following event handler function, where <code>$sender</code> refers to the button object.
+</p>
+<pre class="source">
+public function buttonClicked($sender,$param)
+{
+ $sender->Text="Hello World";
+}
+</pre>
+<div class="runbar">
+<a href="?page=Samples.HelloWorld.Home" target="_blank">Run Sample</a>
+<a href="?page=ViewSource&path=/Samples/HelloWorld/Home.php" target="_blank">View Source</a>
+</div>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/TopicList.tpl b/demos/quickstart/protected/pages/TopicList.tpl index 0cfcb827..ac34b034 100644 --- a/demos/quickstart/protected/pages/TopicList.tpl +++ b/demos/quickstart/protected/pages/TopicList.tpl @@ -2,33 +2,43 @@ <div class="topic">
<span>Getting Started</span><br/>
-<a href="?page=chap1.Introduction">Introduction</a><br/>
-<a href="?page=chap1.AboutPrado">What is PRADO?</a><br/>
-<a href="?page=chap1.Installation">Installation</a><br/>
+<a href="?page=GettingStarted.Introduction">Introduction</a><br/>
+<a href="?page=GettingStarted.AboutPrado">What is PRADO?</a><br/>
+<a href="?page=GettingStarted.Installation">Installation</a><br/>
</div>
<div class="topic">
<span>Fundamentals</span><br/>
-<a href="?page=chap2.Architecture">Architecture</a><br/>
-<a href="?page=chap2.KeyConcepts">Key Concepts</a><br/>
-<a href="?page=chap2.Structure">Application Structure</a><br/>
-<a href="?page=chap2.Configurations">Configurations</a><br/>
-<a href="?page=chap2.Templates1">Templates: Part I</a><br/>
-<a href="?page=chap2.Templates2">Templates: Part II</a><br/>
-<a href="?page=chap2.Templates3">Templates: Part III</a><br/>
+<a href="?page=Fundamentals.Architecture">Architecture</a><br/>
+<a href="?page=Fundamentals.Components">Components</a><br/>
+<a href="?page=Fundamentals.Controls">Controls</a><br/>
+<a href="?page=Fundamentals.Pages">Pages</a><br/>
+<a href="?page=Fundamentals.Modules">Modules</a><br/>
+<a href="?page=Fundamentals.Services">Services</a><br/>
+<a href="?page=Fundamentals.Applications">Applications</a><br/>
+</div>
+
+<div class="topic">
+<span>Configurations</span><br/>
+<a href="?page=Configurations.Overview">Overview</a><br/>
+<a href="?page=Configurations.Templates1">Templates: Part I</a><br/>
+<a href="?page=Configurations.Templates2">Templates: Part II</a><br/>
+<a href="?page=Configurations.Templates3">Templates: Part III</a><br/>
+<a href="?page=Configurations.AppConfig">Application Configurations</a><br/>
+<a href="?page=Configurations.PageConfig">Page Configurations</a><br/>
</div>
<div class="topic">
<span>Samples</span><br/>
-<a href="?page=chap3.HelloWorld">Hello World</a><br/>
-<a href="?page=chap3.Hangman">Hangman Game</a><br/>
+<a href="?page=Samples.HelloWorld">Hello World</a><br/>
+<a href="?page=Samples.Hangman">Hangman Game</a><br/>
</div>
<div class="topic">
<span>Controls</span><br/>
-<a href="?page=chap4.Overview">Overview</a><br/>
-<a href="?page=chap4.Simple1">Simple Controls: Part I</a><br/>
-<a href="?page=chap4.Simple2">Simple Controls: Part II</a><br/>
+<a href="?page=Controls.Overview">Overview</a><br/>
+<a href="?page=Controls.Simple1">Simple Controls: Part I</a><br/>
+<a href="?page=Construction">Simple Controls: Part II</a><br/>
<a href="?page=Construction">Validation Controls</a><br/>
<a href="?page=Construction">List Controls</a><br/>
<a href="?page=Construction">TRepeater</a><br/>
@@ -48,8 +58,8 @@ <div class="topic">
<span>Avanced Features</span><br/>
<a href="?page=Construction">Overview</a><br/>
-<a href="?page=Construction">Theme and Skin</a><br/>
-<a href="?page=Construction">Asset</a><br/>
+<a href="?page=Construction">Themes and Skins</a><br/>
+<a href="?page=Construction">Assets</a><br/>
<a href="?page=Construction">Internationalization</a><br/>
</div>
diff --git a/demos/quickstart/protected/pages/chap2/KeyConcepts.page b/demos/quickstart/protected/pages/chap2/KeyConcepts.page index 5352d1ff..701633c4 100644 --- a/demos/quickstart/protected/pages/chap2/KeyConcepts.page +++ b/demos/quickstart/protected/pages/chap2/KeyConcepts.page @@ -8,7 +8,7 @@ A component is an instance of <code>TComponent</code> or its child class. The ba <h3>Component Properties</h3>
<p>
-A property can be viewed as a public variable describing a specific aspect of the component, such as the background color, the font size, etc. A property is defined by the existence of a getter and/or a setter method of a component class. For example, in <code>TControl</code>, we have
+A component property can be viewed as a public variable describing a specific aspect of the component, such as the background color, the font size, etc. A property is defined by the existence of a getter and/or a setter method in the component class. For example, in <code>TControl</code>, we have
<pre class="source">
class TControl extends TComponent {
public function getID() {
@@ -22,16 +22,52 @@ class TControl extends TComponent { This defines a property named <code>ID</code>. Reading the property (e.g. <code>echo $component->ID;</code>) is equivalent to invoking the getter method (e.g. <code>echo $component->getID();</code>); and writing the property (e.g. <code>$component->ID='Button';</code>) is equivalent to invoking the setter method (e.g. <code>$component->setID('Button');</code>).
</p>
<p>
-A property is read-only if it only has a getter method and no setter method. Since PHP method names are case-insensitive, property names are also case-insensitive.
+A property is read-only if it has a getter method but no setter method. Since PHP method names are case-insensitive, property names are also case-insensitive. A component class inherits all its ancestor classes' properties.
</p>
<h3>Component Events</h3>
+<p>
+Component events are special properties that take method names as their values. Attaching (setting) a method to an event will hook up the method to the places at which the event is raised. Therefore, the behavior of a component can be modified in a way that may not be foreseen during the development of the component.
+</p>
+<p>
+A component event is defined by the existence of an <code>on</code>-method. For example, in <code>TButton</code>, we have
+<pre class="source">
+class TButton extends TWebControl {
+ public function onClick($param) {
+ ...
+ }
+}
+</pre>
+This defines an event named <code>Click</code>, and a handler can be attached to the event using one of the following ways,
+<pre class="source">
+$button->Click=$callback;
+$button->Click->add($callback);
+$button->Click[]=$callback;
+$button->attachEventHandler('Click',$callback);
+</pre>
+where <code>$callback</code> refers to a valid PHP callback (e.g. a function name, a class method <code>array($object,'method')</code>, etc.)
+</p>
<h2>Controls</h2>
<p>
A control is an instance of class <code>TControl</code> or its subclass. A control is a component defined in addition with user interface. The base class <code>TControl</code> defines the parent-child relationship among controls which reflects the containment relationship among user interface elements.
</p>
+<h3>Parent-Child Relationship</h3>
+<p>
+A parent control is in charge of the state transition of its child controls. The rendering result of the child controls are usually used to compose the parent control's presentation.
+</p>
+<p>
+The parent-child relationship is usually established by the framework via <a href="?page=chap2.Templates1">templates</a>. In code, you may explicitly specify a control as a child of another using the following method,
+<pre class="source">
+$parent->Controls->add($child);
+</pre>
+where the property <code>Controls</code> refers to the child control collection of the parent.
+</p>
+
<h2>Pages</h2>
+<p>
+Pages are top-most controls that have no parent (you may consider application as their container though). The presentation of pages are directly displayed to end-users.
+</p>
</com:TContent>
\ No newline at end of file |