List widgets

A list widget displays a set of records on the front application. It is composed with a component and partial, and can be configured through the widget edition dialog.

Let's assume we have a "post" module.
We want to show the posts list.
config/dm/modules.yml

Content:  
  Blog:  
    post:  
      components:  
        list:  

The front component has been generated and contains:
apps/front/modules/post/actions/components.class.php

class postComponents extends myFrontModuleComponents
{  
  public function executeList()  
  {  
    // generate the query  
    $query = $this->getListQuery();  
    // generate the pager for this query  
    $this->postPager = $this->getPager($query);  
  }  

List filters

Imagine you want a list of posts, only for a given category of posts. You have a Post model and a Category model, with a one-to-many or even a many-to-many relation.
You can declare a list of articles filtered by a category:
config/dm/modules.yml

Content:  
  Blog:  
  
    category:  
  
    post:  
      components:  
        listByCategory: { filters: category }  

When adding this widget to the page, the edition dialog shows a select where you can choose the category to filter by. If Diem can guess the current category from the page context, it will propose a [contextual] entry in the select. By choosing [contextual], the category used will change depending on the page.

Available filters

You can use foreign modules and local boolean fields as filters:

Content:  
  Blog:  
  
    category:  
  
    post:  
      components:  
        listByCategory:  
          filters:  
            - category    # use the category module to filter with  
            - is_funny    # use the is_funny boolean field of the Post model  

Access the category filtered with

Customize the list query

The list query is generated and ready to use without any interventions.
By default, the list query:

• joins the i18n table if any
• filters on is_active field if any
• orders by selected field on widget dialog
• filters on selected module on widget dialog

Anyway, you can customize it to handle specific constraints or minimize SQL queries.

Choose the root alias

If you plan on customizing the query, you should first choose a root alias by passing it as the first argument of getListQuery():

$query = $this->getListQuery('post'); // you can choose any string you want

Add conditions

You can add where clauses as for any doctrine query.

$query = $this->getListQuery('post')
->addWhere('post.name LIKE ?', '%symfony%');  

Join I18n table

If the model is translatable, the i18n join is done automatically and does not require your intervention. The i18n alias is generated by adding 'Translation' to your root alias.

Add conditions on i18n table

In this example, the i18n alias is 'postTranslation', so we can add a clause on translated fields.

$query = $this->getListQuery('post')
->addWhere('postTranslation.description LIKE ?', '%symfony%');  

Add joins to reduce SQL queries

If the Post model has an Author relation, we can join it now to prevent the Author to be loaded for each Post.

$query = $this->getListQuery('post')
->leftJoin('post.Author author');  

If the Post model has a relation to DmMedia named 'Image', you can use the following shortcut:

$query = $this->getListQuery('post')
->withDmMedia('Image');  

Customize the list pager

The list pager is responsible for selecting and displaying a subset of the matched records, and render pagination links.
It's highly configurable. You can pass options:

• from the component

$this->postPager = $this->getPager($query);
$this->postPager->setOption('ajax', true);  

• from the template

$postPager->setOption('ajax', true);
$postPager->renderNavigationTop();  

• from apps/front/config/dm/services.yml

parameters:  
  front_pager_view.options:  
    ajax: true  

Options setted with the services.yml file will apply on all pagers.

Ajax links

You can decide that the pager no more reloads the page, but only the list widget with Ajax.
It's as simple as setting the 'ajax' option to true:

$pager->setOption('ajax', true);

Users which browser supports JavaScript will enjoy Ajax interactions.
The ajax pager gracefully degrades, so other users and search engine spiders can still use it normally.

First, Prev, Next, Last buttons

All these links can be customized.

$pager
->setOption('first', __('First page'))  // use a translated text for first button  
->setOption('prev', _media('prev.png')) // use an image for prev button  
->setOption('next', _tag('span.next'))     // use HTML for next button  
->setOption('last', false);             // disable last button  

Separator

If set, a separator li is added between all links. Defaults to false.

$pager->setOption('separator', '|');

Nb links

Specify the maximum number of page links. Defaults to 9.

$pager->setOption('nb_links', 3);

Will output a maximum of 3 page links.

Css classes

You can add CSS classes to the pager with the class option

$pager->setOption('class', 'my_pager');

Or with a CSS expression when rendering the pager links:

echo $postPager->renderNavigationTop('.my_pager_top');

Url parameters

You can add url parameters to the pagination links with the url_params option.

$pager->setOption('url_params', array('name' => value'));

This will add "&name=value" to all pagination links.

Current class

Class applied to the li tag of the current page. Defaults to current.

$pager->setOption('current_class', 'current_element');