Page fragments
Page fragments are just that: fragments of a page. The term could be applied to any kind of design that builds up a page from parts, but we are going to focus on building a page from a collection of similar objects.
We are going to build a reading list site. It can be a way to publicize the books you have read and plan to read, and to act as a recommended reading list for others.
In your content directory, make a new directory, call it books/. Remember that wok won't act differently because these new content files are in a directory, it is just a nice way for us to organize them. In this directory, make a few files, like these:
books/harrypotter2.mkd
title: Harry Potter and the Chamber of Secrets
author: J.K. Rowling
category: books
tag: fiction, fantasy
---
I remember devouring this book in only a few days when I was in middle
school. This was the first series I actually had to wait for each new
release.
books/hhgtg.mkd
title: Hitch Hikers Guide to the Galaxy
author: Douglas Adams
category: books
tag: fiction, comedy, scifi
---
This is practically required reading for any geek. It is a fantastic
mix of British humour and mock science fiction. Find out why the answer
is *always* 42.
I'll be brief and only list those two, but feel free to make some more.
We also need a page that will collect all these fragments together. I suggest making this file in the root of your content directory.
books.mkd
title: Books
type: booklist
---
Here is a list of books I have read.
That's it. All of the real magic happens in in the templates. The important thing is the type attribute, because that is what ties it to the template we are about to write.
The template is what will gather all the fragments and work them into a single page. The name of this file is important: it has to match the type of books.mkd above. Make this file in your templates directory
booklist.html
{% extends "default.html" %}
{% block content %}
{{ super() }}
{% for book in page.subpages %}
<div class="book">
<h1>{{ book.title }}</h1>
<h2>by {{ book.author }}</h2>
<span class="tags">{{ book.tags|join(', ') }}
{{ book.content }}
</div>
{% endfor %}
{% endblock %}
Let's take this in parts
{% extends "default.html" %}
This makes the page use the general site template. For more details see templates.
{% block content %}
{{ super() }}
This starts a block, that was defined in default.html. The super() call brings the contents of the content block from default.html. This way it builds upon the template, instead of over writing it.
{% for book in page.subpages %}
Since the slug of the books.mkd page is "books" (derived from the title "Books"), and the fragment pages have a category of "books", wok will recognize them as sub-pages, and conveniently provide them here for you.
<div class="book">
<h1>{{ book.title }}</h1>
<h2>by {{ book.author }}</h2>
<span class="tags">{{ book.tags|join(', ') }}
{{ book.content }}
</div>
This is just some basic HTML and Jinja that makes a div that contains the information about the book. Notice that we don't make a link to the book, that isn't what we want. We just want everything to appear on this collection page.
{% endfor %}
{% endblock %}
End the loop, end the block, and that is the end of the file.
Page fragments don't always make sense, but when they do, they can be very useful. They can make it easier to collaborate on one part of the site by having each person write a different fragment.
They can also help deduplicate your site. From this base, you could make another page that lists all the fiction books, or fantasy books, based on their tags. Then when a new book fragment is added, the main book list, the fiction book list, and the fantasy book list will all be automatically updated: you won't have to do a thing except re-run wok.