4.1 Basics and Listing Template
In this lesson we’re going to begin the process of adding a blog to your site. We’ll start by setting up the content file structure our blog will need, and then we’ll create a listing template to show our latest posts.
1.Introduction1 lesson, 01:23
2.Getting Started3 lessons, 26:42
3.Grav CMS Templates4 lessons, 25:21
4.Set Up a Blog4 lessons, 33:39
5.Conclusion1 lesson, 03:43
4.1 Basics and Listing Template
Hey, welcome back to Up and Running with Grav CMS. In this lesson, we're gonna be doing the first half of getting you set up with a basic blog on your Grav site. We're gonna be getting all of the content setup. And we're gonna create the template for the parent listing page for the blog. On the screen here on the left, you've got the file structure of the site that you've been working on so far. And on the right, you've got the source files that you have as part of your access to this course. I've actually got some precreated blog content for you, so you don't have to set it up manually. So we're gonna create our blog content structure. And then, we're gonna copy in the predone content from the source files. To do that, we're gonna go into the user folder again, and then into the pages folder. In my experience with Grav so far, when you're setting up something like this, it's easier to do this part directly through your file manager than it is to go through the admin panel, just in this case. So the first thing we're gonna do is create the folder that's going to house both the parent page for our blog and all of the child pages, which will be each one of the blog posts. So we'll make a new folder, and we'll give it the name 03.blog. And we'll jump inside there and we're gonna create a new markdown file. We'll call this one blog.md. As you know from our previous lessons, whatever you name your markdown file, that is the name of the template from the theme that you're gonna use to display that file. So that means that later on, we're gonna need to create a template file named blog.html.twig. Okay, so now we've got our folder and we've got our blog's parent page markdown file in there. The next thing that we need to do is add in some posts. So for each one of these posts, it's gonna need its own folder. And inside that we have the markdown files and any images that are used in each one of these posts. In your source files, you'll find a folder named pages. So go into that folder, and then into the folder that's named blog. It has a different number, it's 04 in this case, but don't worry about that. You just need to go into that blog folder. And then, you wanna copy everything except that blog.md file. We're going to be coding up that md file by hand in a second, so we just want each one of the folders for the individual posts. So grab those and copy and paste them into your blog folder. So we'll just have a quick look at what's inside. You could see in each one of these folders, we have a markdown file named item.md. So that tells us that we're gonna need to create a template named item.html.twig. And that template is going to control the display of our individual blog posts. Each one of the folders also has an image and that image has just been inserted above the first line of text for each one of these posts. All right, so lets go ahead and setup our blog.md file here. For our purposes, we're not gonna include any actual content in this file. We're just gonna use the header section only, that front meta section. So we'll add the three dashes to open the header section, and the three dashes to close it. And now all we're gonna do is use this mark down file to specify the content that should be displayed when you go to this top level page. So we're gonna say content: then we're gonna go onto a new line and add a tab indentation. And then we're gonna say items: and then we're gonna set this to a string and it should be @self.children. So that tells the Grav CMS system to look up all the children underneath this page. So that's the basics of our file structure setup to accommodate our blog. And there's a whole bunch of other stuff that you can do too. You can add on all kinds of extra features. But I wanna really focus on just the essentials, so you know what you absolutely must include. And then you can decide what extras you wanna have on top as an option. So with that done, now we're ready to set up our blog template. So we'll go back into our file structure, back up to the user folder > themes folder > themes-from-scratch folder > templates folder. And we're gonna create a new template and we're gonna call it blog.html.twig. So let's open that up for editing. And the first thing that we wanna do is extend on our base template, just like we did with our default template. So, we're gonna add in extends and then, partials/base.html.twg. Now in order to start outputting our blog posts on this page, we're gonna need to fetch a collection of all of those blog posts. And we wanna store that collection inside a variable. So we're gonna use Twig to do that by adding set collection, so that sets the variable name collection, and having it = page.collection with brackets on the end there. Now that page.collection integrates with what we just added into our blog.md file and it gets all the children of this current page. So now that collection variable is gonna be storing all of those blog posts. And we can start outputting the content that's inside that. And once again, just like we did with our default template, we're gonna need to use the content block. So we're replacing that content block placeholder in the base template. So we'll add block content, and then we'll add endblock. Now we're gonna start iterating through that collection of content that we've stored in the variable collection, and we're gonna use a for loop to do it. So we'll add for page in collection, and then we'll round that off with endfor. And inside this for loop, we're gonna output each one of our individual blog posts. So to do that we're gonna need a div with a class blog_post. And then, we'll start by outputting the blog post title, so we'll add an h1 element with a class blog_post_title. And this listing page is just gonna give a summary of each one of the posts. So we want people to be able to click through and read the full thing. So inside that title we're going to add a link, and we're gonna have that go through to the blog page's URL. So we'll do that with page.url, and then we'll output the page title with page.title. Now underneath the blog post title, we're gonna show the date that blog post was created on. So add another div with a class blog_post_date, and we'll add in Posted on. Then we'll just include some span tags. This is just for styling. And then inside the span tags, we're gonna output page.date. And that's just gonna fetch the post date of the blog post in question. Now that date is just going to get returned as a raw time stamp, so we need to process that into a format that's gonna make sense. So we're gonna add a filter by including a pipe symbol. And then we're gonna use the date function. And inside the brackets for the date function, we specify the format that we want, which we do by adding quotation marks and then putting small d, big M. And you'll see the format that that turns out as when we look at the front-end when we're done here. Now we wanna output some of the actual content for the post, so we're gonna add another div. And this one is gonna have the class blog_post_content". Now in here, we want a clipped version of our post. We don't wanna show the whole thing. We just wanna show a summary, so we're gonna output page.summary. Now Grav actually gives you the ability to specify your own delimiters, so your own set of symbols or characters that you wanna include in a post at the point at which you want it to break off at the end of a summary. So by default, if you insert three equals signs inside the page for a blog post, that will indicate where you want the summary to end. And you can find all of that in the config settings for your Grav site. So when we use this page.summary that's looking at the markdown file, and it's gonna extract all of the content before those three equal signs. So you can have a look at the content that you're provided with that we just pasted into your site, if you wanna see an example of that. And then finally, we're just gonna add a Read More link after the summary. So we'll add a div with a class read_more. We'll add a link. And once again, this is gonna go through to page.url. And then for the text, we're gonna add, Read More and then we're just gonna include a right pointing arrow at the end of that. All right, so let's go to our front-end and see what we've got by clicking on the blog link that we have in our menu now. And you can see that there is an error. What I actually did was I made a typo. Instead of writing .twig when I included our base template, I left the i out. I wrote .twg. I wanted to leave that included in this course because it gives you an opportunity to have a look at the excellent bug checking system that's included in Grav CMS. So when something goes wrong, you don't get a weird unspecified PHP error that you're then left to sort of figure out yourself. You're given excellent information that helps you isolate exactly what's wrong in your code and what might be happening. So you can see here it's given us a heap of information. It's shown us at exactly what points in the Grav CMS system itself it's run into something that it can't complete. And then, it gives you a very, very clear error message up on the top left here. So it's telling us, template partials/base.html.twg is not defined. So right away, we can identify where the mistake is. So that enables us to go back into our template, correct the error, and then go back. And now everything is working. So here is our blog listing. We've got our title, our post date, and then our post summary and Read More links showing up for each one of our blog posts. And you can also include Pagination in a blog if you'd like. In this case I haven't included it because you do need to install a plugin to power Pagination. And we just don't quite have enough time on this course to cover that topic. You also have the ability to include categories and tags. So these are all extra features that you can include in a Grav CMS site. And I'll include some links in the notes for this video to where you can read a bit more about how to integrate those features into a blog if you choose. Okay, so now we've setup our blog template. But in order to complete our basic blog, we still need to setup our item template, so that when a person goes to read the full blog post, we have a template controlling exactly what they're going to see. So we're gonna code that up in the next lesson. I'll see you there.