Subversion-Projekte lars-tiefland.prado

<com:TContent ID="Main">

<h1>Creating <tt>ListPost</tt> Page</h1>

<p>
The <tt>ListPost</tt> page shows the latest blog posts in a list. If there are too many posts, they will be displayed in several pages.
</p>

<p>
Before we proceed with the implementation, we would like to point our homepage to the upcoming <tt>ListPage</tt> page, because we want the users to see latest posts when they hit the website. To do so, we modify the application configuration <tt>protected/application.xml</tt> as follows,
</p>

<com:TTextHighlighter CssClass="source" Language="xml">
......
<services>
  <service id="page" class="TPageService" DefaultPage="posts.ListPost">
    <pages MasterClass="Application.layouts.MainLayout" />
  </service>
</services>
</com:TTextHighlighter>

<p>
We now create the template and class files for the <tt>ListPost</tt> page: <tt>protected/pages/posts/ListPost.page</tt> and <tt>protected/pages/posts/ListPost.php</tt>.
</p>

<h2>Creating Page Template</h2>
<p>
Based on the functionality requirement of the <tt>ListPost</tt> page, we will use two controls in the page template:
</p>
<ul>
<li><a href="http://www.pradosoft.com/demos/quickstart/?page=Controls.Repeater">TRepeater</a>: this control is mainly used to display a list of data items. The presentation of the each data item can be specified via an inline template or an external template control (the approach we will use here).</li>
<li><a href="http://www.pradosoft.com/demos/quickstart/?page=Controls.Pager">TPager</a>: this control is used to paginate a list of data items. It interacts with end-users to determine which page of data to be displayed in a <a href="http://www.pradosoft.com/demos/quickstart/?page=Controls.List">list control</a> (e.g. <tt>TListBox</tt>) or <a href="http://www.pradosoft.com/demos/quickstart/?page=Controls.Data">data control</a> (e.g. <tt>TRepeater</tt>).</li>
</ul>

<p>
Below is the content in the page template:
</p>

<com:TTextHighlighter CssClass="source" Language="prado">
&lt;%@ Title="My Blog" %>

&lt;com:TContent ID="Main">

&lt;com:TRepeater ID="Repeater"
        ItemRenderer="Application.pages.posts.PostRenderer"
        AllowPaging="true"
        AllowCustomPaging="true"
        PageSize="5"
        />

&lt;com:TPager ControlToPaginate="Repeater" OnPageIndexChanged="pageChanged" />

&lt;/com:TContent>
</com:TTextHighlighter>

<p>
In the repeater, we specify that the repeated content is to be displayed using the item renderer <tt>PostRenderer</tt> which we will create soon after. In order for PRADO to find this class, we give the complete namespace path <tt>Application.pages.posts.PostRenderer</tt>, meaning the class file is <tt>protected/pages/posts/PostRenderer.php</tt>.
</p>

<p>
We also set a few other properties of repeater to enable paging. And we set <tt>ControlToPaginate</tt> property of the pager so that it knows whose repeated content should be paginated.
</p>


<h2>Creating Page Class</h2>

<p>
From the above page template, we see that we need to write a page class that implements the event handler: <tt>pageChanged()</tt> (attached to the pager's <tt>OnPageIndexChanged</tt> event). We also need to populate post data into the repeater according to the current paging setting. The following is the complete source code of the page class:
</p>

<com:TTextHighlighter CssClass="source" Language="php">
class ListPost extends TPage
{
        /**
         * Initializes the repeater.
         * This method is invoked by the framework when initializing the page
         * @param mixed event parameter
         */
        public function onInit($param)
        {
                parent::onInit($param);
                if(!$this->IsPostBack)  // if the page is requested the first time
                {
                        // get the total number of posts available
                        $this->Repeater->VirtualItemCount=PostRecord::finder()->count();
                        // populates post data into the repeater
                        $this->populateData();
                }
        }

        /**
         * Event handler to the OnPageIndexChanged event of the pager.
         * This method is invoked when the user clicks on a page button
         * and thus changes the page of posts to display.
         */
        public function pageChanged($sender,$param)
        {
                // change the current page index to the new one
                $this->Repeater->CurrentPageIndex=$param->NewPageIndex;
                // re-populate data into the repeater
                $this->populateData();
        }

        /**
         * Determines which page of posts to be displayed and
         * populates the repeater with the fetched data.
         */
        protected function populateData()
        {
                $offset=$this->Repeater->CurrentPageIndex*$this->Repeater->PageSize;
                $limit=$this->Repeater->PageSize;
                if($offset+$limit>$this->Repeater->VirtualItemCount)
                        $limit=$this->Repeater->VirtualItemCount-$offset;
                $this->Repeater->DataSource=$this->getPosts($offset,$limit);
                $this->Repeater->dataBind();
        }

        /**
         * Fetches posts from database with offset and limit.
         */
        protected function getPosts($offset, $limit)
        {
                // Construts a query criteria
                $criteria=new TActiveRecordCriteria;
                $criteria->OrdersBy['create_time']='desc';
                $criteria->Limit=$limit;
                $criteria->Offset=$offset;
                // query for the posts with the above criteria and with author information
                return PostRecord::finder()->withAuthor()->findAll($criteria);
        }
}
</com:TTextHighlighter>

<h2>Creating <tt>PostRenderer</tt></h2>

<p>
We still need to create the item renderer class <tt>PostRenderer</tt>. It defines how each post should be displayed in the repeater. We create it as a template control which allows to specify the post presentation using our flexible template syntax. The template and the class files are saved as <tt>PostRenderer.tpl</tt> and <tt>PostRenderer.php</tt> files under the <tt>protected/pages/posts</tt> directory, respectively.
</p>

<h3>Creating Renderer Template</h3>
<p>
The renderer template specifies the presentation of various fields in a post, including title, author name, post time and content. We link the post title to the <tt>ReadPost</tt> which shows more details of the selected post.
</p>
<p>
The expression <tt>$this->Data</tt> refers to the data item passed to the repeater. In our case, it is a <tt>PostRecord</tt> object. Notice how we retrieve the author name of a post by <tt>$this->Data->author->username</tt>.
</p>

<com:TTextHighlighter CssClass="source" Language="prado">
<div class="post-box">
<h3>
&lt;com:THyperLink Text="&lt;%# $this->Data->title %>"
        NavigateUrl="&lt;%# $this->Service->constructUrl('posts.ReadPost',array('id'=>$this->Data->post_id)) %>" />
</h3>

<p>
Author:
&lt;com:TLiteral Text="&lt;%# $this->Data->author->username %>" /><br/>
Time:
&lt;com:TLiteral Text="&lt;%# date('m/d/Y h:m:sa', $this->Data->create_time) %>" />
</p>

<p>
&lt;com:TLiteral Text="&lt;%# $this->Data->content %>" />
</p>
</div>
</com:TTextHighlighter>

<h3>Creating Renderer Class</h3>
<p>
The renderer class is very simple. It extends from <tt>TRepeaterItemRenderer</tt> and contains no other code.
</p>
<com:TTextHighlighter CssClass="source" Language="php">
class PostRenderer extends TRepeaterItemRenderer
{
}
</com:TTextHighlighter>

<h2>Testing</h2>
<p>
To test the <tt>ListPost</tt> page, visit the URL <tt>http://hostname/blog/index.php</tt> (remember we have set <tt>ListPost</tt> as our new homepage). We shall expect to see the following result. Since we only have one post at the moment, the pager will not show up. Later when we finish <tt>NewPost</tt>, we can add more posts and come back to test the paging again.
</p>

<img src="<%~ output.gif %>" class="output" />

</com:TContent>