Stacey CMS: Part 2

08 May 2013

Welcome back to Part 2 of my Stacey CMS tutorial/figuring crap out series. If you haven’t read Part 1, you might want to, as I’m assuming stuff from that article… you get the idea.

PS - I wrote that relative link to another page in the site by including the text I wanted to link in “[” and “]” and then the link itself in parenthesis. If I write it like “/articles/stacey-cms-01/”, then it jumps down to the root, then back into articles. Still trying to figure out a simpler way to refer to it.

If you’re coming back to this, you may notice some small style changes (bigger font sizes and different fonts). These are simple changes to improve readability. You’re welcome to do the same by jumping into the public/docs/css folder, and updating the screen.css. But don’t go through just changing stuff all willy-nilly, especially if you’re still learning CSS. I don’t think this is the best-written CSS, but it does things and if you don’t know what it does, you might want to try it out. For example, what happens if you uncomment that background image on line 23…

In future articles, I’ll do a full overhaul of the site’s HTML to bring it up to HTML5</abbr> (it's currently 4.01, which is, like, [16 years old]( and CSS, which is not necessarily old, just not my STYLE *ba-dum* *chik*). I may even use [Sass](!

This time, we’re going to create a template for “articles”, instead of just using what was once project. But first, let’s dissect the current projects template, so that we can have a good idea of what’s going on. I’m going to assume you have a basic understanding of HTML and CSS, and how a page is laid out. You can always refer to the free HTML and CSS course I mentioned in the previous article.

###Okay! Templates!

To open the projects template, go into the templates folder and open “project.html”. Yep, the templates are (basically) HTML, so if you know HTML, this should be a breeze. The first place I notice something different is on line 6, between the title tags. We have ampersands, followed by names. These are variables that Stacey uses, so that it can dynamically insert the content to which these variables refer. The first one, “title”, is defined at the top of this file. Just by writing “title:” and the title, it’s defined. You’ll see other ones like this for the date, as well as the content.

You may notice that content does not have any HTML around it except for the div. If this is confusing, remember that the content in Stacey is written in Markdown, which converts into HTML when it gets to the browser.

You’ll also notice variables that are not defined in the document. For example name, which is also in the title tag. If you remember, we defined some site-wide variables in the content folder, in a file called “shared.txt” with an underscore in front o if. I don’t know the specific reason for the underscore but it probably has to do with ensuring it doesn’t render out a page, or demarking where the variables are stored. You can look it up in the documentation if it is bothering you. But yeah, if you open that file, you can see where variables that are used across the site are defined.

You can add your own variables here, if they are going to be constant throughout. Or, you can add them to the specific document followed by a line break and a “-“. I’m going to make a variable for this document called “tldr”. We’ll discuss in a moment how we can add this to our template conditionally, so that if we don’t define it, we don’t have to worry about any errors.

The third unique item are those elements that begin with “:”, like next-page, previous-page and media. These are partials, which are stored in the templates/partials folder. They are included in a couple of ways.

One way has a bit of “if” logic that seems to be asking if the PHP “siblings” variable exists (but don’t quote me on that). But we can figure it out! If you look at the bottom of the page, it’s offering me links to a previous project and a next project. Those did not exist when I only had one article. So, when I have more than one article, which acts as a sibling, it offers me links to the previous and next article. If we open the assets fold, we see a partial called “next-page.html” and “previous-page.html”. In each of those is for each logic to display the links. So, for each sibling article, it spits out a previous and a next link at the bottom of the page. It seems that it does that, even if you are at the earliest article, and that it creates a loop around, so that if you are on the latest article, the “next” will be a link to the very first one, and so on. I have no problem with this, but if you want your beginning to be a beginning, and your end to be your end, you’ll need to spend some more time in the documentation, figuring it out.

The other one is a reference to “media”. Hmm. If I look in the partials folder, there’s another folder called assets, and inside that is a “media.html”. Inside there, it looks like it’s asking if there is a certain media type in the folder along with this .txt file, then spit out the related partial. I think that’s what added the image slider in the previous article.Edit: If there is any additional media you want on the page, you just include it in the folder, and media pulls in the proper partial to handle it.

###Still following me?

I’m getting pretty lost in all this logic myself. If you’re like me, you’re thinking it’s cool that a lot of this stuff is sort of figured out for me, but I’ll come back to it if I need it.

Let’s make our own version. First, do a save as, and save the file as “article.html”. First thing I’m going to do is remove the “‘s Portfolio” from the title. Because it’s not. I don’t mind if it just says the article’s title, followed by my name. (Just so you know, I also went through all the other templates and did the same thing to maintain consistency. It might be smarter to write a “header” include so that I only have to write it once…)

Also, everything from line 26 to 33, in regards to the gallery, going away. Not sure about the hr tag, but we’ll leave it for the time being ( I would prefer to add that in CSS, maybe by adding some padding to the bottom of the content div, and then setting border bottom… But this is about the HTML right now).

You know what? That’s all I want to change right now. Because later, I’m going to rewrite all the HTML anyways. If you want to change more, change more! If you want to keep some stuff I removed, keep it! In fact, here’s a fun challenge. Pull out EVERYTHING. And then, start adding stuff as you want. See what’s the smallest bit of the code you can have in your template in order to make it work.

Once you’re done with it, and you want to make a page using your template, just create a new folder in the content folder where you want it to be. For me, I created a new folder called “stacey-cms-02”, and then saved the text document as “article.txt”. And then, I write!

Before we go, we’re going to do one more thing… remember the “tldr” variable I added to this page? I want that to be a summary of the article, and I want it to show up on the home page, as well as the articles page. If you go to each one, they appear the exact same… But there are templates for index.html and for category.html. If we go into each, we see one small difference in each one: index.html has a category-lists partial, and category has a projects-list partial. I’ll save you the wondering: if you go into navigation and look at each, the category-list partial has one extra bit of logic wrapped around it. The difference? projects-list only looks in the the existing folder for children and then spits out their title, as well as a thumb if one exists. Category-lists goes through all the folders in content, looking for children, and displays them out. That way, if you decided to have projects AND articles on your site, you can have a similar hierarchy in each folder, and the home page will list out both for you, like the gentleman than it is.

Since I’m super lazy ass right now, I’m just going to add my extra bit of logic to both category-lists and project-lists. We can actually just use the same logic that conditionally includes a thumb. That is, if I have a “tldr” defined if my content, then spit it out. Otherwise, don’t! I also added a “summary” class, in case I need to do some additional styling (edit: I did.)

Okay! That’s it for now. I’m making a list of things I want to do with this site in particular, and each one deserves it’s own little bit of articles…

So look forward to articles about all of these things! I might end up having to do a bunch of this as once, so the site might jump forward and then I’ll go back and write the articles about it.

As always, here’s a link to this project on github. EDIT: As mentioned in the previous article, this version of the site is no longer mantained as the site is now run on Jekyll. The link is included for historical purposes.