Collection

Collections are simply a group of items. While each item tends to be unique, items all share the same data structure. Collections are very powerful and they can be retrieved from different sources: pages, filesystem, database, or webservice.

Table of Contents

• Frontmatter
• Model
  • Identifier
  • Query
• State
  • Sorting
  • Paginating
  • Searching
• The collection() function
• The state() function

Frontmatter

A collection is defined in the frontmatter of the page.

collection: 
   model: identifier[?query]
   state:
        limit: int 
        offset: int
        order: desc/descending/asc/ascending/shuffle, asc
        sort: string, order

• Model: The model string is an URL of the format identifier[?query]. The identifier defines the model name or for custom models the object identifier. The query is optional, not every collection supports it.

• State: The state is an associative property array that allows you to filter the collection to retrieve a specific subset of the items.

Model

The model is an URL of the format identifier[?query]. The query is optional and offers support for the URI template standard. URI templates add a special syntax to replace template place holders with state variables.

Identifier

Out-of-the-box Pages supports different collections. It's also possible to create your own custom collections.

1. Pages (default) - a collection will be retrieved from within the pages folder. If a model is not specified in the frontmatter, the collection is automatically pages.
2. Filesystem - a collection will be created from one or more data files in the filesystem.
3. Database - a collection will be created from any database table.
4. Web Service - a collection will be created from any URL as long as the URL returns structured data.

Query

The model query is optional and makes use of URI template standard. Query template place holders are replaced with state variables to generate the model URL.

collection:
   model: collection?{?a,b}
   state:
     a: hi
     b: there

The resulting collection model would be collection?a=hi&b=there. URI templates aren't limited to just simple variable replacements; URI templates can provide an enormous amount of flexibility when creating request URIs.

collection:
   model: webservice?url=http://example.com{+path}{/segments*}{?query,data*}
   state:
     path: /foo/bar
     segments: ['one', 'two']
     query:  test
     data: 
        more: value

The resulting collection model would be webservice?url=http://example.com/foo/bar/one/two?query=test&more=value.

Note: URI template expressions need to be enclosed in an opening and closing brace (e.g. {var}). You can learn about all of the different features of URI templates by reading the URI templates RFC

State

The state is an associative property array that allows you to filter the collection to retrieve a specific subset of the items.

The following state properties are available for each collection, some collections define additional state properties that you can use to filter the collection.

• limit: the pagination limit
• offset: the pagination offset
• sort: the sorting of the pages, receives the page property to sort on.
• order: the order of pages [asc|desc|shuffle]
• search: search the collection for an item(s) with a specific value

Sorting

A collection can be ordered using the sort and order states. You can use any page property to sort on, including custom properties.

Example:

collection('pages', ['sort' => 'title' , 'order' => 'desc']);

It's also possible to retrieve the collection in random order by setting the order to shuffle.

Paginating

A collection can be paginated using the limit and offset states. Offset defines the item to start from and limit the max amount of items to retrieve from the collection.

By default, limit will be set to the List limit that you have configured in the Joomla global configuration.

Example:

collection('pages', ['offset' => 10 , 'limit' => 10]);

See also: Templates > Helpers > Pagination

Searching

A collection can be searched using the search state. The state value needs to be formatted as follows: [column]:[value] You can use any page property to search on, including custom properties.

Example:

collection('pages', ['search' => 'title:foo']);

The collection() function

If you want to retrieve a collection, you can use the collection($model, $state) function and it will return a traversable object.

The $state function parameter should be a php array that defines the specific state to be used to filter the collection.

Example:

collection('pages', ['limit' => 3, 'order' => 'shuffle');

You can use the collection() function without any arguments to retrieve the active collection, defined through the active page frontmatter, from any template or layout.

See also: Templates > Functions

The state() function

The state() function allow you to access the active collection state in templates. It returns a KModelStateInterface object.

Example:

state();

See also: Templates > Functions