diff options
10 files changed, 219 insertions, 7 deletions
diff --git a/.gitattributes b/.gitattributes index 4910bc88..799488e9 100644 --- a/.gitattributes +++ b/.gitattributes @@ -108,6 +108,13 @@ demos/quickstart/protected/pages/Controls/List.page -text demos/quickstart/protected/pages/Controls/NewControl.page -text demos/quickstart/protected/pages/Controls/Overview.page -text demos/quickstart/protected/pages/Controls/Repeater.page -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.page -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.php -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.php -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.tpl -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.page -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.php -text +demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/LabeledTextBox.php -text demos/quickstart/protected/pages/Controls/Samples/TBulletedList/Home.page -text demos/quickstart/protected/pages/Controls/Samples/TBulletedList/Home.php -text demos/quickstart/protected/pages/Controls/Samples/TBulletedList/bullet.gif -text diff --git a/demos/quickstart/protected/pages/Controls/NewControl.page b/demos/quickstart/protected/pages/Controls/NewControl.page index f4ded5a4..8e2a21cf 100644 --- a/demos/quickstart/protected/pages/Controls/NewControl.page +++ b/demos/quickstart/protected/pages/Controls/NewControl.page @@ -1,15 +1,101 @@ <com:TContent ID="body" >
<h1>Writing New Controls</h1>
+<p>
+Writing new controls is often desired by advanced programmers, because they want to reuse the code that they write for dealing with complex presentation and user interactions.
+</p>
+<p>
+In general, there are two ways of writing new controls: composition of existing controls and extending existing controls. They all require that the new control inherit from <tt>TControl</tt> or its child classes.
+</p>
<h2>Composition of Existing Controls</h2>
+<p>
+Composition is the easiest way of creating new controls. It mainly involves instantiating existing controls, configuring them and making them the constituent components. The properties of the constituent components are exposed through <a href="?page=Fundamentals.Components">subproperties</a>.
+</p>
+<p>
+One can compose a new control in two ways. One is to override the <tt>TControl::createChildControls()</tt> method. The other is to extend <tt>TTemplateControl</tt> (or its child classes) and write a control template. The latter is easier to use and can organize the layout constituent compoents more intuitively, while the former is more efficient because it does not require parsing of the template.
+</p>
+<p>
+As an example, we show how to create a labeled textbox called <tt>LabeledTextBox</tt> using the above two approaches. A labeled textbox displays a label besides a textbox. We want reuse the PRADO provided <tt>TLabel</tt> and <tt>TTextBox</tt> to accomplish this task.
+</p>
-<h3></h3>
+<h3>Composition by Writing Templates</h3>
+<p>
+We need two files: a control class file named <tt>LabeledTextBox.php</tt> and a control template file named <tt>LabeledTextBox.tpl</tt>. Both must reside under the same directory.
+</p>
+<p>
+Like creating a PRADO page, we can easily write down the content in the control template file.
+</p>
+<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TLabel ID="Label" ForControl="TextBox" />
+<com:TTextBox ID="TextBox" />
+</com:TTextHighlighter>
+<p>
+The above template specifies a <tt>TLabel</tt> control named <tt>Label</tt> and a <tt>TTextBox</tt> control named <tt>TextBox</tt>. We would to expose these two controls. This can be done by defining a property for each control in the <tt>LabeledTextBox</tt> class file. For example, we can define a <tt>Label</tt> property as follows,
+</p>
+<com:TTextHighlighter CssClass="source">
+class LabeledTextBox extends TTemplateControl {
+ public function getLabel() {
+ $this->ensureChildControls();
+ return $this->getRegisteredObject('Label');
+ }
+}
+</com:TTextHighlighter>
+<p>
+In the above, the method call to <tt>ensureChildControls()</tt> ensures that both the label and the textbox controls are created (from template) when the <tt>Label</tt> property is accessed. The <tt>TextBox</tt> property can be implemented similarly.
+</p>
+<com:RunBar PagePath="Controls.Samples.LabeledTextBox1.Home" />
+
+<h3>Composition by Overriding <tt>createChildControls()</tt></h3>
+<p>
+For a composite control as simple as <tt>LabeledTextBox</tt>, it is better to create it by extending <tt>TControl</tt> and overriding the <tt>createChildControls()</tt> method, because it does not use templates and thus saves template parsing time.
+</p>
+<p>
+Complete code for <tt>LabeledTextBox</tt> is shown as follows,
+</p>
+<com:TTextHighlighter CssClass="source">
+class LabeledTextBox extends TControl {
+ private $_label;
+ private $_textbox;
+ protected function createChildControls() {
+ $this->_label=new TLabel;
+ $this->_label->setID('Label');
+ // add the label as a child of LabeledTextBox
+ $this->getControls()->add($label);
+ $this->_textbox=new TTextBox;
+ $this->_textbox->setID('TextBox');
+ // add the textbox as a child of LabeledTextBox
+ $this->getControls()->add($textbox);
+ }
+ public function getLabel() {
+ $this->ensureChildControls();
+ return $this->_label;
+ }
+ public function getTextBox() {
+ $this->ensureChildControls();
+ return $this->_textbox;
+ }
+}
+</com:TTextHighlighter>
+<com:RunBar PagePath="Controls.Samples.LabeledTextBox2.Home" />
+
+<h3>Using <tt>LabeledTextBox</tt></h3>
+<p>
+To use <tt>LabeledTextBox</tt> control, first we need to include the corresponding class file. Then in a page template, we can write lines like the following,
+</p>
+<com:TTextHighlighter Language="prado" CssClass="source">
+<com:LabeledTextBox ID="Input" Label.Text="Username" />
+</com:TTextHighlighter>
+<p>
+In the above, <tt>Label.Text</tt> is a subproperty of <tt>LabeledTextBox</tt>, which refers to the <tt>Text</tt> property of the <tt>Label</tt> property. For other details of using <tt>LabeledTextBox</tt>, see the above online examples.
+</p>
<h2>Extending Existing Controls</h2>
<h3>Extending <tt>TControl</tt></h3>
<h3>Extending <tt>TWebControl</tt></h3>
-
+PostBackHandler
+PostBackEvnetHandler
+DataBoundControl
</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.page b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.page new file mode 100644 index 00000000..ed05bfdf --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.page @@ -0,0 +1,11 @@ +<com:TContent ID="body" >
+<com:LabeledTextBox
+ ID="Input"
+ Label.Text="Username" />
+<com:TButton
+ Text="Submit"
+ OnClick="buttonClicked" />
+<com:TRequiredFieldValidator
+ ControlToValidate="Input.TextBox"
+ ErrorMessage="You must enter a value"/>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.php b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.php new file mode 100644 index 00000000..2b18972d --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/Home.php @@ -0,0 +1,13 @@ +<?php
+
+Prado::using('Application.pages.Controls.Samples.LabeledTextBox2.LabeledTextBox');
+
+class Home extends TPage
+{
+ public function buttonClicked($sender,$param)
+ {
+ $sender->Text=$this->Input->TextBox->Text;
+ }
+}
+
+?>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.php b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.php new file mode 100644 index 00000000..999639d7 --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.php @@ -0,0 +1,18 @@ +<?php
+
+class LabeledTextBox extends TTemplateControl
+{
+ public function getLabel()
+ {
+ $this->ensureChildControls();
+ return $this->getRegisteredObject('Label');
+ }
+
+ public function getTextBox()
+ {
+ $this->ensureChildControls();
+ return $this->getRegisteredObject('TextBox');
+ }
+}
+
+?>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.tpl b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.tpl new file mode 100644 index 00000000..8b3c1406 --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox1/LabeledTextBox.tpl @@ -0,0 +1,2 @@ +<com:TLabel ID="Label" ForControl="TextBox" />
+<com:TTextBox ID="TextBox" />
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.page b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.page new file mode 100644 index 00000000..ed05bfdf --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.page @@ -0,0 +1,11 @@ +<com:TContent ID="body" >
+<com:LabeledTextBox
+ ID="Input"
+ Label.Text="Username" />
+<com:TButton
+ Text="Submit"
+ OnClick="buttonClicked" />
+<com:TRequiredFieldValidator
+ ControlToValidate="Input.TextBox"
+ ErrorMessage="You must enter a value"/>
+</com:TContent>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.php b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.php new file mode 100644 index 00000000..2309bd88 --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/Home.php @@ -0,0 +1,13 @@ +<?php
+
+Prado::using('Application.pages.Controls.Samples.LabeledTextBox1.LabeledTextBox');
+
+class Home extends TPage
+{
+ public function buttonClicked($sender,$param)
+ {
+ $sender->Text=$this->Input->TextBox->Text;
+ }
+}
+
+?>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/LabeledTextBox.php b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/LabeledTextBox.php new file mode 100644 index 00000000..f4148148 --- /dev/null +++ b/demos/quickstart/protected/pages/Controls/Samples/LabeledTextBox2/LabeledTextBox.php @@ -0,0 +1,32 @@ +<?php
+
+class LabeledTextBox extends TControl
+{
+ private $_label;
+ private $_textbox;
+
+ protected function createChildControls()
+ {
+ $this->_label=new TLabel;
+ $this->_label->setID('Label');
+ $this->getControls()->add($this->_label);
+ $this->getControls()->add(' ');
+ $this->_textbox=new TTextBox;
+ $this->_textbox->setID('TextBox');
+ $this->getControls()->add($this->_textbox);
+ }
+
+ public function getLabel()
+ {
+ $this->ensureChildControls();
+ return $this->_label;
+ }
+
+ public function getTextBox()
+ {
+ $this->ensureChildControls();
+ return $this->_textbox;
+ }
+}
+
+?>
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page b/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page index 03d9afe8..0d031f9f 100644 --- a/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page +++ b/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page @@ -1,19 +1,38 @@ <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.
+PRADO is a component-based and event-driven programming framework for developing Web applications in PHP 5. 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.
+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.
</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.
+PRADO implements an event-driven programming paradigm that allows delegation of extensible behavior to components. End-user activities, such as clicking on a submit button, 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>
+
+<h2>Why PRADO?</h2>
<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.
+A primary goal of PRADO is to enable maximum reusability in Web programming. By reusability, we mean not only reusing one's own code, but also reusing other people's code in an easy way. The latter is more important as it saves the effort of reinventing the wheels and may cut off development time dramatically. The introduction of the concept of component is for this purpose.
+</p>
+<p>
+Reusing existing components is very easy. It merely involves getting and setting component properties, and sometimes responding to component events. PRADO provides a complete set of components that deal with common Web programming tasks, such as collecting and validating user inputs through generic HTML elements, manipulating tabular data, etc. These components can be rapidly glued together and form Web pages that are highly user interactive. For example, using the datagrid component, one only needs to write a few lines of PHP code (mainly to populate the data into the datagrid), and he can create a page presenting a data table which allows paging, sorting, editting, and deleting rows of data.
+</p>
+<p>
+Developing new components can also be very easy. A new component class can be created by composing together several existing components in a template which specifies the layout of the constituent components. The page that you are reading now is such an example. It is the presentation of a component without a single line of PHP code.
</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>
+
+<h2>What Is PRADO Best For?</h2>
+<p>
+PRADO is best suitable for creating Web front-ends that are highly user-interactive and require small to medium traffic. It can be used to develop systems as simple as a blog system to systems as complex as a content management system (CMS) or a complete e-commerce solution. PRADO can help you cut your development time significantly.
+</p>
+<p>
+PRADO does not exclude other back-end solutions such as most DB abstraction layers. In fact, they can be used like what you usually do with traditional PHP programming.
+</p>
+<p>
+Without server caching techniques, PRADO may not be suitable for developing extremely high-traffic Web applications, such as popular portals, forums, etc. In these applications, every niche of potential performance gain must be exploited and server caching (e.g. Zend optimizer) is almost a must.
+</p>
+
</com:TContent>
\ No newline at end of file |