Developer Documentation and Developer Version for Widget Developers

PHPCow Template Language – Pagination Module

Continuing CTL topic, I want to introduce new pagination module developed for new template engine. Pagination is a must feature for any content related system. We tried to develop universal module which could be integrated with any other module that requires pagination. Introduced module is highly customizable that gives template authors unlimited capabilities to feet pagination to desired needs.

Simplest usage of the pagination module is shown below:

{mod:cow:pagination uri_pattern="/blog/posts/page/{page_number}" record_count="50" limit="3"}
    {var:pagination.links}
{/mod:cow:pagination}

Shown snippet of code will generate pagination shown on the pictures:

Shown example uses three attributes 1) uri_pattern - Defines URI to be used for paginated results. It is possible to use any URI pattern but there is one simple requirement that URI must contain "{page_number}" special variable. Pagination module will replace this variable with apropriate page number; 2) record-count - that defines total count of particular type of content (e.g. blog posts or news); 3) limit - defines how many items must be shown per page;

There are much more attributes that could be supplied to the module, these attributes give endless customization options to template authors. For example it is possible to change labels for next, previous, first, and last links or change number of adjacent pages.

Supported attributes are listed below:

//URI to be used for paginated results
uri_pattern="{var:env.context}/posts/page/{page_number}"

//Previous/Next links to be shown, defaults to "false"
prev_next="true" 

//First/Last links to be shown, defaults to "true"
first_last="false"

//label for "Previous" link
prev_label="« Previous"

//label for "Next" link
next_label="Next »" 

//label for "First" link
first_label="First"

//label for "Last" link 
last_label="Last"

//total number of records (e.g. blog posts or news)
record_count="50"

//how many results must be shown on each page
limit="3"

//number of adjacent pages, defaults to "3"
adjacent="2"

PHPCow Template Language – Modules

Previously I briefly overviewed CTL (see this post). Now I want to introduce another most powerful feature of CTL. This is CTL Module tag.

Think about CTL Module tag as a custom tag. This is a simple tag like construct that allows to integrate new functionality into CTL without harming the core and it requires ZERO configuration. To install module you only need to create correct folder structure.

Module tag looks like something similar:

{mod:cow:tagcloud}
    //rest of content here
{/mod:cow:tagcloud}

Module tags have simple structure. As with other structures it starts and ends with curly braces, followed by “mod:” prefix, followed by “package:” prefix and finally actual module name. Think about package as a simple folder, for the shown example package(folder) name is “cow” and the module name is “tagcloud”.

This is real module which is used in this blog(see right sidebar). We developed this simple but useful module to arrange categories like tag cloud.

As general HTML tags, module tags support attributes. Attribute names are module parameter names and attribute values are module parameter values. See example below:

{mod:cow:comments limit="5" order="desc"}
    <h3>Recent Comment</h3>
    <ul class="tag-cloud">
    {mod:iterator}
        <li>{var:comment.member.name}: {var:comment.title}</li>
    {/mod:iterator}
    </ul>
{/mod:cow:comments}

Shown snippet of code will generate list of recent comments, something like you see on the right sidebar.

In this example we used two attributes, “limit” and “order”. We told module to select five latest comments and order them in descendant order. But, in the example we used one more tag which is a part of module tag specification. This is “mod:iterator” tag. This very useful tag is used to iterate result returned by module, instead of using boring “foreach” structure we used module iterator to generate list of comments.

What we need to develop CTL modules? and is it necessary to dive into PHPCow core API details?

First of all, only thing you need is to extend one base module class. Secondly just begin programming as you do it usually, nothing from PHPCow is necessary except knowing database structure if you are going to enhance PHPCow. In other words you have absolute freedom in you module development.