PyroCMS

The Loop Cycle

The most basic and common way of interacting with PyroStreams data is looping through it using the cycle plugin function. Here's a very simple example where we display five entries from a stream called "bands":

{{ streams:cycle stream="bands" limit="5" }}

    <h2>{{ name }}</h2>

{{ /streams:cycle }}

Inside the tags, you have access to all of the fields you set up when you created your streams. There are a lot of options to customize what entries are returned, which are outlined below.

Short Syntax

Instead of specifying a stream with the stream="stream_slug" parameter, you can use it in the place of "cycle". For instance, if the tag code below is functionally equivalent to our first example above:

{{ streams:bands limit="5" }}

    <h2>{{ name }}</h2>

{{ /streams:bands }}

There is no real advantage to using the short syntax, except for saving some paramter space, which may come in handy if you have a lot of parameters.

Filtering by Date

The cycle function contains a number of functions for filtering by date. For instance, you can specify a year, month, and day. Each of these should be a numerical value:

{{ streams:events year="2013" month="01" day="14" }}

You can also restrict the entries shown by telling the cycle plugin to show or not show entries before or after the current date by using show_upcoming and show_past. Both of these are set to yes by default, so if you wanted to display a list of events that are upcoming you could do it like this:

{{ streams:events show_past="no" }}

The parameters above need a field to filter the dates by, and this is the created_by column by default. However, if you have another field that you want to use instead, you can specify that with date_by:

{{ streams:events date_by="event_start" year="2013" month="01" day="14" }}

Parameter Reference

The following are basic parameters that restrict or modify the returned data in some way:

Parameter Default Description
stream   Slug of the stream you want to cycle through.
namespace streams Streams works off the core streams namespace, but you can change this to use the cycle function with other namespaced streams.
limit   Number to limit the results to.
offset   Number to offset the results by.
order_by created Specify a field to order by.
sort desc Specify to the sort order. Ascending (asc), descending (desc), or random.
date_by created The field to run date parameters through.
year   Restrict results to a year (in the date_by field).
month   Restrict results to a month (in the date_by field).
day   Restrict results to a day (in the date_by field).
show_upcoming yes Choose yes or no to show entries dated in the future (in the date_by field).
show_past yes Choose yes or no to show entries dated in the past (in the date_by field).
where   Allows you to restrict results. See The Where Parameter for more information.
exclude   IDs of entries to exclude separated by a pipe character (|).
exclude_called no Set to 'yes' to limit entries to ones not already displayed on the same page. Ex: An image gallery with a featured image. Use exclude_called="yes" on the rest of the images to not display the currently selected image..
include   Value to include in a where= clause. Used with include_by to filter by a single data point.
include_by id The field to use when using the include parameter.
disable Allows you to disable fields and their formatting. You can specify multiple fields by separating them with a pipe character (|).
no_results No results Message that displays when no results are found.
partial Allows separation of results into separate segments. See Separating Results into Sets for more information.

The Where Parameter

If you need to restrict your results, a handy way to do that is with the where parameter.

where="`field_slug`='value'"

where="`one_field_slug`>='value' AND `another_field_slug`!='another_value'"

where="`one_field_slug`>='value' AND (`another_field_slug`!='another_value' OR `yet_another_field_slug`='yet_another_value')" 

Note: The where clause is directly mapped to the where clause in MySQL, so you are limited in the values that you can restrict by. For instance, if you have a Choice dropdown field with a key and value, the key is stored in the database. So, if you want to restrict by that field, you need to restrict by the choice key and not the value.

Extra Loop Variables

Aside from the field tags that are returned when you loop through entries, you can also access some automatically generated tags.

Tag Description
{{ count }} A numerical auto increment of the posts returned. This is different than the id and resets on different pages of pagination. Starts at 1.
{{ odd_even }} Returns 'odd' or 'even' alternately, starting with odd.
{{ last }} Returns '1' if the item is the last in the returned set, or '0' if it is not.

Restrict by User

PyroStreams gives you the option of restricting a to a specific user. Each stream automatically tracks which user created an entry using the created_by field that is automatically added. Turning on user restricting means that only the entries created by the specified user will be returned.

Parameter Default Description
restrict_user no Setting this to a value will enable user restricting. Setting it to current will use the current logged in user. This parameter can also take a user id and a username to restrict to.

Note: If no user is logged in or the user id/username is invalid, user restricting is subsequently turned off.

Nested Variables

Some variables return an array of values, such as a variable from a related field. Each of these values can be accessed with a colon between the field name and the sub variable you want to access.

For example, if you have a user field, named 'person', you can access their id like this:

{{ person:id }}

Variables from relationships can be accessed in the same way:

 {{ band:name }}

And sub variables within relationships can be accessed this way:

 {{ band:email:email_link }}

Pagination

Very often you'll want to paginate large data sets. PyroStreams allows you to do this quickly and easily. The following parameters are used in the cycle function for creating pagination.

Parameter Default Description
paginate no Setting this to yes will enable pagination.
pag_segment 2 The URI segment to take the pagination offset from.

Note: Turning on pagination will automatically set the limit to 25. You can override this by setting a limit parameter.

Pagination URI Segments

Pagination works by adding a page number onto the end of the URI of your page. So if you have a URI like this:

/products/list

Pagination will add a number like this:

 /products/list/10

For this reason, you need to go into the page that you have streams pagination on, and uncheck Require an exact URI match? under the Options tab. This means that when accessing a page like /products/list/10, it will not look for a page with a slug of '10' under 'lists', but will ignore that segment.

Controlling the Pagination Markup

You can control the markup of the pagination with the following parameters. These are taken directly from the CodeIgniter pagination markup parameters.

Parameter Default Description
full_tag_open <p> The opening tag placed on the left side of the entire result.
full_tag_close </p> The closing tag placed on the right side of the entire result.
first_link First The text you would like shown in the "first" link on the left. If you do not want this link rendered, you can set its value to FALSE.
first_tag_open <div> The opening tag for the "first" link.
first_tag_close </div> The closing tag for the "first" link.
last_link Last The text you would like shown in the "last" link on the right. If you do not want this link rendered, you can set its value to FALSE.
last_tag_open <div> The opening tag for the "last" link.
last_tag_close </div> The closing tag for the "last" link.
next_link Next The text you would like shown in the "next" page link. If you do not want this link rendered, you can set its value to FALSE.
next_tag_open <div> The opening tag for the "next" link.
next_tag_close </div> The closing tag for the "next" link.
prev_link &lt; The text you would like shown in the "next" page link. If you do not want this link rendered, you can set its value to FALSE.
prev_tag_open <div> The opening tag for the "previous" link.
prev_tag_close </div> The closing tag for the "previous" link.
cur_tag_open <span> The opening tag for the "current" link.
cur_tag_close </span> The closing tag for the "current" link.
num_tag_open <div> The opening tag for the "digit" link.
num_tag_close </div> The closing tag for the "digit" link.

Pagination Example

{{ streams:cycle stream="bands" limit="5" paginate="yes" pag_segment="2" limit="10" }}
    <p>{{ total }} entries returned.</p>
    {{ entries }}
      <h2>{{ name }}</h2>
    {{ /entries }}
    {{ pagination }}
{{ /streams:cycle }}

Switching Namespaces

Streams namespaces (not to be confused with PHP namespaces) allow modules to have their own sets of streams without worrying about naming conflicts. For instance, the Streams module can have a streams with products as the slug, and a store module can have a stream with products as the slug as well since each module has a difference namespace.

The default namespace for the streams module is streams, so you don't have to set that using the streams plugin. However, you can switch streams by adding a namespace parameter. This allows you to display data from streams from anywhere in the system, as long as you know the namespace.

For example if you wanted to display blog posts using the streams plugin (although there is a plugin for that), you could do this:

{{ streams:cycle stream="blog" namespace="blogs" }}

It's important to remember, however, that many modules use streams in unique ways, so using the streams plugin may only get you so far. For example, in the Pages module, the pages table contains page data like the title, slug, parent page, etc., and then each page has the ID of the stream entry it is associated with. So, you can only get the page entry data - and not the pages table data - only the entries of the associated page type stream.

Your best bet is to use the respective plugins for each module, which often will contain extra data. For example, you can use the pages plugin to properly display lists of pages and their metadata.

Separating Results into Sets

Sometimes you don't want to show all of your stream entry results at the same time. The most common use case for this is separating results into equal columns.

PyroStreams has a built-in feature to take care of this, and can be called using the partial parameter. The partial parameter will take input like this:

partial="1of3"

This will separate your results into three segments and only return the first. So, if you wanted to separate your results into two columns, you could do this:

{{ streams:cycle stream="sample" partial="1of2" }}
{{ /streams:cycle }}
{{ streams:cycle stream="sample" partial="2of2" }} {{ /streams:cycle }}
Note: Other parameters do not affect the partial parameter, so if you have a limit/offset, the partial feature will take its segment from the entries already filtered by the limit/offset.