+
TButton creates a click button on a Web page. The button's caption is specified by Text property. A button is used to submit data to a page. TButton raises two server-side events, OnClick and OnCommand, when it is clicked on the client-side. The difference between OnClick and OnCommand events is that the latter event is bubbled up to the button's ancestor controls. An OnCommand event handler can use CommandName and CommandParameter associated with the event to perform specific actions.
-+
Clicking on button can trigger form validation, if CausesValidation is true. And the validation may be restricted within a certain group of validator controls according to ValidationGroup.
+
TCheckBox displays a check box on a Web page. A caption can be specified via Text and displayed beside the check box. It can appear either on the right or left of the check box, which is determined by TextAlign. You may further specify attributes applied to the text by using LabelAttributes.
-+
To determine whether the check box is checked, test the Checked property. A CheckedChanged event is raised if the state of Checked is changed between posts to the server. If AutoPostBack is true, changing the check box state will cause postback action. And if CausesValidation is also true, upon postback validation will be performed for validators within the specified ValidationGroup.
+
TClientScript allows Javascript code to be insert or linked to the page template. PRADO is bundled with a large library of Javascript functionality including effects, AJAX, basic event handlers, and many others. The bundled @@ -12,13 +12,13 @@ Javascript libraries can be linked to the current page template using the can be specified using comma delimited string of the name of Javascript library to include on the page. For following example will include the "ajax" and "effects" library.
-- The available bundled libraries included in Prado are -
+ The available bundled libraries included in Prado are
+The dependencies for each library are automatically resolved. That is, +
The dependencies for each library are automatically resolved. That is, specifying, say the "ajax", will also include the "prado" library.
Custom Javascript files can be register using the ScriptUrl property. +
Custom Javascript files can be register using the ScriptUrl property. The following example includes the Javascript file "test.js" to the page. In this case, the file "test.js" is relative the current template you are using. Since the property value is dynamic asset tag, the file "test.js" will be published automatically, that is, the file will be copied to the assets directory if necessary.
-You can include Javascript files from other servers by specifying the full URL string in +
You can include Javascript files from other servers by specifying the full URL string in the ScriptUrl property.
Any content within the TClientScript control tag will be considered as +
Any content within the TClientScript control tag will be considered as Javascript code and will be rendered where it is declared.
\ No newline at end of file diff --git a/demos/quickstart/protected/pages/Controls/ColorPicker.page b/demos/quickstart/protected/pages/Controls/ColorPicker.page index 8909ad98..e0de6712 100644 --- a/demos/quickstart/protected/pages/Controls/ColorPicker.page +++ b/demos/quickstart/protected/pages/Controls/ColorPicker.page @@ -3,7 +3,7 @@+
TBD
diff --git a/demos/quickstart/protected/pages/Controls/Data.page b/demos/quickstart/protected/pages/Controls/Data.page index 6a93ec6f..aea25ab7 100644 --- a/demos/quickstart/protected/pages/Controls/Data.page +++ b/demos/quickstart/protected/pages/Controls/Data.page @@ -2,7 +2,7 @@+
TDatagrid is an important control in building complex Web applications. It displays data in a tabular format with rows (also called items) and columns. A row is composed by cells, while columns govern how cells should be displayed according to their association with the columns. Data specified via DataSource or DataSourceID are bound to the rows and feed contents to cells.
-+
TDataGrid is highly interactive. Users can sort the data along specified columns, navigate through different pages of the data, and perform actions, such as editing and deleting, on rows of the data.
-+
Rows of TDataGrid can be accessed via its Items property. A row (item) can be in one of several modes: browsing, editing and selecting, which affects how cells in the row are displayed. To change an item's mode, modify EditItemIndex or SelectedItemIndex. Note, if an item is in edit mode, then selecting this item will have no effect.
+
Columns of a data grid determine how the associated cells are displayed. For example, cells associated with a TBoundColumn are displayed differently according to their modes. A cell is displayed as a static text if the cell is in browsing mode, a text box if it is in editing mode, and so on.
-+
PRADO provides five types of columns:
-+
TDataGrid defines different styles applied to its items. For example, AlternatingItemStyle is applied to alternating items (item 2, 4, 6, etc.) Through these properties, one can set CSS style fields or CSS classes for the items.
-+
Item styles are applied in a hierarchical way. Styles in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, ItemStyle, AlternatingItemStyle, SelectedItemStyle, and EditItemStyle. Therefore, if background color is set as red in ItemStyle, EditItemStyle will also have red background color, unless it is explicitly set to a different value.
+
TDataGrid provides several events to facilitate manipulation of its items,
-+
TDataGrid by default will create a list of columns based on the structure of the bound data. TDataGrid will read the first row of the data, extract the field names of the row, and construct a column for each field. Each column is of type TBoundColumn.
-+
The following example displays a list of computer product information using a TDataGrid. Columns are automatically generated. Pay attention to how item styles are specified and inherited. The data are populated into the datagrid using the follow code, which is common among most datagrid applications,
-+
Using automatically generated columns gives a quick way of browsing tabular data. In real applications, however, automatically generated columns are often not sufficient because developers have no way customizing their appearance. Manually specified columns are thus more desirable.
-+
To manually specify columns, set AutoGenerateColumns to false, and specify the columns in a template like the following,
-+
Note, if AutoGenerateColumns is true and there are manually specified columns, the automatically generated columns will be appended to the manually specified columns. Also note, the datagrid's Columns property contains only manually specified columns and no automatically generated ones.
-+
The following example uses manually specified columns to show a list of book information,
-Pay attention to how item (row) styles and column styles cooperate together to affect the appearance of the cells in the datagrid.
+Pay attention to how item (row) styles and column styles cooperate together to affect the appearance of the cells in the datagrid.
+
Besides the rich data presentation functionalities as demonstrated in previous section, TDataGrid is also highly user interactive. An import usage of TDataGrid is editing or deleting rows of data. The TBoundColumn can adjust the associated cell presentation according to the mode of datagrid items. When an item is in browsing mode, the cell is displayed with a static text; when the item is in editing mode, a textbox is displayed to collect user inputs. TDataGrid provides TEditCommandColumn for switching item modes. In addition, TButtonColumn offers developers the flexibility of creating arbitrary buttons for various user interactions.
-+
The following example shows how to make the previous book information table an interactive one. It allows users to edit and delete book items from the table. Two additional columns are used in the example to allow users interact with the datagrid: TEditCommandColumn and TButtonColumn. In addition, TDropDownListColumn replaces the previous TTemplateColumn to allow users to select a rating from a dropdown list. Note, it is also possible to use TTemplateColumn to achieve the same task.
+
TDataGrid supports sorting its items according to specific columns. To enable sorting, set AllowSorting to true. This will turn column headers into clickable buttons if their SortExpression property is not empty. When users click on the header buttons, an OnSortCommand event will be raised. Developers can write handlers to respond to the sort command and sort the data according to SortExpression which is specified in the corresponding column.
-+
The following example turns the datagrid in Example 2 into a sortable one. Users can click on the link button displayed in the header of any column, and the data will be sorted in ascending order along that column.
+
When dealing with large datasets, paging is helpful in reducing the page size and complexity. TDataGrid has an embedded pager that allows users to specify which page of data they want to see. The pager can be customized via PagerStyle. For example, PagerStyle.Visible determines whether the pager is visible or not; PagerStyle.Position indicates where the pager is displayed; and PagerStyle.Mode specifies what type of pager is displayed, a numeric one or a next-prev one.
-+
To enable paging, set AllowPaging to true. The number of rows of data displayed in a page is specified by PageSize, while the index (zero-based) of the page currently showing to users is by CurrentPageIndex. When users click on a pager button, TDataGrid raises OnPageIndexChanged event. Typically, the event handler is written as follows,
-+
The following example enables the paging functionality of the datagrid shown in Example 1. In this example, you can set various pager styles interactively to see how they affect the pager display.
+
The paging functionality shown above requires loading all data into memory, even though only a portion of them is displayed in a page. For large datasets, this is inefficient and may not always be feasible. TDataGrid provides custom paging to solve this problem. Custom paging only requires the portion of the data to be displayed to end users.
-+
To enable custom paging, set both AllowPaging and AllowCustomPaging to true. Notify TDataGrid the total number of data items (rows) available by setting VirtualItemCount. And respond to the OnPageIndexChanged event. In the event handler, use the NewPageIndex property of the event parameter to fetch the new page of data from data source. For MySQL database, this can be done by using LIMIT clause in an SQL select statement.
+
Besides traditional class inheritance, extensibility of TDataGrid is mainly through developing new datagrid column components. For example, one may want to display an image column. He may use TTemplateColumn to accomplish this task. A better solution is to develop an image column component so that the work can be reused easily in other projects.
-+
All datagrid column components must inherit from TDataGridColumn. The main method that needs to be overridden is initializeCell() which creates content for cells in the corresponding column. Since each cell is also in an item (row) and the item can have different types (such as Header, AltneratingItem, etc.), different content may be created according to the item type. For the image column example, one may want to create a TImage control within cells residing in items of Item and AlterantingItem types.
-+
In initializeCell(), remember to call the parent implementation, as it initializes cells in items of Header and Footer types.
diff --git a/demos/quickstart/protected/pages/Controls/DataList.page b/demos/quickstart/protected/pages/Controls/DataList.page index 75541564..1630ed96 100644 --- a/demos/quickstart/protected/pages/Controls/DataList.page +++ b/demos/quickstart/protected/pages/Controls/DataList.page @@ -1,16 +1,16 @@+
TDataList is used to display or modify a list of data items specified by its DataSource or DataSourceID property. Each data item is displayed by a data list item which is a child control of the data list. The Items property contains the list of all data list items.
-+
TDataList displays its items in either a Table or Flow layout, which is specified by the RepeatLayout property. A table layout uses HTML table cells to organize the items while a flow layout uses line breaks to organize the items. When the layout is Table, the table's cellpadding and cellspacing can be adjusted by CellPadding and CellSpacing properties, respectively. And Caption and CaptionAlign can be used to add a table caption with the specified alignment. The number of columns used to display the data list items is specified via RepeatColumns property, while the RepeatDirection governs the order of the items being rendered.
-+
Each data list item is created according to one of the seven kinds of templates that developers may specified for a TDataList,
-+
Each of the above templates is associated with a style property that is applied to the items using the template. For example, ItemTemplate is associated with a property named AlternatingItemStyle. Through this property, one can set CSS style fields or CSS classes for the data list items.
-+
Item styles are applied in a hierarchical way. Style in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, ItemStyle, AlternatingItemStyle, SelectedItemStyle, and EditItemStyle. Therefore, if background color is set as red in ItemStyle, EditItemStyle will also have red background color, unless it is explicitly set to a different value.
-+
A data list item can be in normal mode, edit mode or selected mode. Different templates will apply to items of different modes. To change an item's mode, modify EditItemIndex or SelectedItemIndex. Note, if an item is in edit mode, then selecting this item will have no effect.
-+
TDataList provides several events to facilitate manipulation of its items,
-+
The following example shows how to use TDataList to display tabular data, with different layout and styles.
+
A common use of TDataList is for maintaining tabular data, including browsing, editing, deleting data items. This is enabled by the command events and various item templates of TDataList.
-+
The following example displays a computer product information. Users can add new products, modify or delete existing ones. In order to locate the data item for updating or deleting, DataKeys property is used.
-+
Be aware, for simplicity, this application does not do any input validation. In real applications, make sure user inputs are valid before saving them into databases.
TDatePicker displays a text box for date input purpose. +
TDatePicker displays a text box for date input purpose.
When the text box receives focus, a calendar will pop up and users can
pick up from it a date that will be automatically entered into the text box.
The format of the date string displayed in the text box is determined by
the DateFormat property. Valid formats are the combination of the
following tokens:
-
+
The date of the date picker can be set using the Date or Timestamp
properties. The Date property value must be in the same format as the pattern
specified in the DateFormat property. The Timestamp property
only accepts integers such as the Unix timestamp.
-TDatePicker has three Mode to show the date picker popup.
-
+TDatePicker has three Mode to show the date picker popup.
+
-
The CssClass property can be used to override the CSS class name +
The CssClass property can be used to override the CSS class name for the date picker panel. The CalendarStyle property changes the overall calendar style. -The following CalendarStyle values are available: -
The InputMode property can be set to "TextBox" or "DropDownList" with +
The InputMode property can be set to "TextBox" or "DropDownList" with default as "TextBox". In DropDownList mode, in addition to the popup date picker, three drop down list (day, month and year) are presented to select the date . When InputMode equals "DropDownList", the order and appearance of the date, month, and year will depend on the pattern specified in DateFormat property.
-The popup date picker can be hidden by specifying ShowCalendar as false. Much of the +
The popup date picker can be hidden by specifying ShowCalendar as false. Much of the text of the popup date picker can be changed to a different language using the Culture property.
-The calendar picker year limit can be set using the FromYear and UpToYear properties +
The calendar picker year limit can be set using the FromYear and UpToYear properties where FromYear is the starting year and UpToYear is the last year selectable. The starting day of the week can be changed by the FirstDayOfWeek property, with 0 as Sunday, 1 as Monday, etc.
-Note 1: If the InputMode is "TextBox", the DateFormat should +
Note 1: If the InputMode is "TextBox", the DateFormat should
only NOT contain MMM or MMMM patterns. The
server side date parser will not be able to determine the correct date if MMM or
MMMM are used. When InputMode equals "DropDownList", all patterns can be used.
Note 2: When the TDatePicker is used together +
Note 2: When the TDatePicker is used together with a validator, the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker AND must set DataType="Date" on the validator to ensure correct validation. See diff --git a/demos/quickstart/protected/pages/Controls/Expression.page b/demos/quickstart/protected/pages/Controls/Expression.page index 044808c6..71230fba 100644 --- a/demos/quickstart/protected/pages/Controls/Expression.page +++ b/demos/quickstart/protected/pages/Controls/Expression.page @@ -3,18 +3,18 @@
+
TExpression evaluates a PHP expression and displays the evaluation result. To specify the expression to be evaluated, set the Expression property. Note, TExpression evaluates the expression during the rendering control lifecycle.
-+
The context of the expression in a TExpression control is the control itself. That is, $this represents the control object if it is present in the expression. For example, the following template tag will display the title of the page containing the TExpression control.
-+
Be aware, since TExpression allows execution of arbitrary PHP code, in general you should not use it to evaluate expressions submitted by your application users.
diff --git a/demos/quickstart/protected/pages/Controls/FileUpload.page b/demos/quickstart/protected/pages/Controls/FileUpload.page index 404a144e..1f2a2adb 100644 --- a/demos/quickstart/protected/pages/Controls/FileUpload.page +++ b/demos/quickstart/protected/pages/Controls/FileUpload.page @@ -3,22 +3,22 @@+
TFileUpload displays a file upload field on a Web page. Upon postback, the text entered into the field will be treated as the (local) name of the file that is uploaded to the server.
-+
TFileUpload raises an OnFileUpload event when it is post back. The property HasFile indicates whether the file upload is successful or not. If successful, the uploaded file may be saved on the server by calling saveAs() method.
-+
The following properties give the information about the uploaded file:
-+
If the file upload is unsuccessful, the property ErrorCode gives the error code describing the cause of failure. See PHP documentation for a complete explanation of the possible error codes.
diff --git a/demos/quickstart/protected/pages/Controls/Head.page b/demos/quickstart/protected/pages/Controls/Head.page index 227b5282..3ee2d6c0 100644 --- a/demos/quickstart/protected/pages/Controls/Head.page +++ b/demos/quickstart/protected/pages/Controls/Head.page @@ -3,7 +3,7 @@+
TBD
diff --git a/demos/quickstart/protected/pages/Controls/HiddenField.page b/demos/quickstart/protected/pages/Controls/HiddenField.page index aa2e7c87..7564573e 100644 --- a/demos/quickstart/protected/pages/Controls/HiddenField.page +++ b/demos/quickstart/protected/pages/Controls/HiddenField.page @@ -3,10 +3,10 @@+
THiddenField represents a hidden field on a Web page. The value of the hidden field can be accessed via its Value property.
-+
THiddenField raises an OnValueChanged event if its value is changed during postback.
diff --git a/demos/quickstart/protected/pages/Controls/HtmlArea.page b/demos/quickstart/protected/pages/Controls/HtmlArea.page index e40a4444..2b755802 100644 --- a/demos/quickstart/protected/pages/Controls/HtmlArea.page +++ b/demos/quickstart/protected/pages/Controls/HtmlArea.page @@ -3,18 +3,18 @@+
THtmlArea displays a WYSIWYG text input field on a Web page to collect input in HTML format. The text displayed in the THtmlArea control is specified or determined by using the Text property. To adjust the size of the input region, set Width and Height properties instead of Columns and Rows because the latter has no meaning under this situation. To disable the WYSIWYG feature, set EnableVisualEdit to false.
-+
THtmlArea provides the WYSIWYG feature by wrapping the functionalities provided by the TinyMCE project.
-+
The default editor gives only the basic tool bar. To change or add additional tool bars, use the Options property to add additional editor options with each options on a new line. See TinyMCE website for a complete list of options. The following example displays a toolbar specific for HTML table manipulation,
-+
The client-side visual editing capability is supported by Internet Explorer 5.0+ for Windows and Gecko-based browser. If the browser does not support the visual editing, a traditional textarea will be displayed.
diff --git a/demos/quickstart/protected/pages/Controls/HyperLink.page b/demos/quickstart/protected/pages/Controls/HyperLink.page index 9fa6bde3..5861a00f 100644 --- a/demos/quickstart/protected/pages/Controls/HyperLink.page +++ b/demos/quickstart/protected/pages/Controls/HyperLink.page @@ -3,7 +3,7 @@+
THyperLink displays a hyperlink on a page. The hyperlink URL is specified via the NavigateUrl property, and link text is via the Text property. The link target is specified via the Target property. It is also possible to display an image by setting the ImageUrl property. In this case, Text is displayed as the alternate text of the image. If both ImageUrl and Text are empty, the content enclosed within the control tag will be rendered.
+
TImage displays an image on a page. The image is specified via the ImageUrl property which takes a relative or absolute URL to the image file. The alignment of the image displayed is set by the ImageAlign property. To set alternate text or long description of the image, use AlternateText or DescriptionUrl, respectively.
+
TImageButton is also similar to TButton, except that TImageButton displays the button as an image. The image is specified via ImageUrl, and the alternate text is specified by Text. In addition, it is possible to obtain the coordinate of the point where the image is clicked. The coordinate information is contained in the event parameter of the OnClick event (not OnCommand).
+
TImageMap represents an image on a Web page with predefined hotspot regions that can respond differently to users' clicks on them. Depending on the HotSpotMode of the hotspot region, clicking on the hotspot may trigger a postback or navigate to a specified URL.
-+
Each hotspot is described using a THotSpot object and is maintained in the HotSpots collection in TImageMap. A hotspot can be a circle, rectangle, polygon, etc.
-+
Hotspots can be added to TImageMap via its HotSpots property or in a template like the following,
-+
TInlineFrame displays an inline frame (<iframe>) on a Web page. The location of the frame content is specified by the FrameUrl property.
-+
The appearance of a TInlineFrame may be customized with the following properties, in addition to those inherited from TWebControl.
-+
The following samples show TInlineFrame with different property settings. The Google homepage is used as the frame content.
+
TJavascriptLogger provides logging for client-side javascript. It is mainly a wrapper of the Javascript developed at http://gleepglop.com/javascripts/logger/.
-+
To use TJavascriptLogger, simply place the following component tag in a page template.
-+
Then, the client-side Javascript may contain the following statements. When they are executed, they will appear in the logger window.
-+
To toggle the visibility of the logger and console on the browser window, press ALT-D (or CTRL-D on OS X).
diff --git a/demos/quickstart/protected/pages/Controls/Label.page b/demos/quickstart/protected/pages/Controls/Label.page index b7d5b094..794c48de 100644 --- a/demos/quickstart/protected/pages/Controls/Label.page +++ b/demos/quickstart/protected/pages/Controls/Label.page @@ -3,7 +3,7 @@+
TLabel displays a piece of text on a Web page. The text to be displayed is set via its Text property. If Text is empty, content enclosed within the TLabel component tag will be displayed. TLabel may also be used as a form label associated with some control on the form. Since Text is not HTML-encoded when being rendered, make sure it does not contain dangerous characters that you want to avoid.
+
TLinkButton is similar to TButton in every aspect except that TLinkButton is displayed as a hyperlink. The link text is determined by its Text property. If the Text property is empty, then the body content of the button is displayed (therefore, you can enclose a <img> tag within the button body and get an image button.
+
List controls covered in this section all inherit directly or indirectly from TListControl. Therefore, they share the same set of commonly used properties, including,
-+
Since TListControl inherits from TDataBoundControl, these list controls also share a common operation known as databinding. The Items can be populated from preexisting data specified by DataSource or DataSourceID. A function call to dataBind() will cause the data population. For list controls, data can be specified in the following two kinds of format:
-+
TListBox displays a list box that allows single or multiple selection. Set the property SelectionMode as Single to make a single selection list box, and Multiple a multiple selection list box. The number of rows displayed in the box is specified via the Rows property value.
+
TDropDownList displays a dropdown list box that allows users to select a single option from a few prespecified ones.
+
TCheckBoxList displays a list of checkboxes on a Web page. The alignment of the text besides each checkbox can be specified TextAlign. The layout of the checkboxes can be controlled by the following properties:
-+
TRadioButtonList is similar to TCheckBoxList in every aspect except that each TRadioButtonList displays a group of radiobuttons. Only one of the radiobuttions can be selected (TCheckBoxList allows multiple selections.)
+
TBulletedList displays items in a bullet format on a Web page. The style of the bullets can be specified by BulletStyle. When the style is CustomImage, the bullets are displayed as images, which is specified by BulletImageUrl.
-+
TBulletedList displays the item texts in three different modes,
-+
TLiteral displays a static text on a Web page. TLiteral is similar to the TLabel control, except that the TLiteral * control has no style properties, such as BackColor, Font, etc.
-+
The text displayed by TLiteral can be programmatically controlled by setting the Text property. The text displayed may be HTML-encoded if the Encode is true (the default value is false).
-+
TLiteral will render the contents enclosed within its component tag if Text is empty.
-+
Be aware, if Encode is false, make sure Text does not contain unwanted characters that may bring security vulnerabilities.
diff --git a/demos/quickstart/protected/pages/Controls/MultiView.page b/demos/quickstart/protected/pages/Controls/MultiView.page index a22711b6..03dca27e 100644 --- a/demos/quickstart/protected/pages/Controls/MultiView.page +++ b/demos/quickstart/protected/pages/Controls/MultiView.page @@ -3,13 +3,13 @@+
TMultiView serves as a container for a group of TView controls, which can be retrieved by the Views property. Each view contains child controls. TMultiView determines which view and its child controls are visible. At any time, at most one view is visible (called active). To make a view active, set ActiveView or ActiveViewIndex. Note, by default there is no active view.
-+
To add a view to TMultiView, manipulate the Views collection or add it in template as follows,
-+
TMultiView responds to the following command events to manage the visibility of its views.
-+
Upon postback, if the active view index is changed, TMultiView will raise an OnActiveViewChanged event.
-+
The Hangman game is a typical use of TMultiView. The following example demonstrates another usage of TMultiView.
diff --git a/demos/quickstart/protected/pages/Controls/NewControl.page b/demos/quickstart/protected/pages/Controls/NewControl.page index 5662f848..d6cb52c5 100644 --- a/demos/quickstart/protected/pages/Controls/NewControl.page +++ b/demos/quickstart/protected/pages/Controls/NewControl.page @@ -1,39 +1,39 @@+
Writing new controls is often desired by advanced programmers, because they want to reuse the code that they write for dealing with complex presentation and user interactions.
-+
In general, there are two ways of writing new controls: composition of existing controls and extending existing controls. They all require that the new control inherit from TControl or its child classes.
+
Composition is the easiest way of creating new controls. It mainly involves instantiating existing controls, configuring them and making them the constituent components. The properties of the constituent components are exposed through subproperties.
-+
One can compose a new control in two ways. One is to extend TCompositeControl and override the TControl::createChildControls() method. The other is to extend TTemplateControl (or its child classes) and write a control template. The latter is easier to use and can organize the layout constituent components more intuitively, while the former is more efficient because it does not require parsing of the template.
-+
As an example, we show how to create a labeled textbox called LabeledTextBox using the above two approaches. A labeled textbox displays a label besides a textbox. We want reuse the PRADO provided TLabel and TTextBox to accomplish this task.
+
We need two files: a control class file named LabeledTextBox.php and a control template file named LabeledTextBox.tpl. Both must reside under the same directory.
-+
Like creating a PRADO page, we can easily write down the content in the control template file.
-+
The above template specifies a TLabel control named Label and a TTextBox control named TextBox. We would to expose these two controls. This can be done by defining a property for each control in the LabeledTextBox class file. For example, we can define a Label property as follows,
-+
In the above, the method call to ensureChildControls() ensures that both the label and the textbox controls are created (from template) when the Label property is accessed. The TextBox property can be implemented similarly.
+
For a composite control as simple as LabeledTextBox, it is better to create it by extending TCompositeControl and overriding the createChildControls() method, because it does not use templates and thus saves template parsing time.
-+
Complete code for LabeledTextBox is shown as follows,
-+
To use LabeledTextBox control, first we need to include the corresponding class file. Then in a page template, we can write lines like the following,
-+
In the above, Label.Text is a subproperty of LabeledTextBox, which refers to the Text property of the Label property. For other details of using LabeledTextBox, see the above online examples.
+
Extending existing controls is the same as conventional class inheritance. It allows developers to customize existing control classes by overriding their properties, methods, events, or creating new ones.
-+
The difficulty of the task depends on how much an existing class needs to be customized. For example, a simple task could be to customize TLabel control, so that it displays a red label by default. This would merely involves setting the ForeColor property to "red" in the constructor. A difficult task would be to create controls that provide completely innovative functionalities. Usually, this requires the new controls extend from "low level" control classes, such as TControl or TWebControl.
-+
In this section, we mainly introduce the base control classes TControl and TWebControl, showing how they can be customized. We also introduce how to write controls with specific functionalities, such as loading post data, raising post data and databinding with data source.
+
TControl is the base class of all control classes. Two methods are of the most importance for derived control classes:
-+
TWebControl is mainly used as a base class for controls representing HTML elements. It provides a set of properties that are common among HTML elements. It breaks the TControl::render() into the following methods that are more suitable for rendering an HTML element:
-+
When rendering the openning HTML tag, TWebControl calls getTagName() to obtain the tag name. Derived classes may override this method to render different tag names.
+
If a control wants to respond to client-side events and translate them into server side events (called postback events), such as TButton, it has to implement the IPostBackEventHandler interface.
-+
If a control wants to be able to load post data, such as TTextBox, it has to implement the IPostBackDataHandler interface.
-+
If a control wants to get data from some external data source, it can extend TDataBoundControl. TDataBoundControl implements the basic properties and methods that are needed for populating data via databinding. In fact, controls like TListControl, TRepeater are TDataGrid are all derived from it.
+
TOutputCache enables caching a portion of a Web page, also known as partial caching. The content being cached are HTML page source coming from static texts on a PRADO template or rendered by one or several controls on the template. When the cached content is used, controls generating the content are no longer created for the page hierarchy and thus significant savings in page processing time can be achieved. The side-effect, as you might already find out, is that the content displayed may be stale if the cached version is shown to the users.
-+
To use TOutputCache, simply enclose the content to be cached within the TOutputCache component tag on a template (either page or non-page control template), e.g.,
-+
where content to be cached can be static text and/or template tags. If the latter, the rendering results of the template tags will be cached. You can place one or several TOutputCache on a single template and they can be nested.
@@ -23,23 +23,23 @@ where content to be cached can be static text and/or template tags. If the latte TOutputCache stores cached content via PRADO cache modules (e.g. TSqliteCache) and thus requires at least one cache module loaded when the application runs. -+
The validity of the cached content is determined based on two factors: the Duration and the cache dependency. The former specifies the number of seconds that the data can remain valid in cache (defaults to 60s), while the latter specifies conditions that the cached data depends on. If a dependency changes (e.g. relevant data in DB are updated), the cached data will be invalidated and discarded.
-+
There are two ways to specify cache dependency. One may write event handlers to respond to the OnCheckDependency event and set the event parameter's IsValid property to indicate whether the cached data remains valid or not. One can also extend TOutputCache and override its getCacheDependency() method.
-+
The content fetched from cache may be variated with respect to some parameters. TOutputCache supports variation with respect to request parameters, which is specified by VaryByParam property. If a specified request parameter is different, a different version of cached content is used. This is extremely useful if a page's content may be variated according to some GET parameters. The content being cached may also be variated with user sessions if VaryBySession is set true. To variate the cached content by other factors, override calculateCacheKey() method.
-+
Output caches can be nested. An outer cache takes precedence over an inner cache in determining the validity of cached contents. This means, if the content cached by the inner cache expires or is invalidated, while that by the outer cache not, the outer cached content will be used.
-+
By default, TOutputCache is effective only for non-postback page requests and when a cache module is enabled. Do not attempt to address child controls of TOutputCache when the cached content is currently being used. Use ContentCached property to determine whether the content is cached or not.
diff --git a/demos/quickstart/protected/pages/Controls/Pager.page b/demos/quickstart/protected/pages/Controls/Pager.page index 20b33b95..af2e4b0a 100644 --- a/demos/quickstart/protected/pages/Controls/Pager.page +++ b/demos/quickstart/protected/pages/Controls/Pager.page @@ -3,33 +3,33 @@+
TPager creates a pager that provides UI for end-users to interactively specify which page of data to be rendered in a TDataBoundControl-derived control, such as TDataList, TRepeater, TCheckBoxList, etc. The target data-bound control is specified by the ControlToPaginate property, which must be the ID path of the target control reaching from the pager's naming container.
-+
Note, the target data-bound control must have its AllowPaging set to true. Otherwise the pager will be invisible. Also, in case when there is only one page of data available, the pager will also be invisible.
-+
TPager can display one of the following three types of user interface, specified via its Mode property:
-+
These user interfaces may be further customized by configuring the following properties
-+
TPager raises an OnPageIndexChanged event when an end-user interacts with it and specifies a new page (e.g. by clicking on a next page button that would lead to the next page.) Developers may write handlers to respond to this event and obtain the desired new page index from the event parameter's property NewPageIndex. Using this new page index, one can feed a new page of data to the associated data-bound control.
diff --git a/demos/quickstart/protected/pages/Controls/Panel.page b/demos/quickstart/protected/pages/Controls/Panel.page index be36095b..4f4f9b14 100644 --- a/demos/quickstart/protected/pages/Controls/Panel.page +++ b/demos/quickstart/protected/pages/Controls/Panel.page @@ -3,7 +3,7 @@+
TPanel acts as a presentational container for other control. It displays a <div> element on a page. The property Wrap specifies whether the panel's body content should wrap or not, while HorizontalAlign governs how the content is aligned horizontally and Direction indicates the content direction (left to right or right to left). You can set BackImageUrl to give a background image to the panel, and you can set GroupingText so that the panel is displayed as a field set with a legend text. Finally, you can specify a default button to be fired when users press 'return' key within the panel by setting the DefaultButton property.
+
TPlaceHolder reserves a place on a template, where static texts or controls may be dynamically inserted.
diff --git a/demos/quickstart/protected/pages/Controls/RadioButton.page b/demos/quickstart/protected/pages/Controls/RadioButton.page index b40f37bd..bdf5dee2 100644 --- a/demos/quickstart/protected/pages/Controls/RadioButton.page +++ b/demos/quickstart/protected/pages/Controls/RadioButton.page @@ -3,7 +3,7 @@+
TRadioButton is similar to TCheckBox in every aspect, except that TRadioButton displays a radio button on a Web page. The radio button can belong to a specific group specified by GroupName such that only one radio button within that group can be selected at most.
+
TRepeater displays its content defined in templates repeatedly based on the given data specified by the DataSource or DataSourceID property. The repeated contents can be retrieved from the Items property. Each item is created by instantiating a template and each is a child control of the repeater.
-+
Like normal control templates, the repeater templates can contain static text, controls and special tags, which after instantiation, become child contents of the corresponding item. TRepeater defines five templates for different purposes,
-+
To populate data into the repeater items, set DataSource to a valid data object, such as array, TList, TMap, or a database table, and then call dataBind() for the repeater. That is,
-+
Normally, you only need to do this when the page containing the repeater is initially requested. In postbacks, TRepeater is smart enough to remember the previous state, i.e., contents populated with datasource information.The following sample displays tabular data using TRepeater.
-+
TRepeater provides several events to facilitate manipulation of its items,
-+
The following example shows how to use TRepeater to display tabular data.
+
TRepeater can be used in more complex situations. As an example, we show in the following how to use nested repeaters, i.e., repeater in repeater. This is commonly seen in presenting master-detail data. To use a repeater within another repeater, for an item for the outer repeater is created, we need to set the detail data source for the inner repeater. This can be achieved by responding to the OnItemDataBound event of the outer repeater. An OnItemDataBound event is raised each time an outer repeater item completes databinding. In the following example, we exploit another event of repeater called OnItemCreated, which is raised each time a repeater item (and its content) is newly created. We respond to this event by setting different background colors for repeater items to achieve alternating item background display. This saves us from writing an AlternatingItemTemplate for the repeaters.
+
Besides displaying data, TRepeater can also be used to collect data from users. Validation controls can be placed in TRepeater templates to verify that user inputs are valid.
-+
The PRADO component composer demo is a good example of such usage. It uses a repeater to collect the component property and event definitions. Users can also delete or adjust the order of the properties and events, which is implemented by responding to the OnItemCommand event of repeater.
-+
See in the following yet another example showing how to use repeater to collect user inputs.
+
TSafeHtml is a control that strips down all potentially dangerous HTML content. It is mainly a wrapper of the SafeHTML project. According to the SafeHTML project, it tries to safeguard the following situations when the string is to be displayed to end-users:
-+
To use TSafeHtml, simply enclose the content to be secured within the TSafeHtml component tag in a template. The content may consist of both static text and PRADO controls. If the latter, the rendering result of the controls will be secured.
diff --git a/demos/quickstart/protected/pages/Controls/Standard.page b/demos/quickstart/protected/pages/Controls/Standard.page index f19bc07e..6ea2d52a 100644 --- a/demos/quickstart/protected/pages/Controls/Standard.page +++ b/demos/quickstart/protected/pages/Controls/Standard.page @@ -2,7 +2,7 @@* the tutorial for this control is not completed yet.
-+
TStatements evaluates a sequence of PHP statements and displays the content rendered by the statements. To specify the PHP statements to be evaluated, set the Statements property. For example, the following component tag displays the current time on the Web page,
-+
Note, TStatements evaluates the PHP statements during the rendering control lifecycle. Unlike TExpression, TStatements only displays the content 'echoed' within the statements.
-+
The context of the statements in a TStatements control is the control itself. That is, $this represents the control object if it is present in the statements. For example, the following statement tag will display the title of the page containing the TStatements control.
-+
Be aware, since TStatements allows execution of arbitrary PHP code, in general you should not use it to evaluate PHP code submitted by your application users.
diff --git a/demos/quickstart/protected/pages/Controls/Table.page b/demos/quickstart/protected/pages/Controls/Table.page index e0f5586e..ab9e6c1f 100644 --- a/demos/quickstart/protected/pages/Controls/Table.page +++ b/demos/quickstart/protected/pages/Controls/Table.page @@ -3,7 +3,7 @@+
TTable displays an HTML table on a page. It is used together with TTableRow and TTableCell to allow programmatically manipulating HTML tables. The rows of the table is stored in Rows property. You may set the table cellspacing and cellpadding via the CellSpacing and CellPadding properties, respectively. The table caption can be specified via Caption whose alignment is specified by CaptionAlign. The GridLines property indicates how the table should display its borders, and the BackImageUrl allows the table to have a background image.
+
TTextBox displays a text box on a Web page. The content in the text box is determined by the Text property. You can create a SingleLine, a MultiLine, or a Password text box by setting the TextMode property. The Rows and Columns properties specify their dimensions. If AutoPostBack is true, changing the content in the text box and then moving the focus out of it will cause postback action.
+
TTextHighlighter does syntax highlighting for its body content, including both static text and the rendering results of its child controls. The text being highlighted follows the syntax of the specified Language, which can be 'php' (default), 'prado', 'css', 'html', etc. Here, 'prado' stands for the syntax of PRADO control templates.
-+
If line numbers are desired in front of each line, set ShowLineNumbers to true.
-+
To use TTextHighlighter, simply enclose the contents to be syntax highlighted within the body of a TTextHighlighter control. The following example highlights a piece of PHP code,
-+
Validation controls, called validators, perform validation on user-entered data values when they are post back to the server. The validation is triggered by a postback control, such as a TButton, a TLinkButton or a TTextBox (under AutoPostBack mode) whose CausesValidation property is true.
-+
Validation is always performed on server side. If EnableClientScript is true and the client browser supports JavaScript, validators may also perform client-side validation. Client-side validation will validate user input before it is sent to the server. The form data will not be submitted if any error is detected. This avoids the round-trip of information necessary for server-side validation.
-+
Validators share a common set of properties, which are defined in the base class TBaseValidator class and listed as follows,
-+
TRequiredFieldValidator ensures that the user enters some data in the specified input field. By default, TRequiredFieldValidator will check if the user input is empty or not. The validation fails if the input is empty. By setting InitialValue, the validator can check if the user input is different from InitialValue. If not, the validation fails.
+
TRegularExpressionValidator verifies the user input against a regular pattern. The validation fails if the input does not match the pattern. The regular expression can be specified by the RegularExpression property. Some commonly used regular expressions include:
-[\w]{6,}(0\d{1,4}-|\(0\d{1,4}\) ?)?\d{1,4}-\d{4}\d{3}(-(\d{4}|\d{2}))?\d{5}(-\d{4})?\d{3}-\d{2}-\d{4}+
More regular expression patterns can be found on the Internet, e.g. http://regexlib.com/.
-+
Note, TRegularExpressionValidator only checks for nonempty user input. Use a TRequiredFieldValidator to ensure the user input is not empty.
+
TEmailAddressValidator verifies that the user input is a valid email address. The validator uses a regular expression to check if the input is in a valid email address format. If CheckMXRecord is true, the validator will also check whether the MX record indicated by the email address is valid, provided checkdnsrr() is available in the installed PHP.
-+
Note, if the input being validated is empty, TEmailAddressValidator will not do validation. Use a TRequiredFieldValidator to ensure the value is not empty.
+
TCompareValidator compares the user input with a constant value specified by ValueToCompare, or another user input specified by ControlToCompare. The Operator property specifies how to compare the values, which includes Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan and LessThanEqual. Before comparison, the values being compared will be converted to the type specified by DataType listed as follows,
-+
Note, if the input being validated is empty, TEmailAddressValidator will not do validation. Use a TRequiredFieldValidator to ensure the value is not empty.
-+
N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.
+
TDataTypeValidator verifies if the input data is of specific type indicated by DataType. The data types that can be checked against are the same as those in TCompareValidator.
-+
N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.
@@ -105,10 +105,10 @@ TDataTypeValidator verifies if the input data is of specific type indicated by <+
TRangeValidator verifies whether an input value is within a specified range. TRangeValidator uses three key properties to perform its validation. The MinValue and MaxValue properties specify the minimum and maximum values of the valid range. The DataType property specifies the data type of the value being validated. The value will be first converted into the specified type and then compare with the valid range. The data types that can be checked against are the same as those in TCompareValidator.
-+
N.B. If validating against a TDatePicker the DataType must be equal to "Date" and the DateFormat property of the validator must be equal to the DateFormat of the TDatePicker.
@@ -116,16 +116,16 @@ TRangeValidator verifies whether an input value is within a specified range. TRa+
TCustomValidator performs user-defined validation (either server-side or client-side or both) on an input control.
-+
To create a server-side validation function, provide a handler for the OnServerValidate event that performs the validation. The data string of the input control to validate can be accessed by the event parameter's Value property. The result of the validation should be stored in the IsValid property of the parameter.
-+
To create a client-side validation function, add the client-side validation javascript function to the page template and assign its name to the ClientValidationFunction property. The function should have the following signature:
-