Active Record Scaffold Views

Available from Prado versions 3.1b onwards.

Active Record classes can be used together with TScaffoldListView and TScaffoldEditView ( TScaffoldView 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
{
    const TABLE='users';

    public $username;
    public $email;
}

The scaffold view classes are in the System.Data.ActiveRecord.Scaffold.* namespace. This namespace can be "imported" in the Application Configuration using the application.xml file or through the php code using the Prado::using() method. To start using the TScaffoldView simply set the RecordClass property value equal to an Active Record class name. 

<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.

TScaffoldListView

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 repeater. 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" >
    <prop:List.ItemTemplate>
        <strong><%# $this->Data->username %></strong>
    </prop:List.ItemTemplate>
</com:TScaffoldListView>
Info: 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.

TScaffoldEditView

<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" >
    <prop:ListView.List.ItemTemplate>
        <%# $this->Data->username %>
        <com:TLinkButton Text="Edit" CommandName="edit" />
    </prop:ListView.List.ItemTemplate>
</com:TScaffoldView/>