Template Parsing

Using Osmek's template parsing can be very powerful, allowing you to utilize Osmek to do most of your data processing. Templates allow you to request data formated how you need it, and keywords allow you to request values in different formats, like the format of a date, or the size of an image.

Templates

When specifying the response format, if you define a template parameter, the value of that parameter will be parsed with the response data from Osmek.

An example template:

<h1>[title]</h1>
<span class="date">[date *m/*d/*Y]</span>
<div class="body">[description]</div>

The same template parsed by Osmek:

<h1>Lorem Ipsum Dolor</h1>
<span class="date">12/22/2009</span>
<div class="body"><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque felis tellus, tincidunt id vulputate ac, iaculis sed velit.</p></div>

Keywords

A keyword is a word in a template that is meant to be replaced with a value. Keywords in templates are wrapped in hard brackets. Example: [keyword]. Keywords may also be used as the values listed in the vars parameter as described in the Response Formats section.

Keyword Actions

A keyword can consist of multiple parts. The first part will always be the value you want, for example title, or date. The second part can be an action or a formatting value.

For example you can format a date by using date *m/*d/*Y,
or request a specific image size by using photo 100x100,
or shorten a description to a specific link by using description truncate 400.

Keywords can be broken into 2 or more parts in the following format.

variable_name [action [option1 [option2... ]]]

Actions

Truncate

Any string value can be truncated. If the value is longer than the value you request, it will be shortened, and either an elipsis or what is specified after the length will be appended.

Example: title truncate 20 or description truncate 400 (continued)

Auto_typography

Works Any string field such as a textarea custom field. Formats text so that it is semantically and typographically correct HTML. Note: description fields with a WYSIWYG editor have HTML by default.

Example: field_name auto_typography

Strip_tags

Works Any string field such as a description field, or textarea custom field. Will strip HTML tags from the text.

Example: field_name strip_tags

Date Format

You can format any date field (such as date, date_added, date_published, date_start, etc.) by passing a format string as the action. The format string is identical to the PHP date format specification found here, however characters should be escaped using an asterick ("*").

Example: date *m/*d/*Y

The following format shortcuts are also supported:

  • db: *Y-*m-*d *H:*i:*s
  • db_date: *Y-*m-*d
  • db_time: *H:*i:*s
  • timestamp: (unix timestamp)
  • time: *g:*i *A

Example: date db

Photos

The action for a photo should be the size of photo you want. This can either be a size extension as defined in your content bin settings (like "l" or "sq") or an explicit size, such as 100x100. More on photo sizing in the photos server section

After the photo size you can specify what kind of value you want. Available values are url, html, width, height, title, caption, orig_name, image_type.

Examples:
photo large url will give you a url for the image
photo 100x100x1 html will give you html for the image

Files

Available actions for file fieds are: url (default), download_url, orig_name, filesize, date, ext, author.

Boolean Fields

A keyword action can be used with boolean fields, such as the active state or a checkbox custom field, to perform a ternary expression on the value

Example: active yes|no (If active == true, this value will not be "yes", otherwise "no").

Pagination

If you use the "Insert page break" button in your description fields, you can request certain pages from your text using the "page" action. (Note: this only works on the description variable).

Examples:
description page:1
description page:2
... and so on.

description page:2+ will return everything from page 2 on.
description page:2-4 will return pages 2 through 4.
description total_pages will return the total number of page sections.

Geocode Fields

The geocode custom field has special keyword actions that allow you access different parts of the data saved by Osmek.

Where "geocode_keyword" is the keyword you specified when creating the custom field…

geocode_keyword address returns the formatted address
geocode_keyword lat returns the latitude
geocode_keyword lng returns the longituded
geocode_keyword embed returns a google map embed code
geocode_keyword embed 500x400 returns a google map embed code sized to 500px by 400px geocode_keyword json returns the full data object saved by Osmek as a JSON string

Video Fields

The video custom field has special keyword actions that allow you access different parts of the data saved by Osmek.

Where "video_keyword" is the keyword you specified when creating the custom field…

video_keyword url returns the url for the video
video_keyword embed returns an embed code for the video
video_keyword embed 500x400 returns an embed code for the video that fits within 500px by 400px
video_keyword embed 500x400x1 returns an embed code for the video sized to exactly 500px by 400px
Adding "autoplay" as the last action will make the video… you guessed it, auto play.
video_keyword embed 500x400 autoplay
video_keyword title returns the video title
video_keyword description returns the video description
video_keyword thumb returns the video thumbnail saved by the video host
video_keyword duration returns the duration of the video

Drop Down Fields

Drop down custom fields have some special functionality

Where "dropdown_keyword" is the keyword you specified when creating the custom field…

For drop down fields with the key/value pairs predefined:

dropdown_keyword returns the key selected
dropdown_keyword disaplay returns the display value

Utilizing arrays in templates

When accessing feeds, the response data from Osmek starts as a multidimensional array. You can utilize this to make a loop

Example template with loop:

<h1>This is a blog roll!</h1>
[items]
<h1>[title]</h1>
<span class="date">[date *m/*d/*Y at *h:*i *A]</span>
<span class="tags">Tags: [tags][value], [/tags]</span>
<span class="comments">Comments: [comment_count]</span>
<div class="body">[description]</div>
[/items]

For a Photo Gallery content bin, you can loop through photos inside an album using the [photos] keyword:

<h1>This is a photo album</h1>
[photos]
[photo 100x100x1]
[/photos]