Support Center

About Koken

This Help Center provides support for Koken, a free content management system designed for photographers, artists and designers.

What's new in Lens

What's new in Lens

Last Updated: Mar 23, 2015 12:08PM EDT

In this document we chronologically track recent edits and additions to Lens variables, tags and templates. This is low-level, nitty-gritty stuff that may only be of interest to theme designers.

0.21.0 (Mar 23, 2015)

New helper classes added for contact form support

This release of Koken includes support for contact forms embedded in pages. All published form elements are assigned helper classes for theme styling. See the "Contact form" section of the Helper classes article for more detailed information.

0.20.0 (Feb 15, 2015)

login.lens template support added

In support of the new premium Password Protect plugin a login.lens template has been added to Koken's template framework. Koken includes a default login.lens template for themes that don't include this template.

.k-password-protected helper class added

Also related to the Password Protect plugin is a new .k-password-protected helper class. If the plugin is installed, and a password protected page is requested, the protected page's <body> element is assigned this class.

0.19.0 (Dec 9, 2014)

<koken:public> and <koken:unlisted> tags added

These tags may be used in any template to test whether the parent page was accessed through a public or unlisted site url. If the page is public (viewable to the general public and search engines) then content inside the <koken:public> tag is rendered. If the page is unlisted then content inside <koken:unlisted> is rendered. Useful for certain items like social media share links that may be included globally in every template but should not be displayed on unlisted pages to discourage content sharing.

.k-unlisted helper class added

This class is automatically assigned to a page's <body> tag if the page is accessed through an unlisted site url. For example, site pages for albums, sets, images and videos that have unlisted visibility. Useful in style sheets should a designer want to apply styles to a page if the content being displayed isn't public.

"restart" method and link added to Pulse

Our Pulse slideshow player now supports a restart link and Javascript method. When used the slideshow returns to the first item.

album properties accessible within <koken:covers> tag

Before this release, album properties (e.g., {{ album.title }}, etc) were out of scope when used inside the <koken:covers> tag, and thus rendered empty. Now they populate with values as expected.

0.18.0 (Sep 22, 2014)

'social' attribute added to koken:link

This attribute makes it much easier to publish social media share links for content. Supported values (and linkable social media) include "twitter", "facebook", "pinterest", "tumblr" and "google-plus". When clicked Koken automatically assigns a URL that opens a new browser window for the assigned service to share the item.

.k-link-lightbox-loading class added

This class is automatically appended to the anchor link generated by koken:link if the link loads the lightbox. The class is automatically removed from the anchor link when the lightbox appears above the page. This makes it possible for designers to append spinners, colors, or any styles to the links when they're clicked and the lightbox is loading.

0.14.4 (June 6, 2014)

koken:albums tag behavior modified

In previous versions, <koken:albums> returned all albums an image/video was part of except the album the image/video was currently being viewed in. We've changed this so that all albums are always returned (regardless of context). If you want the old behavior you can append include_current="false" attribute to <koken:albums>.

{{ count }} variable added

This variable can be used with any Lens template tag that utilizes <koken:loop>. Insert the variable before the loop and the total number of items that will be looped-over will be returned.

0.14.0 (May 20, 2014)

New <koken:meta /> tag

This new tag publishes smarter, more SEO-friendly meta tags in the head of every .lens template. It automatically creates meta author, description and keywords tags that use their global values by default (as defined through Settings > Site Publishing). When viewing content pages, the description tag uses album summaries, content captions, and essay excerpts. All are truncated to 160 characters for SEO. The keywords tag is appended with the tags assigned to page content.

Here's an example that publishes dynamic titles and metadata in any .lens template:

  <koken:title />
  <koken:meta />

0.12.0 (March 11, 2014)

Added autolink attribute for Lens variables

New boolean attribute that converts any "http://" string found in a published string to a hyperlink. This is set to false by default, but is set to true automatically whenever paragraphs="true" is used (so you don't need to explicitly assign it). This makes it much easier to include hyperlinks in a caption without injecting unecessary HTML markup into the soure data.

Unique .k-link-lightbox class appended to lightbox enabled links

When lightbox="true" is assigned to <koken:link> the published link receives a .k-link-lightbox class for targeting with CSS.

Added .k-lightbox-loading class

This class is appended to the body tag when a lightbox-enabled link is clicked. The class is then removed once the lightbox loads. Designed to be used with loading animations or whatever else you'd like to show / hide.

Added collapse option for theme settings sub-groups

Theme settings can grouped under sub-headers, which until now have always been open by default. We added a new collapse boolean so the group may be closed initially. Details in the Settings article.

Added preview refresh option for theme settings

Most theme settings can refresh a theme preview live, but there may be some that require a preview frame refresh. To make that possible we added a reload_preview boolean. See the updated Settings article for an example.

More control over setting scope in theme settings

You've always been able to scope a setting to specific themes, but we've taken this a step further by allowing unique values to be assigned to each scoped template. That way instead of a setting automatically changing all other scoped templates it can now act independently. You can even specify the default values each scoped template should use. This optimizes settings by allowing you to use a single setting to modify multiple templates. See the updated "scope" section of Settings for examples.

And and Or conditional support in <koken:if>

For the times when you need to test two boolean setting against one another we've added AND and OR conditional support to <koken:if>. See the documentation for a few examples.

New {{ location.template }} variable

This global variable outputs the file name of the parent template, minus ".lens". Eg, "contents" would be displayed in contents.lens, etc.

0.10.0 (September 19, 2013)

New templates: tags.lens, tag.lens, category.lens, categories.lens, timeline.lens, date.timeline.lens

Additional templates have been added to provide more content publishing opportunities. They include:

  • tags.lens — Index of all your tags, which link to...
  • tag.lens — Tag detail page. Displays assigned albums, content and essays.
  • categories.lens — Index of all your categories, which link to...
  • category.lens — Category detail page. Displays assigned albums, content and essays.
  • timeline.lens — Unified stream of all your most recently published albums, content and essays.
  • date.lens — Archive page that displays timeline events for a day, month or year.

<koken:event>, <koken:event_album>, <koken:event_content>, <koken:event_essay> and <koken:event_album_update> tags added

Koken 0.10.0 introduces a new "Timeline" template (timeline.lens) that renders the latest updates to your albums, content and essays as events. These template tags were added to support the publication of each event type. See the tag documentation for more information.

Added RSS feed for Timeline

The Timeline's RSS feed is now included as part of a site's RSS auto-discovery links. Can be accessed at or added through Add Links in Site. Theme developers may use the new {{ rss.timeline }} variable to output the RSS file's path.

<koken:context> tag added

This tag publishes contextual information about images and videos. If an image/video is being viewed as part of an album or through a tag/category query, <koken:context> provides the necessary data to publish the context's title, the index of the image/video within that context, plus the total number of images/videos the context includes. Check the documentation for example usage.

relative formatting option added to <koken:time>

<koken:time> can now output relative dates ("7 days ago"). Simply add relative="true" to the tag.

flat filter added to <koken:load>

For those who want to display all albums (but no parent sets) we've added a flat filter to <koken:load>. This works in code form when requesting albums directly, like so:

<koken:load source="albums" filter:flat="true">

To display flat albums on the regular albums index of a theme, edit the Albums index filter in Site.

timeline added as source option for <koken:load>

Coinciding with the new timeline publishing, timeline has been added as an option for the source attribute of <koken:load>

Basic arithmetic added to variables

For the times when you need to multiply, add, subtract or divide two numerical values created by a Lens variable, we've added support for basic arithmetic. Here's an example:

<koken:covers minimum="{{ settings.cols * settings.rows }}">
    <koken:img />

limit attribute added to <koken:loop>

To prevent <koken:loop> from iterating past a fixed number we've added support for a limit attribute. Assign a number and the loop will break-out and stop looping if it reaches that value.

<koken:discussion_count> template tag added

This ties-in with the existing <koken:discussion> tag to display the number of comments made on a particular piece of content. Note that this requires a discussion plugin to be enabled, which at the time of this writing is limited to Disqus. Also note that with Disqus, count data is only returned when requested from a page outside of the page displaying comments. Here's an example that could be used inside <koken:loop> on the essays.lens page.

  {{ discussion_count }}

<koken:dates> template tag added

This tag outputs a linked list of monthly archive links for the timeline, albums, essays and content. See the tag documentation for examples.

<koken:select> template tag added

This tag creates an HTML <select> element that can receive multiple data types to display linked options. See the tag documentation for examples.

Date is now the default output of <koken:time />

Adding show="date" to <koken:time /> is no longer needed. Tag outputs date by default. To output date and time (the former default), assign show="both".

url queries for album pages

Album pages (album.lens) may now be viewed using urls that contain search queries. This allows you to filter returned data to display only a particular subset of data by date, tag or category. Here's an example from a timeline's album update event that links the event to the album's album.lens template to display all content added to the album on the same day as the event.

<koken:link filter:order_by="uploaded_on" filter:year="{{ date date_format='Y' }}" filter:month="{{ date date_format='m' }}" filter:day="{{ date date_format='d' }}">
Link label

<koken:featured> tag added

Used to conditionally display content if a page is being filtered. See the a href=""><koken:featured> tag documentation for examples.

Added note_align attribute to settings

Controls the alignment of setting notes (assigned with "note"). Is set to centered by default. Assign "left" for left alignment and "right" for right alignment.

Current template added as namespaced class to body tag

We were already appending data sources as a namespaced class to <koken:body>, but because some themes might offer templates with matching data sources we added the template names too. Class is always "k-lens-" plus the name of the template file. So...album.lens is "k-lens-album" and if you added "custom.lens" the class would be "k-lens-custom". Should help with targeting elements with css, etc.

0.9.3 (August 2, 2013)

order_by and order_direction added to koken:parent

The <koken:parent> tag has been expanded to support two new attributes: order_by and order_direction. These allow you to control the order in which data retrieved by <koken:parent> is displayed.

Limit support added to <koken:pagination> plus simplified tags for previous/next links

A new limit attribute has been added to the <koken:pagination> template tag. This will allow you to stipulate the maximum number of page links that should be displayed. If there are more pages than the limit allows, you can use the new <koken:pagination_limited_next> and <koken:pagination_limited_previous> tags to publish links that jump to the next set of limited paginated results.

The <koken:pagination> template tag has been simplified by adding child tags for <koken:pagination_previous> and <koken:pagination_next> to more easily publish Previous/Next links.

{{ now }} and {{ year }} global variables added

Two new date variables have been added. {{ now }} outputs the current time as a unix timestamp. {{ year }} outputs the current year. Both of these variables are global and may be used in any template.

if_true variable transformation added for booleans

For the Lens variables that are boolean in nature we've added an if_true attribute. This allows you to output any string you'd like if the variable returns true. If the variable is false nothing is printed. This will come in handy with the {{ essay.featured }}, {{ content.featured }} and {{ content.favorite }} boolean variables. Here's an example of how this could be used to append a class to an article if an essay is featured.

<article class="{{ essay.featured if_true="featured" }}"></article>

out_of_scope_value attribute added to settings

Anytime a setting conditional is used in a template that's not included in the setting's scope the return value is false. This attribute allows theme designers to control what the return value of the setting should be in these edge-case situations. See the bottom of Settings for more info.

koken:albums now works in other content contexts

The <koken:albums> tag — used to display a list of all albums an image/video is part of — now functions in any content context. Previously this tag only worked on the content.lens page, but may now be used in album.lens or anywhere individual images/videos appear.

Display theme settings on separate lines

Need a setting's label/value to be displayed on separate rows? You can now do that by adding a separate_line attribute. See the updated Settings article for more info.

0.9.2 (July 5, 2013)

link_current attribute added to <koken:breadcrumbs />

Boolean for controlling whether the last crumb link (the current page) is linked. Default value is true.

0.9.0 (July 2, 2013)

sets.lens template added

Koken now supports the inclusion of a sets.lens template. This template displays all top-level sets, and will load when requesting "". Clicking a set displayed on this page will load the set.lens template for that set.

<koken:featured_image> template tag added

<koken:featured_image> is used to output the featured image of an essay or page. It would be used in any template where essay or page data is being used. See the tag documentation for example markup.

<koken:breadcrumbs> template tag added

Templates may now display hiearchy using the new <koken:breadcrumbs> tag. Simply insert it into any template and the tag will output links for each parent template above the current one. Options include control over the separator character used in addition to whether breadcrumbs are published when only one link is available. See the tag documentation for more info.

<koken:note> template tag added

This tag is for displaying help tips or other information inside a template. The contents of a note are only visible when the theme is being previewed.

<koken:iptc> template tag added

Image IPTC metadata may now be published in templates. Koken stores a subset of IPTC data using the most common fields when an image containing IPTC is uploaded. Click here to see the tag's complete documentation.

{{ content.filename.clean }} variable added

This variable outputs the filename of an uploaded image or video without its file suffix and any underscores or hyphens replaced with spaces. This would be helpful for people who format their file names using titles. Example: "new-york-bridge.jpg" would print as "new york bridge". Like all variables you could then append case too. For example, the following would output "New York Bridge".

{{ content.filename.clean case="title" }}

position attribute added to <koken:background /> template tag

The <koken:background /> tag has been updated to include a position attribute. This assigns a horizontal and vertical position to the image when assigned as the background. It defaults to "center center". For example, to position in the upper left corner:

<koken:background position="0 0" />

{{ location.site_url }} variable added

{{ location.site_url }} variable added. This returns the path to your published site.

{{ album.public }} and {{ content.public }} variables

{{ album.public }} and {{ content.public }} variables added. These are booleans that return true if their visibility is set to public, false if set to unlisted.

{{ rss.essays }}, {{ rss.contents }} and {{ album.rss }} variables added

Three new variables added for publishing URLs to RSS feeds. The {{ rss.essays }} and {{ rss.contents }} variables are global and may be used in any template while the {{ album.rss }} variable should be used when loading album content in album.lens or directly.

autoplay added to <koken:video />

A boolean autoplay attribute has been added to <koken:video /> to allow immediate playback of videos. Default value is false.

{{ location.hostname }} variable added

Added a variable that prints the host domain of the published site. e.g., "".

Lazy loaded images now fade-in by default

In previous versions of Koken you needed to append fade="true" to any <koken:img lazy="true" /> tag to make the images fade-in when loaded. This update changes this so fade is true by default and no longer necessary to include (unless you want to change its duration or remove the fade effect).

0.8.5 (May 24, 2013)

url_encode option for variables

Lens variables now support an additional url_encode option. This will encode the string printed by the variable for url compatibility. Example:

{{ content.title url_encode="true" }}

0.8.3 (May 22, 2013)

k-image-loaded event added

The new k-image-loaded event detects when lazy loaded images have loaded and fully faded in. This applies when the <koken:img> template tag has both lazy="true" and fade="true" assigned.

0.8.2 (May 15, 2013)

album variables for primary cover image

For the times when you need a direct link to an album's primary cover image we've added new {{ album }} variables. Check out the updated Lens variables document for more.

Custom links in navigation groups

Navigation groups were re-worked in Koken 0.8 to make them easier to use. This point update allows for custom links that don't point to predefined sections to be added. See the end of the updated Navigation groups article for an example.

0.8.0 (May 9, 2013)

Easier custom templates

We've simplified the process for adding custom templates to themes. Now all you need to do is add an HTML document with ".lens" as its file suffix and Koken 0.8 will recognize the template and make it available for linking on your site. See the new tutorial Create a custom page for instructions.

We've also posted a new tutorial that explains how to Add new section templates, which allow you to offer publishers alternate layouts for the standard section templates (albums.lens, essays.lens, etc).

Page url variables

Variables were added that print the absolute url of the content page. These variables include {{ album.url }}, {{ content.url }} and {{ essay.url }}.

Label variables

As part of the link and label editing added in Koken 0.8, variables for printing label values have been added. You may see these in the updated "Global variables" section of Lens variables.

New <koken:discussion> template tag

In conjunction with our new Disqus plugin we've implemented a <koken:discussion> template tag. This tag is targeted by the Disqus plugin to add comments to a page. The template tag may be targeted by other (third party) plugins as well to insert content in the same place. See the updated koken:discussion tag documentation for example usage.

Load album by id

Albums may now be requested using their id (displayed in the Library). The example below would load the album with the id of 10:

<koken:load source="albums" filter:id="10">
  <!-- Insert template tags and variables -->

Additional EXIF outputs

The <koken:exif> tag has been updated to include a new "computed" variant that outputs numerical values only (eg, "100" instead of "ISO 100"). You may also request clean/raw versions of each EXIF type without looping through them all. See the updated koken:exif tag documentation for more.

Slide transition in Pulse

The transition_type attribute has been updated to include "Slide" as a supported transition type. This transition slides images from right to left.

Keyboard bindings

Any <koken:link> tag or anchor can now be bound to the keyboard. For example, the left and right arrow keys are now used in every default theme's content.lens template to move forward/backward to neighboring pages. See the updated koken:link documentation for examples.

New minimum attribute added to <koken:covers>

If you have a layout that requires a minimum number of album covers to function you may assign a minimum attribute to <koken:covers>. Koken will return all covers and will fill-in any missing covers by randomly picking an image from the album. See the updated koken:covers documentation for examples.

Google+ profile variable

{{ profile.google_plus }} added to output a publisher's Google+ profile url.

Notes for theme settings

For settings that could benefit from more information we've added support for notes. Notes are displayed underneath the setting they're applied to in the settings panel. Simply add <"note"> followed by the value you want. Here's example markup from a theme's info.json file:

  "name": "Theme name",
  "version": "1.0",
  "description": "Brief description of this theme",
  "demo": "",
  "author": {
    "name": "Your name",
    "link": ""

  "settings": {
    "Thumbnails": {
      "icon": "img",
      "settings": {
        "show_title": {
          "label": "Show title",
          "type": "boolean",
          "value": true,
          "control_first": true,
          "note": "This hides the thumbnail titles"

Alt properties with <koken:img />

The <koken:img /> template tag has been updated to automatically output an alt property in the img element it generates. The alt value is equal to the image's title if it's available. Otherwise it uses the image's file name. If you don't want the alt property to be generated assign a null value and it won't be included. For example:

<koken:img alt="" />

Theme location variables

For those who need to know the path to their theme folder we've added two new global variables: {{ }} (protocol plus http host) and {{ location.theme_path }} (relative path to the theme's folder).

Better default links for navigation groups

As explained in Settings your theme may define additional navigation groups for publishers to edit. Koken 0.8 has improved and simplified the markup for adding default links. Adding links is now handled simply by passing in the names of the sections or profiles you'd like to publish links for. See the updated Settings article for more info.

Easier method for assigning a theme's front page

Dictating which template in your theme should be used as the front page is now much easier. Simply add a default_front_page variable to your theme's info.json file with a value equal to the template's file name (minus ".lens"). For example, if you wanted to make the albums.lens template the default front page of the theme you could set it up like this:

  "name": "Theme name",
  "version": "1.0",
  "description": "Theme description",
  "demo": "",
  "author": {
  "name": "Your name",
    "link": ""
  "default_front_page": "albums"

Recommended social media metadata

We've posted a new tutorial on adding social media metadata to your templates for more control over how content is shared through Facebook and Twitter.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found