Entry Display

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:

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')" 

Extra Loop Variables

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

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.

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.

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.

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" }}

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 }}