Weblog Entries Tag Parameters

Weblog entries are shown using this basic tag pair:

{exp:weblog:entries}

weblog content

{/exp:weblog:entries}

Parameters

A variety of parameters can be added to affect what is displayed by the weblog tag. Here is a simple example of the weblog tag with a couple of parameters:

{exp:weblog:entries weblog="news" limit="15"}

weblog content

{/exp:weblog:entries}

backspace=

backspace="6"

Backspacing removes characters from the last iteration of the weblog entries loop. For example, if you put a <br /> tag between each entry you'll have this layout:

Entry 1 title<br />
Entry 2 title<br />
Entry 3 title<br />

You might, however, not want the <br /> tag after the final item. By adding backspacing you can remove it. Simply count the number of characters and spaces in the item you want to remove and add it to the tag. A <br /> tag has 6 characters, so you would do this:

{exp:weblog:entries backspace="6"}

{title}<br />

{/exp:weblog:entries}

That will produce code like this:

Entry 1 title<br />
Entry 2 title<br />
Entry 3 title

Note:
The "backspace" parameter will only work if you have either the rdf="off" parameter specified or you have "Add Trackback Auto-discovery code to your pages?" setting turned off under Weblog Management.

cache=, refresh=

cache="yes" refresh="60"

This parameter enables tag caching. Refresh is the number of minutes between cache refreshes.

cat_limit=

cat_limit="30"

This parameter lets you set a different limit for the category display than the regular display. For example, let's say you normally only want 10 entries on your main weblog page, but you want 100 entries shown when viewing a specific category. For that, you could do this:

{exp:weblog:entries limit="10" cat_limit="100"}

category=

category="2"

Categories are specified by ID number (the ID number of each category is displayed in the Control Panel). The reason we use the ID is because categories can be called anything (with spaces, quotes, etc.), and also renamed. It would be much more difficult to have to update the tag parameters every time you updated a category name.

And as with some of the other parameters, you can stack categories:

category="2|45|4|9"

Or use "not" to exclude categories

category="not 4|5|7"

display_by=

display_by="month" display_by="day"

There are two optional "display types" that let you limit the display of your entries. If you do not use these parameters the default grouping is by "number".

These parameters interact with the "limit" parameter to tailor the number of entries per page. For example, if you want to show only the current month you'll do this:

display_by="month" limit="1"

At 12 AM on the first day of the month the previous month will no longer be visible. If you want to show three months you'll do this:

display_by="month" limit="3"

If you want to show only the current day you'll do this:

display_by="day" limit="1"

If you want to show 14 days you'll do this:

display_by="day" limit="14"

These are all optional. If you do not use this parameter your entries will be limited by number. In other words:

limit="20"

Will show 20 entries.

dynamic=

dynamic="off"

The weblog display engine sets some parameters dynamically, based on what is in the URL. There are times, however, where you do not want the parameters affected by what the URL contains. To override the dynamic nature of the weblog tag, use dynamic="off".

This is often useful if you want to list entries in a "sidebar" on your site and have them always be the same ones regardless of which page on your site you visit (main page, archives, comments, etc.). By setting dynamic="off" you will ensure that the list is not affected by anything passed in the URL.

entry_id=

entry_id="147"

You can hard code the weblog tag to show a specific weblog entry.

group_id=

group_id="4"

You can decide from which Member Groups (by specifying the group ID) you wish entries to be shown. If you choose "4", then only entries created by members of the Member Group with the ID of 4 will be shown. You can choose multiple member groups using a pipe:

group_id="2|3|4"

Or exclude groups using "not"

group_id="not 2|3|4"

limit=

limit="12"

This parameter limits the number of entries on any given page.

offset=

offset="1"

This parameter offsets the display by X number of entries. For example, if you want to show all entries except the three latest ones, you would do this:

offset="3"

orderby=

orderby="date"

The "order" parameter sets the display order of the entries. Setting options for this parameter include:

In addition you can order by a custom field. Use the "short_name" of the field:

orderby="name_of_field"

paginate=

paginate="top" paginate="bottom" paginate="both"

This parameter is for use with entry pagination and determines where the pagination code will appear for your weblog entries:

  1. top: The navigation text and links will appear above your list of entries.
  2. bottom: The navigation text and links will appear below your list of entries.
  3. both: The navigation text and links will appear both above and below your list of entries.

If no parameter is specified, the navigation block will default to the "bottom" behaviour.

paginate_type=

paginate_type="field"

This tells ExpressionEngine to function in "pagination" mode for your weblog entry fields so that you can automatically have an entry span multiple pages. See the Spanning a Weblog Entry Across Multiple Pages page.

rdf=

rdf="off" rdf="on"

The Trackback Autodiscovery RDF code can be manually set for any particular weblog entry listing. This is useful when used on the RSS pages if the "global" setting in Weblog Management is turned on.

sort=

sort="asc" sort="desc"

The sort order can be ascending or descending. The order will default to "descending" if nothing is specified.

status=

status="open"

The weblog status to which you would like to restrict display. You can choose multiple statuses using a pipe:

status="draft|reviewed|published"

Or exclude statuses using "not"

status="not submitted|processing|closed"

sticky=

sticky="off"

By default, sticky topics always remain at the top of the page. You can manually turn off stickies by using the above parameter.

switch=

switch="option_one|option_two"

This parameter permits you to alternate between any two values as the entries are displayed. The first entry will use "option_one", the second will use "option_two", the third "option_one", and so on. This parameter sets the values and the {switch} variable is used to display them

The most straightforward use for this would be to alternate colors. It could be used like so:

{exp:weblog:entries switch="one|two"}
<div class="{switch}">
<h1>{title}</h1>
{body}
</div>
{/exp:weblog:entries}

The entries would then alternate between <div class="one"> and <div class="two">.

username=

username="petunia"

This parameter limits the query by username. You can use the pipe character to query by multiple usernames:

username="tom|dick|harry"

Or you can add "not" to exclude usernames:

username="not tom|dick|harry|fred" You can also use the constant "CURRENT_USER" to show entries from only the currently logged in user.

username="CURRENT_USER"

This allow each logged-in user to get only their entries. Users who are not logged in won't see anything. Alternatively, you can use the constant "NOT_CURRENT_USER" to show entries except from the currently logged in user.

username="NOT_CURRENT_USER"

weblog=

weblog="which"

From which weblog to show the entries (will show all weblogs if no weblog is specified). Additionally, you can use the pipe character to separate multiple weblogs:

weblog="weblog1|weblog2|weblog3"

Or you can add the word "not" (with a space after it) to exclude weblogs:

weblog="not weblog1|weblog2|weblog3"

year=, month=, day=

year="2003" month="12" day="23"

You can limit queries by year, month, or day. For example, to show all of year 2002 you'll use only:

year="2002"

To show only the month of December in 2003 you'll do this:

year="2003" month="12"

Note: Don't combine these parameters with the "display_by" parameter discussed previously, as these take precedence over that parameter. In addition, the three parameters must be applied "in order", meaning that you must specify the year if you specify the month and you must specify both month and year to use day.

Examples

Here are a few examples of the weblog tag using multiple parameters at the same time.

{exp:weblog:entries weblog="news|sports" limit="15"}

weblog content

{/exp:weblog:entries}

The above tag would display the first 15 entries from the "news" and "sports" weblogs.

{exp:weblog:entries limit="10" orderby="most_recent_comment" sort="desc"}

weblog content

{/exp:weblog:entries}

The above tag would display the 10 entries with the most recent comments.

{exp:weblog:entries group_id="not 3|5" year="2003" weblog="politics" category="17"}

weblog content

{/exp:weblog:entries}

The above tag would display entries from 2003 for the "politics" weblog if they belong to the category with the ID "17". The entries will display for all members that are not part of member groups 3 or 5.