Active Record Scaffold Views
Available from Prado versions 3.1b onwards.
Active Record classes can be used together with
links both TScaffoldListView and TScaffoldEditView) to create
simple Create/Read/Update/Delete (CRUD) web applications.
The scaffold views are intended to assist in prototyping web application,
they are not designed to be as customiziable as more complex components such as
TDataGrid. The scaffold views provide
the following builtin functionality:
- Listing of all active record items.
- Searching records.
- Paging and sorting.
- Deleting an item.
- Inserting a new item.
- Updating an existing item.
- Validates required fields and basic data types.
- Presents specialized controls such as date pickers.
Scaffold views are dependent on Active Records and currently supports
the following databases: Mysql, Sqlite and Postgres SQL. Support for other databases
can be considered when there are sufficient demand.
Setting up a Scaffold View
To use the scaffold view, we first define an Active Record
class that represents a table or view in the database. Consider the following
Active Record class that corresponds to the users
table as defined in the Active Record quickstart page.
class UserRecord extends TActiveRecord
The scaffold view classes are in the System.Data.ActiveRecord.Scaffold.*
This namespace can be "imported" in the
using the application.xml file or through the php code using the Prado::using()
method. To start using the
simply set the RecordClass property value equal to an Active Record
<com:TScaffoldView RecordClass="UserRecord" />
The above code will list the current records in the users table.
Each record can be edited by clicking on the "edit" button and deleted by
clicking on the "delete" button. A new record can be added by clicking on the
"Add new record" button, enter some data (notice the automatic validation of required fields and data types), and click the "save" button.
Specifying search terms in the search textbox to find particular records. Finally, the
record list can be sorted for each column by changing the sorting column and order.
The TScaffoldView is a template control composed of other scaffold controls.
The following properties gives access to these composite controls.
- ListView -- the TScaffoldListView displaying the record list.
- EditView -- the TScaffoldEditView that renders the inputs for editing and adding records.
- SearchControl -- the TScaffoldSearch responsible to the search user interface.
All these composite controls can be customized as we shall see below.
A list of Active Records can be displayed using the TScaffoldListView
with the following useful properties.
- Header -- a TRepeater
displaying the Active Record property/field names.
- Sort -- a TDropDownList displaying the combination
of properties and its possible ordering.
- Pager -- a TPager control displaying
the links and/or buttons that navigate to different pages in the Active Record data.
- List -- a TRepeater that renders a row of Active Record data.
Custom rendering of the each Active Record can be achieved by specifying
the ItemTemplate and/or AlternatingItemTemplate property of the List
The TScaffoldListView will listen for two command events named "delete" and
"edit". A "delete" command will delete a the record for the row where the "delete" command originates.
An "edit" command will push the record data to be edited by a
TScaffoldEditView with ID specified by the EditViewID property.
The following example lists the usernames only with bold formatting.
<com:TScaffoldListView RecordClass="UserRecord" >
<strong><%# $this->Data->username %></strong>
For the TScaffoldView the list view can be accessed throught the ListView property of a TScaffoldView.
Thus, the subproperty ListView.List.ItemTemplate on TScaffoldView
is equivalent to the List.ItemTemplate subproperty of TScaffoldListView in the above example.
The SearchCondition property and
SearchParameters property (takes array values) can be
specified to customize the records to be shown. The SearchCondition
will be used as the Condition property of TActiveRecordCriteria
and the SearchParameters property corresponds to
Parameters property of TActiveRecordCriteria.
<com:TScaffoldEditView RecordPk="user1" RecordClass="UserRecord" />
Combining list + edit views
<com:TScaffoldEditView ID="edit_view" RecordClass="UserRecord" />
<com:TScaffoldListView EditViewID="edit_view" RecordClass="UserRecord" />
Customizing the TScaffoldView
<com:TScaffoldView RecordClass="UserRecord" >
<%# $this->DataItem->username %>
<com:TLinkButton Text="Edit" CommandName="edit" />