Weblog Tag Variables

Weblog entries are shown using this basic tag pair. The pair may contain variables and HTML within them.

{exp:weblog:entries}

weblog content

{/exp:weblog:entries}

Basics

There are three general types of variables:

  1. Single Variables
  2. Variable Pairs
  3. Conditional Variables

Single Variables

A single variable is one in which the variable represents a single piece of data. Examples:

Single variables are the most common type.

Variable Pairs

Variable pairs are ones that have an opening and closing tag. Examples:

{date_heading}

<h1>{entry_date format="%Y %m %d"}</h1>

{/date_heading}

or

{categories}

<a href="{path=SITE_INDEX}">{category_name}</a><br />

{/categories}

The reason variable pairs have an opening and closing pair is because the information between the pairs can be shown or not shown if the criteria for each tag is met.

In the case of the "date_heading" pair, for example, it only appears at a certain interval that you set (hourly, daily, weekly, monthly, etc.). By using a pair of variables you can put HTML formating between them that only gets shown when the interval is met. Otherwise, the chunk is not displayed.

Conditional Variables

Conditional variables allow you to add scripting to your variables. Example:

{if username="joe"}

<h4>Hi Joe!</h4>

{/if}

This will be explained more below.

Single Variables

aol_im

{aol_im}

The author's AOL IM account name

author

{author}

The author's screen name, if it exists; otherwise, this variable will display the username.

author_id

{author_id}

The member ID number of the author

comment_path

{comment_path=weblog/comments}

The URL to the specified template. The ID number of the entry will be automatically added. For example, this:

<a href="{comment_path=weblog/comments}">comments</a>

Would be rendered like this:

<a href="http://www.example.com/index.php/weblog/comments/234/">comments</a>

comment_tb_total

{comment_tb_total}

The combined total number of both comments and trackbacks for a particular entry

comment_total

{comment_total}

The total number of comments for a particular entry

email

{email}

The author's raw email address

entry_id

{entry_id}

The ID number of the weblog entry

entry_id_path

{entry_id_path=weblog/archives}

The URL to the specified template. The ID number of the entry will be automatically added. For example, this:

<a href="{entry_id_path=weblog/archives}">my entry</a>

Would be rendered like this:

<a href="http://www.example.com/index.php/weblog/archives/234/">my entry</a>

icq

{icq}

The author's ICQ IM user identification number

interests

{interests}

The author's "interests" as entered in their profile

ip_address

{ip_address}

The IP address of the author when they posted the entry

location

{location}

The author's location as entered in their profile

msn_im

{msn_im}

The author's MSN IM account name

occupation

{occupation}

The author's occupation as entered in their profile

permalink

{permalink}

This variable defaults to site index with entry ID number:

http://www.example.com/235/

In addition, you can specify a template group/template and the entry ID will automatically be added:

{permalink="weblog/archives"}

Will render as:

http://www.example.com/weblog/archives/235/

profile_path

{profile_path=member/profile}

The URL to the author of the current entry. The ID number of the author will be automatically added. Use in a link:

<a href="{profile_path=member/profile}">{author}</a>

relative_url

{relative_url}

The URL stored in your Weblog URL setting under Weblog Management, with the domain information removed. For example, if your setting is http://www.example.com/index.php/weblog/index/ the variable will output /index.php/weblog/index/. Typically only used in the Atom feed Template.

relative_date

{relative_date}

The amount of time that has passed between when the entry was submitted and the current time. The output is diaplyed in the format 1 day, 3 hours, 45 minutes. This variable is useful for displaying something such as "This entry was posted 1 day, 3 hours, 45 minutes ago."

screen_name

{screen_name}

The author's screen name, if it exists. This variable will not return anything if the author does not have a screen name defined.

status

{status}

The status of the entry (open, closed, etc.)

switch=

{switch}

This variable permits you to alternate between any two values as the entries are displayed. The values are set with the switch= parameter. For instance, switch="option_one|option_two". The first entry will use "option_one", the second will use "option_two", the third "option_one", and so on.

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

title

{title}

The title of the entry

title_permalink

{title_permalink}

This variable uses the "url title" as the link. It defaults to the site index with the "url title":

http://www.example.com/my_ugly_boyfriend/

In addition, you can specify a specific template group/template and the "url title" will automatically be added:

{title_permalink="weblog/archives"}

Will render as:

http://www.example.com/weblog/archives/my_ugly_boyfriend/

Note: When creating a new entry, if you don't supply the "url title" then it will be automatically created from the actual entry title. Spaces are turned into underscores and quotes are removed. For example, "Joe's night out" becomes "joes_night_out".

trackback_path

{trackback_path=weblog/comments}

The URL to the specified template. The ID number of the entry will be automatically added. Use in a link:

<a href="{trackback_path=weblog/comments}">trackback</a>

trackback_total

{trackback_total}

The total number of trackbacks for a particular entry

trimmed_url

{trimmed_url}

The domain name for your site, trimmed of any subdomains. For instance, www.example.com becomes example.com. Typically only used in the Atom feed Template.

url

{url}

The author's raw URL, if it exists

url_or_email

{url_or_email}

The author's URL if it exists, otherwise the raw email address

url_or_email_as_author

{url_or_email_as_author}

A hyperlink to the author's URL if it exists, otherwise it will be an email link for the author's email address. The text of the link will be the author's screenname if it exists, otherwise it will be the username.

url_or_email_as_link

{url_or_email_as_link}

This is similar to the above variable. The difference is that the text for the link will be either the URL or the email address.

url_title

{url_title}

The human readable title used in the URL as a permalink

url_title_path

{url_title_path=weblog/archives}

The URL to the specified template. The "url title" of the entry will be automatically added. For example, this:

<a href="{url_title_path=weblog/archives}">permalink</a>

Would be rendered like this:

<a href="http://www.example.com/index.php/weblog/archives/ice_cream/">permalink</a>

username

{username}

The author's username

weblog

{weblog}

The name of the weblog to which the currently displayed entry is assigned

weblog_id

{weblog_id}

The ID number of the actual weblog (not the entry)

yahoo_im

{yahoo_im}

The author's Yahoo IM account name

Custom Entry Fields

All custom fields assigned to a weblog can be accessed using the "short name" of the field:

{body}
{summary}
{extended}
etc..

These are totally dynamic in that any field you create for your weblog will automatically be available by its "short name" as a variable.

Custom Member Fields

All custom member profile fields can be accessed using the "short name" of the field:

{age}
{gender}
{zodiac}
etc..

These are totally dynamic in that any profile field you create for your members will automatically be available by its "short name" as a variable.

Single Variable Dates

Several date variables are available for use. As with other date variables, these require the "format" parameter in order to define how the date should be displayed. See the date variable formatting page for more information.

entry_date

{entry_date format="%Y %m %d"}

The date the entry was submitted

expiration_date

{expiration_date format="%Y %m %d"}

The expiration date of the entry

edit_date

{edit_date format="%Y %m %d"}

The date on which the entry was last edited

gmt_entry_date

{gmt_entry_date format="%Y %m %d"}

The date the entry was submitted in GMT. This variable is not localized for each user's date settings.

gmt_edit_date

{gmt_edit_date format="%Y %m %d"}

The date on which the entry was last edited in GMT. This variable is not localized for each user's date settings.

recent_comment_date

{recent_comment_date format="%Y %m %d"}

The date of the most recent comment associated with the entry

Variable Pairs

date_heading

The date heading can be used to show a heading at certain intervals. The interval can be set to show hourly, daily, weekly, monthly, and yearly.

{date_heading}

<h1>{entry_date format="%Y %m %d"}</h1>

{/date_heading}

The opening {date_heading} tag has an optional "display" parameter used to set the display interval:

{date_heading display="daily"}

Choices for the "display" parameter are:

If no parameter is specified it will default to "daily".

Cool Feature: You can use as many date_headers as you want in the same tag. There is a bit of a performance hit, however, since date parsing is the most processor intensive. Read the caching section.

categories

Categories are unique in that they are a "looping pair". Since you can have multiple categories per entry, we need a mechanism to show as many categories as exist for each entry. Here's the base syntax:

{categories}

<a href="{path=weblog/index}">{category_name}</a>

{/categories}

The entire chunk within the tag pair is repeated for as many categories as you have for each entry. For that reason you may need to add HTML formatting between the tags. For example:

{categories}

{category_name}<br />

{/categories}

If your entry has three categories — News, Sports, and Politics — the above code will render this output:

News<br />
Sports<br />
Politics<br />

Whatever is between the opening and closing variables gets looped for as many categories as you have assigned to your entry. If you want to put a space between the categories you'll do this:

{categories}

{category_name}&nbsp;

{/categories}

By default, the category is shown as pure text. If you want it to be a link you'll use the {path=template_group/template} variable in the {categories} variable pair, like this:

{categories}

<a href="{path=weblog/index}">{category_name}</a>

{/categories}

If you want the category links to point to your site index instead of a particular template group/template you can use SITE_INDEX instead:

{categories}

<a href="{path=SITE_INDEX}">{category_name}</a>

{/categories}

Note: "weblog/categories" indicates to which template group/template you want the link to point. It is not a special command in and of itself.

A second optional parameter allows "backspacing":

{categories backspace="4"}

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

News<br />
Sports<br />
Politics<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:

{categories backspace="6"}

{category_name}<br />

{/categories}

Finally, you may use the {category_image} variable to display the contents of the Category Image field in the Control Panel category setup. For instance:

{categories backspace="6"}

<img src="{category_image}" width="25" height="15" alt="" /> <a href="{path=SITE_INDEX}">{category_name}</a><br />

{/categories}

Conditional Variables

Conditional variables allow you to add scripting to your regular Single Variables (see above) in order to show data if certain criteria that you define are met. For more information about conditional logic in ExpressionEngine, please refer to the Global Conditionals.

Note: The left side of the condition must always be the name of a field (title, body, summary, username, screen_name, entry_date, etc.). The right side must be the condition you are testing for.

For example, to test for the "summary field" being not empty, you would do this:

{if summary != ""}

The summary is not empty!

{/if}

An alternate, shorthand syntax can accomplish the same thing:

{if summary}

The summary is not empty!

{/if}

If only the variable name is in the conditional statement it tests for "not empty".

allow_comments

{if allow_comments}
content
{/if}

This special conditional lets you conditionally display content if the current entry is set to allow comments.

{if allow_comments}

({comment_total}) <a href="{comment_path="weblog/comments"}">Comments</a> •

{/if}

allow_trackbacks

{if allow_trackbacks}
content
{/if}

This special conditional lets you conditionally display content if the current entry is set to allow trackbacks.

{if allow_trackbacks}

({trackback_total}) <a href="{trackback_path="weblog/trackbacks"}">Trackbacks</a> •

{/if}

Examples:

To test for the member group being "4":

{if group_id == "4"}

Hey {username}, you are in group 4

{/if}

To test for 10 or more comments:

{if comment_total >= "10"}

Lookout! Hot topic!!

{/if}

You can use any available variable as part of a conditional.

Multiple Conditions

You can nest conditional statements in order to create more complicated restrictions.

{if summary != ""}
{if username =="fred"}

Hey Fred! Look at this summary.

{/if}
{/if}

or

{if comment_total == 0}
{if trackback_total == 0}

No one has posted yet! Come on guys!

{/if}
{/if}

Please remember that we use the PHP convention of double equals signs for equivalence:

{if comment_total == 10}

Doing the following is not allowed: {if comment_total = 10}

Special Conditionals

You may also, of course, use the global conditional variables to test for logged in/out status. If you want to show something only to users who are logged in:

{if logged_in}

stuff...

{/if}

Or not logged in:

{if logged_out}

stuff...

{/if}