Collections


Collections

Collections in Tapestry are essentially arrays containing files, filtered by content type.

When Tapestry parses the project source directory it checks to see which content type each file matches before bucketing it into that content types collection.

Each content type has at least one collection, that being the collection of files attached to that content type, however if a content type has taxonomy configured then it will have additional collections, one for each taxonomy.

Collections in Tapestry are handled by the Collection class, which is at current an empty extension of Tapestries ArrayContainer.

How to request collections

As discussed in previous chapters, Collections are requested by including the use front matter property into your file. For example to request all posts you would do the following:

---
use:
    - blog
---

This will make available to your template all items within the blog collection as the variable: $blog_items. Each item of the $blog_items array will be an instance of the ViewFile class, and as such has all the content helpers attached to it.

For example:

<?php
foreach ($blog_items as $post) {
    echo '<p>' . $post->getData('title') .'</p>';
}

Taxonomy collections behave differently in that they have a key => value relationship; they are requested by the following syntax: {contentTypeName}_{taxonmyName}. For example:

---
use:
    - blog_categories
---

This will make available to your layout the variable $blog_categories containing an array with keys set to the taxonomy classifications and the values set as array's of the content type items belonging to each taxonomy classification.

This by itself may not be useful, however paired with the TaxonomyArchiveGenerator you can have Tapestry generate a page for each taxonomy classification with that classification's items injected.

Pagination

Pagination within Tapestry is handled by the PaginationGenerator generator, and is enabled on a file per file basis through the generator property within each files front matter.

For example:

---
use:
    - blog
generator:
    - PaginationGenerator
pagination:
    provider: blog
    perPage: 6
---

The above will instruct Tapestry to paginate the blog collection using the current page as the template with a maximum of six items per page. This will result in final output similar to the following:

build_local/
└── blog/
    ├── fish/
    |   ├── 3.html
    |   ├── 2.html
    |   └── index.html
    ├── mammals/
    |   └── index.html
    ├── birds/
    |   ├── 2.html
    |   └── index.html
    └── insects/
        ├── 4.html
        ├── 3.html
        ├── 2.html
        └── index.html

When a page is passed through the PaginationGenerator generator it has a $pagination variable set. This is an instance of the \Tapestry\Entities\Pagination class which contains many helpful methods for providing pagination output.


Pagination Helpers

Pagination is handled by Tapestry via the Pagination entity class, this class provides the following helpers methods:

getPages()

This method returns an array containing each of the pages generated by the pagination, each item within the returned array will be an instance of ViewFile.

getItems()

This method returns an array containing the items within the source collection for the current page, each item within the returned array will be an instance of ViewFile.

getNext()

This method will return an instance of ViewFile for the next page of the pagination, or if the current page is the last page it will return null.

getPrevious()

This method will return an instance of ViewFile for the previous page of the pagination, or if the current page is the first page it will return null.

isFirst()

This method will return a boolean value of whether the current page is the first in the pagination.

isLast()

This method will return a boolean value of whether the current page is the last in the pagination.


Pagination Example Usage

Below you can see an example usage Tapestries pagination, this could be written to a file in your _views folder and included within your paginated page via Plates $this->insert method.

<?php
/**
 * @var \Tapestry\Entities\Pagination $pagination
 * @var string $permalink
 */ ?>
<ul>
    <!-- If there is a previous page show previous link -->
    <?php if($previous = $pagination->getPrevious()){ ?>
        <li><a href="<?= $previous->getUrl() ?>">&larr;</a></li>
    <?php } ?>

    <!-- For each pages within the current pagination display a numbered link -->
    <?php foreach($pagination->getPages() as $key => $page) { ?>
        <!-- If the page is the current page do not link -->
        <?php if ($page->getUrl() === url($permalink)){ ?>
            <li><?= $key + 1 ?></li>
        <?php } else { ?>
            <li><a href="<?= $page->getUrl() ?>"><?= $key + 1 ?></a></li>
        <?php } ?>
    <?php } ?>

    <!-- If there is a next page show next link -->
    <?php if($next = $pagination->getNext()){ ?>
        <li><a href="<?= $next->getUrl() ?>">&rarr;</a></li>
    <?php } ?>
</ul>