Collections

Group pages into a pretty, well ordered list.

What Are Collections?

A collection is a way to logically group pages that use the same template together and display them as a list. For example, you could use a collection to build a blog just by filtering out certain pages by URL. Collections are designed using the grid editor and they support multiple pages and ajax pagination.


Example

As mentioned above, you can build a blog with collections. In fact, PageRoost ships with a "Blog" template so you can do just that. To create a blog with a collection, follow the instructions below.

  1. Create a new collection using the instructions in the "Creating A Collection" section.
    1. Choose "Blog Post" in the "Template" field.
    2. Choose "Created" in the "Sort On" field.
    3. Choose "Descending" in the "Sort Order" field.
    4. Choose "Next/Previous Links" in the "Show Pagination" option.
    5. Choose "In place of existing content" in the "Results Appear" field.
    6. Add a filter for the "URL" field.
      1. Filter On - URL
      2. Filter Operator - Starts With
      3. Filter Value - blog/
  2. Add a row to the collection and drag the "Post Title" and "Post Content" fields into the row.
  3. Access the field options menu for "Post Title" by clicking the gear icon - - on the field. Click the "Format Options" link to display the field format options.
    1. Choose "H4" for the "Header Type" field.
    2. Choose "Yes" for the "Link To Page" field.
    3. Click the "Save" button.
  4. Access the field format options dialog for the "Page Content" field.
    1. Choose "Yes" for the "Truncate Text" field.
    2. Choose "Yes" for the "Read More" link.
    3. Enter the number of characters to truncate the text to in the "Length" field.
    4. Optionally, set the title of the "Read More" link.
    5. Click the "Save" button.
  5. Click the "Save Changes" button to save the collection.
  6. Create or edit a template and add a collection to the layout. Please refer to the grid editor and the templates section for more information on this step.
  7. Create a page based on the template you made in step 6 and choose the collection you made in step 1.
  8. Save the page.
    1. Optionally, edit the collection created in step 1 and access the properties by clicking the gears button - - above the field list and select the page you created in step 7 as the "Results Appear" value, click the "Save" button, and then the "Save Changes" button.
  9. Create a page based on the "Blog Post" template.
    1. The URL should start with "blog/" because the collection is only going to include pages with a URL with the same format. So, for example "blog/my-first-blog-post"
    2. Enter a post title and content.
    3. Save the page.
  10. Go to the page you created in step 8. You should see a blog post with:
    1. A title that links to the full blog post.
    2. A truncated version of the post content with a "Read More" link that links to the full blog post.

Creating A Collection

Click on the "Content" menu item and choose the "Collections" option.

  • Click on the "Add Collection" button
  • Enter a name for the collection (i.e. Blog Posts)
  • Complete the form using the table below for reference
  • After you configure the collection, the next page you see will be a grid editor with a list of fields from the selected template.
  • Create the collection layout using the field list and the grid editor controls.
Template
The collection will only display pages that use this template.
Limit
The number of items to display. A value of "0" means that there is no limit to the number of items the collection may display.
Setting this to a number greater than zero would be more suitable for a large collection of content, such as blog posts.
Sort On
Allows you to determine how the items in the collection are sorted.
  • Page Fields - These fields will never change because every page uses them.
  • Template Fields - These fields will vary depending on the value of the "Template" field.
Sort Order
If you select a sorting option, you may also select a sorting direction.
Show Pagination
Determines whether the collection should display pagination options if the number of items in the collection exceeds the number in the "Limit" field. Pagination allows users to view all of the pages a collection includes by clicking on page numbers or "Next" and "Previous" links.
  • No Pagination - Does not display any pagination.
  • Page Numbers - Displays a list of numbers a user can click on.
  • Next/Previous Links - Displays "Next" and "Previous" links.
  • Page Numbers and Next/Previous Links - Exactly what it sounds like.
Results Appear
When pagination is present, this setting determines how it acts.
  • In place of existing content - The pagination will use AJAX to fetch and display subsequent pages.
  • Item in the "On Page" group - The pagination will direct the user to the selected page. The collection must exist on the page you have selected.
Filters
Filters allow you to control which pages are included in a collection. For example, you may want to filter out pages that have a URL that starts with "blog/". You can add as many filters as you want and you can reorder them by dragging the handle to the left of the "Filter On" field.
  • Filter On (first field) - Choose a field you would like to filter. This dropdown will have the same options as the "Sort On" field and will change based on the value of the "Template" field.
  • Filter Operator (second field) - Choose how this filter works. The value of this field will determine how the "Filter Value" is matched against the value found in the "Filter On" field.
  • Filter Value (third field) - Enter a value to use when filtering. The value of this field will be used with the "Filter Operator" to determine whether or not a page gets included in a collection.

Editing A Collection

To edit a collection, go to the "Collections" page, and click on the name of the collection you want to edit, or click on the pencil icon to the right of the name. Use everything you learned above.


Using A Collection

To use a collection, add a collection field to a template and save the template. You can then choose a collection to display when you are editing a page or, you can lock the field on the template and choose a default collection (in the "Field Options" for the field on the template).