Time for part two of the
yst primer I started here.
This time, we will see the basics of using string templates and
yaml data to generate some funky lists.
I’m going to use a silly example,
but it should be clear how to make this work for sensible
applications like keeping a list of publications
or what have you.
Before we continue, let’s simplify the
the CSS we inherited from the template site.
Here’s a simpler
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Next, let’s replace that horrible messy CSS folder with this simpler file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
This is very much like the earlier messy CSS, but a lot simpler. Obviously you’ll want to modify this for your own use, but it should be easier to modify the simple version than it was the old multi-file mess.
Onto some new stuff now.
First, let’s add another page to our site.
index.yaml and add a new item:
1 2 3 4 5 6 7
Now let’s make
1 2 3
yst should update the site in the
There should now be a
index.html and a
The navigation panel on the left should work to
move between them nicely.
Now things get interesting. Let’s write some information about the Beatles into a yaml file. Here’s a sample:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Now, we want to translate this information
into something we can put on the website.
The first thing we need to do is tell
yst that we
will want that data for our
1 2 3 4 5 6 7
Don’t worry about the
requires line just yet.
Take a look at the
We read the data from
beatles.yaml into something
We read in and order the data.
That is, we have ordered the entries by the
and that is the order the items will be printed.
Now, when we want to use that data,
we can use a slightly more complicated version of the things like
$nav$ from before.
Let’s move back to
1 2 3 4 5
What we have here is a template telling
read in the data from
and then run each entry through the
yst that the page requires the
function (that’s what that
requires line was for).
yst will know to recreate the
beatles.html page if
Let’s define the
listname() function now.
Note that there’s a blank line at the beginning of this file.
That’s quite important as we’ll see a little later.
So what this function does is tell
yst how to
format each item.
We want to output this as a list,
so each item of
thebeatles is going to be a list item.
We achieve this by using markdown syntax for unordered lists,
hence the dash.
(We need the blank line so that each new item appears as a new list item
on a new line.)
it is how to refer to the current item.
yst to print the forename attribute of the first item.
Then comes a clever bit.
We check whether the current item has a
Only if this comes out as true is the next bit implemented.
This next bit (up to the
$endif$ prints the
I use this method with my list of papers:
if there is a
url attribute, the paper title is a link to the file.
Finally we print the
instrument attribute in italics.
This seems like an incredibly complicated way of generating a simple list. But it is also a very powerful way to do so. We could have had other information on each Beatle that doesn’t show up here but that appears elsewhere. Or we could use the same information to display things differently. Let’s say we wanted a list of Beatles broken down by instrument. (A more serious case would be to group all your talks with the same title).
Let’s go back to the relevant portion of
We are going to extract the information from
but instead of sorting by surname, we are going to group by instrument.
(We’re also going to require a couple of new files, we’ll
get to that in a minute).
1 2 3 4 5 6 7 8 9 10
You don’t actually have to write the words
GROUP BY in capitals,
but I think it helps keep clear what are the keywords
yst is looking for.
Now let’s add a new list to the
1 2 3 4 5 6 7 8 9
This follows the same pattern as before.
Now we need to look at what sophisticated clever stuff
is going on in the
1 2 3
Now, I have to admit I’m getting to the edge of my understanding of
what’s going on here, so this may be a little bit of
a cargo cult programmer way to do this.
As I understand it, what
GROUP BY does is
it from referring to a single entry at a time
into something that refers to a list of entries that
share the property we have grouped by.
first(it) refers to the first item of the list of things sharing the
In this case, it would be the first Beatle
having the instrument attribute guitar, say.
The conditional part of this template, then,
does the following:
when we get to a new instrument (when we hit the first
dude with a particular attribute) we add a new list item
and then we write the name of the instrument in bold.
That takes care of getting the instrument names written.
How do we write out the names of the people who have those
Like I said, it looks like we have a list of entries
for each possible state of the
Well, we already know how to get a list to print:
we run each element through a function.
In this case the
It looks like this:
$it:simplename()$ formats each member of the list
it is a list now, because of the grouping).
You could actually replace a small part of the
by a call to
I’ll leave that as an exercise.
Now let’s imagine that you remember a bunch of other people who you want to add to your list of Beatles (I’m regretting not choosing an example where it made sense to add a bunch of new items, but bear with me).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
Now all you need to do is run
yst and the website has
incorporated these two new secret Beatles.
Working out how all these little pieces fit together can be a little
brainmelting, and it can seem like overkill.
In fact, in my case, it almost certainly is overkill.
But I hope to have shown you a little bit of the power of this system.
The beauty is that once you’ve set it up,
you’ll only ever really need to add stuff
yaml files and
yst will take care of the rest.
I have tarballed up the final version of the
which should more or less match what I’ve described here.
You can get the tarball