Transcript

I’m going to show you have to implement the Perch Blog in your site and style it to look just like your designs. I’m assuming here that you have an up to date version of Perch installed and working and are ready to try out the blog.

First log into your account on the Perch website and download the blog add-on. It is free of charge as are all of our official add-ons.

Unzip the downloaded file. Inside you will find a folder perch_blog and another folder named blog.

We can now install the blog. Take the folder named perch_blog and drop it into perch/apps/

With a text editor open perch/config/apps.php and add a link to the blog runtime.

include(PERCH_PATH.'/apps/perch_blog/runtime.php');

Save this file and log into your Perch admin. You should see a new blog navigation item, click that item and as this is the first time the blog has run, Perch will now create all of the necessary tables for the blog. Blog is now installed.

Delete the file: /perch/apps/perch_blog/update.php

We will need some data in order that we can test blog, so add a couple of categories and posts to the blog as I have done here.

Once you have some categories and data you can see how it displays on the front-end. Go back to the download folder and place the folder blog into the root of your site.

In your browser visit yoursite.com/blog and you should see a blog listing and be able to click on any item and view the entry.

The example blog pages come with a very basic stylesheet just so you can see what is going on. We expect that you will incorporate the blog into your own design.

I have listing and detail page designs for my site and I want the blog to look like this design.

Here is my list – I have it as an html document list.html. I open that and the blog/index.php – which is the listing page – in a text editor.

Let’s have a quick look at the default blog index.php page. Most of what you see is just simple markup wrapping the blog listing. The actual functions that do the work are:

<?php 
    perch_blog_recent_posts(5);
?>

This gets the list of recent posts.

Then in the sidebar:

<!--  By category listing -->
<?php perch_blog_categories(); ?>
<!--  By tag -->
<?php perch_blog_tags(); ?>
<!--  By year -->
<?php perch_blog_date_archive_years(); ?>
<!--  By year and then month - can take parameters 
for two templates. The first displays the years and the 
second the months see the default templates 
for examples -->
<?php perch_blog_date_archive_months(); ?>

These are different functions showing you different ways to display your archives. You can use some, all or none of these – it’s up to you. The different functions are documented in the Perch documentation site.

Make a copy of this blog index page and open that in your browser, you can use this as a reference to the functions. The copy the HTML of your design over and replace everything in index.php leaving the link to the perch runtime at the top.

Your page should now just contain a copy of your HTML – make sure any links to CSS and so on still work.

Now go back to the copied old index.php and copy the perch_blog_recent_posts function, including the PHP tags that wrap it. Paste this in replacing the placeholder content.

I have space for categories and tags listings. So I copy the function for categories and the one for tags and paste them into my content.

If I refresh the page you will see that this is getting there – however the styling of my list of posts is wrong. This is because Perch, by default, outputs that as a list and this design has different mark-up.

This is no problem – Perch always gives you control of your mark-up. As always to edit the mark-up output by Perch you need to find the template used by Perch and edit that.

In the perch folder on your filesystem find apps/perch_blog/templates. Inside will be a folder named blog.

Copy this folder to perch/templates and you can now start editing. If you make a mistake and want to start over you can always copy the default template back out and start over.

The template that controls the look of the post when it is in the list is called post_in_list.html – you can change this to have the mark-up and perch content that you want. I’m just copying it over from my static list.html page.

Refreshing the page it all looks pretty good now – the default list view of tags and categories matches well. The only problem I have is that the thumbnail images are too small. This is also controlled by the template, if you look at the image tag here I have set it to crop to 50 pixels square. What I want is an 80 pixels in width image that maintains it’s ratio. I need to change this but changing it in post_in_list.html isn’t enough, I also need to go edit the master template.

All apps have a master template, this is where all the main fields that appear in admin are placed. Adding fields to this template will cause them to appear in admin. You can then use them on any template used in the blog. For the blog the master template is post.html. At the bottom of post.html you can see the image tag for the thumbnail. Change the size here. After changing image dimensions you need to re-upload images as the sizes are generated at upload time so it’s worth messing around with your templates before uploading a lot of images!

I’m now pretty happy with my listing, let’s have a look at the detail page.

I can follow the same process, making a copy of the detail page and then copying in my design and copying back the perch functions.

Interesting things to note are that I can add the title of the post using perch_blog_post_field() and the post itself is called with the function <?php perch_blog_post($_GET['s']); ?> the ‘s’ stands for the parameter that is on the querystring and then passed into this function.

Once again we need to edit our template to make it look like the design – this is the master template post.html which you used earlier to change the size of the thumbnail.

By default the excerpt in the template is suppressed, so it won’t show on this display but will display on the edit form and be available for other templates to use. I actually want to use it as a curated intro to my post so I remove suppress="true".

I am changing the size of the main image here which requires me to re-upload my image. If I look at the page now it is looking much more like my design. One thing missing is an image caption.

To add a caption I add a perch template tag to the post.html template. Go back to admin and refresh – the caption field appears. If I add some content, save it and refresh the page I can see my caption.

This is all you need to do to style blog with your own site design. The key things to remember are:

• The example pages can be replaced with your own designs, just copy in the Perch functions where you need them to go.
• The markup that is output by those functions comes from the templates. Copy the default blog templates from inside the app folder to perch/templates/blog and edit away.
• To add fields add them to the master template post.html, if you don’t want them to display on post.html then use the attribute suppress="true".