Keys

Keys are a way of extracting data from subpages. In a blog you have lots of posts and a main blog page. The main blog page extracts the title and image from each post using keys.

To make it easier to understand keys I'll use a blog as an example. Note that keys have a much broader use than blogs. It can be used for all kinds of collections such as blog posts, products, articles and more. The best way to get started is to create a new blog based on an existing one. By doing that you'll get all the example code you need. In this walktrough we've simplified the code a bit to exaplain what it does.

In a blog we have two templates:

  • blog.tpl
  • post.tpl


In this simple example the blog page displays the title of each post together with an image.

post.tpl

This template will be used for all posts in the blog. 

<div class="post">
     <sf-image3 id="1" width="1170" height="400" key="image"></sf-image3>
     <sf-singlerow id="2" key="title" html-element="h1"></sf-singlerow>
     <sf-text id="3"></sf-text>
</div>

This template adds a div which contains an image, title and text as content tags. We have defined a key name for the image with key="image" and a key name for the title with key="title". This allow us to go on and create the blog template.

blog.tpl

This template will show all blog posts

{ com_keys (
    id:'1',
    description: 'Blog posts',
    class: 'posts',
    html:'
        <a href="{{ page.url }}" class="post">
            <span class="image" style="background-image:url({{ keys.image | resize:120,120 }})"></span>
            <span class="title">{{ keys.title }}</span>
        </a>
    ',
    sortBy:'publishedDate descending',
    useChildPages: 'true',
    limit: '9',
    offset: '0'
) }

This code will generate <div class="posts"> and  repeat the code inside the html parameter for each post. All keys specified in post.tpl are available in the keys object, {{ keys.title }}.

It it also possible to resize or crop images with filters. In this example we resize the image to 120x120.

Reference parameters for com_keys

  • id – Uses the same id name space as content tags.
  • description – Visible when no subpages exists
  • class – Add a class to the wrapper <div>
  • html – The code repeated for each page
  • sortBy – publishedDate/pageName/createdDate/updatedDate in ascending or descending order.
  • limit – Limit the number of pages
  • perPage – Show this amount of pages before pagination
  • paginationHtml – Specify the HTML code used by the pagination (see example for more details)
  • offset – Skip pages
  • exclude-self – Exclude the current page


Reference for html in com_keys

  • {{ page.url }}
  • {{ page.name }}
  • {{ page.publishDate | format:"%e %B, %Y"}} – See formatting guide.
  • {{ keys }} – Access the keys defined in the subpage template