entries

Display sets of entries in various ways.

{{ entries:listing }}

Fetches a list of entries from one or more folders and allows you to sort, filter, and group them in various ways.

Sample Usage

<ul>
    {{ entries:listing }}
        <li>
            <a href="{{ url }}">{{ title }}</a>
        </li>
    {{ /entries:listing }}
</ul>

Parameters

This tag accepts the following parameters:

folder

The folder from which to pull entries.

You can specify multiple folders by pipe delimiting them, or use use a wildcard * character at the end of the folder name will let you traverse through all subfolders.

Default: the current folder

{{ entries:listing folder="blog|news*" }}

taxonomy

Boolean setting to use the current URL to filter taxonomies automatically.

Default: false

{{ entries:listing taxonomy="true" }}

show_hidden

Boolean setting to show hidden files or not

Default: false

{{ entries:listing show_hidden="false" }}

since

If set, limits the date the earliest point in time from which date-based entries should be fetched. Uses PHP’s strtotime method allowing you to use plain English to specify the date.

Default: null

{{ entries:listing since="Last Sunday" }}
{{ entries:listing since="January 15th, 2013" }}
{{ entries:listing since="Yesterday" }}

until

If set, limits the date to the latest point in time from which date-based entries should be fetched. Uses PHP’s strtotime method allowing you to use plain English to specify the date.

{{ entries:listing until="Next Saturday" }}
{{ entries:listing until="Midnight" }}
{{ entries:listing until="Nov 25" }}

show_past

Boolean setting to enable date-based entries that have dates in the past.

Default: true

{{ entries:listing show_past="true" }}

show_future

Boolean setting to enable date-based entries that have dates in the future.

Default: false

{{ entries:listing show_future="true" }}

conditions

Conditions let you filter on and and every custom field in your entry data with the use a comma-separated string of key:value pairs.

{{ entries:listing conditions="author:jack" }}

You can also string together multiple OR conditions by separating them with commas:

conditions="author:jack,featured:yes"

You can perform “not” conditions by adding a ! mark:

conditions="author:!jack"

You can perform a series of OR checks by separating them with pipes (|). You can use the |option_list to easily take an array/list and format it appropriately.

{{ entries:listing conditions="type:beef|pork|bacon" }}

You can also perform a series of AND checks by separating them with ampersands (&). You can use the |required_list to easily take an array/list and format it appropriately.

{{ entries:listing conditions="type:beef&pork&bacon" }}

And finally, you can make those AND conditions be subtractive (AND NOT) with a ! mark:

{{ entries:listing conditions=”type:! lettuce&tomato&cucumber” }}

sort_by

Allows you to specify the field to sort the entries list on. In addition to any custom field, you can also sort by date, numeric, and random.

Default: date or numeric, depending on entry type.

{{ entries:listing sort_by="author" }}
{{ entries:listing sort_by="title" }}
{{ entries:listing sort_by="random" }}

sort_dir

Sets the direction all sorting should following, either ascending (asc) or descending (desc), by default this is dependant on sort_by. Numerically ordered entries will ascend and date-based will descent. It’s a good idea to always set this parameter.

{{ entries:listing sort_dir="desc" }}

sort added in v1.9

Allows you to sort the entries list on one or more fields. Accepts a comma-separated list of field_name asc|desc. Along with the ability to sort on multiple fields, this parameter lets to write even single field-sort orders in one parameter. (You can also use the keyword random to sort remaining items at random.)

{{ entries:listing sort="title desc" }}
{{ entries:listing sort="author desc, title asc" }}
{{ entries:listing sort="author desc, random" }}

limit

If set, limits the the maximum number of entries to display.

{{ entries:listing limit="10" }}

offset

If set, skips over the specified number of entries after sorting has been applied.

{{ entries:listing offset="1" }}

paginate

Boolean setting to respect any pagination rules from the URL or not. Generally used in conjunction with the {{ entries:pagination }} tag.

Default: false

{{ entries:listing paginate="true" }}

group_by_date

Allows loose grouping on any repeating date-based structure when sorting entries by date. Accepts a PHP date format string to specify the group type. For example, to group by month and date, use group_by_date="F Y".

Inside your tag pair, the grouped_date variable will be enabled and filled in with the entry’s date, formatted as specified, if different from the previous entry. The grouped_date will only be filled in when its value is different from the loop before, and otherwise it will be empty. This means that you can check for it with conditional statements and act accordingly.

{{ entries:listing folder="blog" group_by_date="F Y" }}
    {{ if grouped_date }}
        {{ if !first }}
            </ul>
        {{ endif }}

        <h3>{{ grouped_date }}</h3>
        <ul>
    {{ endif }}

    <li>
        <a href="{{ url }}">{{ title }}</a>
    </li>

    {{ if last }}
        </ul>
    {{ endif }}
{{ /entries:listing }}

Single Variables

In addition to your entry’s variables, the following single variables are available inside your entries:listing tag.

count

Current count of the entry being displayed.

date

Your entry’s date (if a date-based entry) formatted by your _date_format system setting. Accepts the format parameter.

datestamp

Your entry’s full datestamp Accepts the format parameter.

first

TRUE if the first entry in the list

grouped_date

Available if using the group by date feature

last

TRUE if the last entry in the list

permalink

The fully qualified URL of your current page. Example: http://example.com/blog/check-out-my-blog-yo

total_found

The total number of entries in the specified folder.

total_results

The total number of entries fetched by the entries:listing tag (as affected by limit, offset, conditions, etc).

url

The URL of the entry being output.

{{ entries:pagination }}

Displays information about paginating over a set of entries. This tag is designed to be used in conjunction with {{ entries:listing }} and should be given the same exact set of parameters.

Sample Usage

{{ entries:pagination }}
    {{ if previous_page }}
        <a href="{{ previous_page }}">Previous Page</a>
    {{ endif }}
    {{ if next_page }}
        <a href="{{ next_page }}">Next Page</a>
    {{ endif }}
{{ /entries:pagination }}

Parameters

The Paginate tag accepts all the same parameters as Listing, and should in fact mirror those used to display entries. Paginate does not automatically pick up the parameters of the primary Listing tag as there may be more than one rendering in a given template. This gives you the control.

Available Tags

Pagination also has access to all standard Tag Pair Helper Variables

{{ entries:map }} Deprecated in v1.7, use location:map_listing instead

Displays a map with matching entries as markers. Used in conjunction with the location add-on. Note that this tag will only work with entries containing location fields.

Sample Usage

{{ entries:map }}
    {{ pop_up }}
        <h2>{{ title }}</h2>
        {{ description }}
    {{ /pop_up }}
{{ /entries:map }}

{{ location:start_maps }}

Parameters

The Entries:Map tag accepts all the standard Listing parameters and the following additional parameters:

center_point required

Coordinates of the map’s center point in the format [latitude],[longitude].

{{ entries:map center_point="44.33,-68.21" }}

locate_with required

The name of the field containing location data.

{{ entries:map locate_with="where" }}

zoom

The starting zoom level of the map.

Default: 12

{{ entries:map zoom="8" }}

map_id

The value of the HTML id attribute used in map generation.

Default: a random string

{{ entries:map map_id="home-office" }}

clusters

Boolean on whether markers that are near each other should be clustered together at zoomed-out levels.

Default: true

{{ entries:map clusters="false" }}

{{ entries:next }} Added in v1.6.6

Displays the next entry that would show up in the listing.

Sample Usage

{{ entries:next folder="blog" }}
    {{ if !no_results }}
        Next up: <a href="{{ url }}">{{ title }}</a>
    {{ endif }}
{{ /entries:next }}

Parameters

This tag accepts all of the standard listing parameters and the following additional parameters:

current

The URL for the piece of content that is considered to be “current.” (This tag will display the next entry in the listing after the current one if one exists.)

Default: the current URL

wrap Added in v1.7

When set to true, this tag will wrap around to the other end of the list. In scenarios where there wouldn’t be a next entry, the first entry will be returned.

Default: false

Available Tags

All tags from the next piece of content are available, as well as one special tag:

{{ has_previous }}

Will return true if this tag’s current content within the list also has previous content. This can be helpful for printing extra stylizing features, such as only putting a hyphen between next and previous links if they both exist. As of v1.7, this tag will be determined based on what wrap is set to on the parent tag.

{{ entries:next folder="blog" }}
    {{ if !no_results }}
        {{ if has_previous }}
            <span class="delimiter">-</span>
        {{ endif }}

        Next up: <a href="{{ url }}">{{ title }</a>
    {{ endif }}
{{ /entries:next }}

{{ entries:previous }} Added in v1.6.6

Displays the next entry that would show up in the listing.

Sample Usage

{{ entries:previous folder="blog" }}
    {{ if !no_results }}
        Previously on Blog: <a href="{{ url }}">{{ title }}</a>
    {{ endif }}
{{ /entries:previous }}

Parameters

This tag accepts all of the standard listing parameters and the following additional parameters:

current

The URL for the piece of content that is considered to be “current.” (This tag will display the previous entry in the listing before the current one if one exists.)

Default: the current URL

wrap Added in v1.7

When set to true, this tag will wrap around to the other end of the list. In scenarios where there wouldn’t be a previous entry, the last entry will be returned.

Default: false

Available Tags

All tags from the next piece of content are available, as well as one special tag:

{{ has_next }}

Will return true if this tag’s current content within the list also has next content. This can be helpful for printing extra stylizing features, such as only putting a hyphen between next and previous links if they both exist. As of v1.7, this tag will be determined based on what wrap is set to on the parent tag.

{{ entries:previous folder="blog" }}
    {{ if !no_results }}
        Previously on Blog: <a href="{{ url }}">{{ title }</a>

        {{ if has_next }}
            <span class="delimiter">-</span>
        {{ endif }}
    {{ endif }}
{{ /entries:previous }}

{{ entries:meld }} Added in v1.7

Meld lets you combine all of the entries found with the given parameters and merge them into one value representative of the whole set.

Sample Usage

My average rating for all reviews is 
{{ entries:meld folder="reviews" field="rating" action="average" precision="1" }}.

Parameters

This tag accepts all of the standard listing parameters and the following additional parameters:

field

The field on which to meld.

Default: null

action

The action to perform to meld the content together, currently there are two allowed values:

• sum will add up all of the field values and return the total
• average will return the average of all the field values

Default: sum

precision

The number of decimal points to round the number to, although this really only applies to average, setting the precision (even to 0) will run the result through PHP’s number_format function, which will add locale-specific thousands-separators to the outcome.

Default: null