1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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>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>
|
