(Tutorial) How the heck does Twig work?

Gravatar Matt-SD

  • Posts: 41
  • Topic Created: Fri Jan 14 02:01:14 2011 +0100
  • Topic Updated: Fri Jan 14 02:03:19 2011 +0100

Here's a tutorial/explanation of how Twig works. First, I'll say what a lot of newcomers will want to know: Can I use PHP? No. You can't. Sorry.

PART 1: BLOCKS

Open the layouts/default.twig in a theme of your choice (I'll be using stardust). Look in the head & you'll see this line:

<title>{% block title %}$site.name{% if title %} ยป ${ title | escape }{% endif %}{% endblock %}</title>

What that does the {% block title %} does is declare a block & {% endblock %} ends it (obviously) the stuff in the middle is the fallback content for that block. It's the same for {% block content %} which you'll see often.

Now, open pages/index.twig. At the top you'll see this:

{% extends "layouts/default.twig" %}

which basically says this file (index.twig) fills in the blocks from layouts/default.twig. Below that you'll see this:

{% block content %} {% for post in posts.paginated %} {% include "feathers/" ~ post.feather ~ ".twig" %} {% else %} <h1>${ "No Posts" | translate }</h1> <p>${ "Nothing here yet!" | translate }</p> {% endfor %} {% endblock %}

what this does is fill in the content block from default.twig. You following me? The layout (default.twig) declares the blocks, & index.twig tells default.twig what's in them.

I'll continue writting this tutorial in the next post.

Gravatar Matt-SD

PART 2: VARIABLES

One variable you will use often is the $site.url variable. In PHP this would be $site['url'] or $site->url whichever tickles your fancy. What that variable outputs is the URL of your Chyrp installation. For example, if your site was located at http://example.com/blog/ then that's exactly what $site.url would output.

<a href="$site.url">$site.name</a>

Here's a list of the variables you'll most likely use

  • Theme:
    • $theme.url = the theme's directory
    • $theme.feeds = the RSS feeds associated with your blog in (uses a <link> tag)
    • $theme.stylesheets = a <link> for every CSS file in the stylesheets directory
    • $theme.javascripts = Same as above, but with javascripts
  • Post (obvious explanations omitted):
    • $post.feather
    • $post.id
    • $post.paginated = require the Pagination module.
      • $post.paginated.prev_link = Previous page of the paginated entry
      • $post.paginated.next_link
      • $post.paginated.pages = Number of pages
    • $post.created_at
    • $post.url
    • Text feather:
      • $post.title
      • $post.body
    • Audio:
      • $post.description
      • $post.audio_player
    • $post.dialogue = requires chat feather
    • Link:
      • $post.source = the link
      • $post.name = name for the link
      • $post.description
    • Photo:
      • ${ feathers['photo'].image_link(post, 434) } = outputs photo at a max width of 434
      • $post.caption
    • Quote:
      • $post.quote
      • $post.source = Who said it
    • Video:
      • ${ feathers['video'].embed_tag_for(post, 440) } = video player at 440 px wide
      • $post.caption
  • Flash: Don't know ANYTHING about this one
  • Trigger: See this page: https://github.com/chyrp/chyrp/wiki/Triggers-%28List%29
  • Modules: All the active modules
  • Feathers: All the active feathers
  • Title: The title of the current page or post
  • Site: (I've excluded comments for the obvious ones)
    • $site.url
    • $site.name = Your blogs title
    • $site.description
    • $site.feed_url = The URL entered in the General Settings, Feed URL box
    • $site.email
    • $site.timezone
    • $site.can_register = If users are allowed to register or not
    • $site.comments_per_page
  • Version: The version of Chyrp you are using
  • Now: the current timestamp. Equivalent to PHP's time()
  • Post: same as $_POST
  • Get: same as $_GET

Of course, there a more, but these are the one's you'll use the most. If think there's a variable that isn't listed here, just ask on the IRC channel (#chyrp on irc.freenode.net)

Gravatar Matt-SD

PART 3: FILTERS

A filter works by first getting the variable then applying the filters to it. For example, no make your blogs title capitalized, you would do this:

${ site.name | upper }

To get the current date in dd/mm/yyyy format, you'd do this:

${ "now" | date("d/m/Y") }

The Inspect filter is like PHP's print_r() or var_dump(). This would output the $site.url, $site.name, $site.description, etc:

${ site | inspect }

You can also have multiple filters. For pagination, you could do something like this:

${ "Page %d of %d" | translate | format(posts.page, posts.pages) }

which would output something like "Page 2 of 5". And because of the translate filter, you would see this: "Seite 2 von 5" if your language was set to german (from Google Translate. Sorry if it's wrong.)

For a full list of filters, & further reading on Twig, go here: https://github.com/chyrp/chyrp/wiki/Twig-Reference

- Matt Dwyer (Matt-SD) MattSD.com