Creating a Theme for Anchor CMS

We're going to be making a custom theme for the "up and coming" open source CMS, Anchor. Anchor is a super simple, lightweight and bullet fast content management system. You can pick up a copy of Anchor from the Anchor CMS website, plus you can also checkout some of the themes available for Anchor on Anchor Themes.

Why Would I Want to do That?

Maybe you’re a web designer or front end developer and you’re looking for a way to take things a step further? Perhaps you have a static HTML prototype of a website, you want to be able to create pages and articles quickly, but you don’t want the hassle of writing code each time. Anchor CMS will give you that control without giving yourself a development headache.

What do I Need?

This article assumes at least a basic knowledge of web design and development concepts, such as hosting a website and coding HTML. You'll need a working installation of Anchor CMS, which can be a local or remotely installed. To install Anchor (locally or remotely) just download a copy and follow their installation instructions.

Along with your installation you’ll need a prototype of your theme. The prototype should be a cleanly marked-up HTML visual, with a stylesheet and any assets you've used, such as images and JavaScript. To demonstrate this whole process, I’m going to be making a theme too. You can see my theme below, and you can download the prototype HTML from the link at the top of the page:

I like to think theming for Anchor is like making a sandwich, and I know a lot of people are partial to a good sandwich. So I hope my references help you in trying to understand the steps I go through. Also, I prefer to list out what some of the functions in Anchor actually do, as this seems like a more straightforward way of explaining them.

Getting Started

Hungry? Let's eat then..

Get Your Breadboard & Ingredients

Much like other content management systems, Anchor has a directory for just themes. If you go to the root of your installation there'll be a folder called "themes". Create a new folder in here and name it whatever your theme is going to be called, in my case I’m going to call my theme “Cleat”:

You'll also need to create an "about.txt" file. This is just a basic text file which explains what the theme is called, who it's by and any referral information. The "read me" file essentially. Take a look at my example below:

Theme name:		Cleat
Description:	A light and pure theme thats simple at heart.
Author name:	David Darnes
Author site:	http://david.darn.es
License:		http://licence.visualidiot.com

Along with your about.txt file, place your prototype files in the folder too. It's best to keep your assets, such as images, in a separate sub folder. To construct the theme we'll be taking chunks of your HTML and placing them into Anchor friendly php files.

Butter Your Bread

Most websites are structured with a header, a footer and a bit in the middle. Anchor CMS takes advantage of this commonality by allowing you to break your theme up into these separate sections. This helps with organisation and more importantly consistency.

Create a new file in your theme folder called "header.php". Open this file and your HTML file for the prototype. Copy the HTML from the very top, down to just before the main part of your content starts. In my case that's just after the menu. I decided this because in my design everything from the menu upwards is identical on every page, so I want to keep this consistent throughout my theme.

What we are now going to do is replace the static information with php helpers that are provided in Anchor. Below is the code I’ve copied from the top of my HTML prototype, but with some changes:

<!DOCTYPE html>
<html>
	<head>
		<title>
			<?php echo page_title("Page can't be found"); ?> - <?php echo site_name(); ?>
		</title>
		<!-- Asset links -->
		<link href="<?php echo theme_url('assets/style.css'); ?>" media="screen" rel="stylesheet" type="text/css" />
		<link rel="shortcut icon" href="<?php echo theme_url('assets/favicon.ico'); ?>" type="image/x-icon">
		<!-- Meta -->
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
		<meta name="generator" content="Anchor CMS">
	</head>
	<body>
		<section>
			<header>
				<a class="logo" href="<?php echo base_url(); ?>" title="<?php site_description(); ?>"><?php echo site_name(); ?></a>
				<!-- Main Menu -->
				<hr/>
			</header>

Notice that the HTML is still in place, but I’ve replaced any content or site-relevant information with snippets of PHP code. These pieces of PHP code are called functions, they act like placeholders for content. When the theme is used, these functions will be replaced with the content taken from the website. Here’s a list of the functions that I’ve used to replace the content:

<?php echo page_title(); ?> - Produces the page title, easy as that.
<?php echo theme_url('assets/image.png'); ?> - Used to get the url of assets in your theme folder, use this for your stylesheets and any images you use.
<?php echo site_description(); ?> - The site description set in the metadata section of Anchor.
<?php echo site_name(); ?> - The name of site, also set in Anchor.
<?php echo base_url(); ?> - The root url of the installation, which should also be the main site address.

If you ever get stuck with what these functions do, or you need something different to what I’ve shown above, checkout the Anchor CMS Docs.

Add a Tasty Menu

Creating a menu in your theme is pretty straightforward once you understand how it works. Anchor generates the menu from all the published pages you have created. Any page that is set to draft, or archived, won’t appear in the menu.

In order to utilise these published pages, we need a way to pick them out and run through them. Take a look at my example below:

<?php if(has_menu_items()) : ?>
	<nav role="main">
		<?php while(menu_items()) : ?>
			<a href="<?php echo menu_url(); ?>" title="<?php echo menu_title(); ?>"><?php echo menu_name(); ?></a>
		<?php endwhile; ?>
	</nav>
<?php endif; ?>

Using this, we can allow the theme to create a menu for the website. Line 1 is where we are checking "if there are menu items”, on line 3 we’re asking “while you have them do this with each menu item". On line 5 we stop working with that menu item, which means it will start the same process with the next item. Once it runs out of menu items it will go past line 5 and onto line 7, where it ends the whole menu creation process.

Each time a menu item is iterated, a set of functions is processed as well:

<?php echo menu_url(); ?> - Gets the link of the menu item.
<?php echo menu_title(); ?> - The title of the item, aka the title of the page.
<?php echo menu_name(); ?> - The actual name of the menu item, added in the page options.

Compare these to your menu and replace the content and information in your menu with the functions above. Make a note of how the menu code works, as knowing this process will become helpful for posts later on in the tutorial.

Butter Your Other Slice

Just like your header.php file, you'll want to take the footer section of your markup and paste it into a new file called "footer.php". In my theme I have a key line and a credit line, these appear on every page so I’ll place the HTML of this part into my footer.php file.

				<hr/>
				<small class="credit"><a href="https://github.com/daviddarnes/cleat" title="Cleat: GitHub">Cleat</a> for <a href="http://anchorcms.com" title="Anchor CMS Homepage">Anchor CMS</a>, Created by <a href="http://david.darn.es" title="David Darnes: Designer">David Darnes</a></small>
			</footer>
		</section>
	</body>
</html>

Your footer might not have the same complexity as the header, but it's a great place for crediting things such as yourself for making the theme.

Now that you've buttered your bread we can move onto the tasty part, the fillings.

Your Three Main Fillings

In order to cater for all the types of content your theme will deal with, we need to create three different files. These files sit between your header and footer and will display your posts, your individual articles and pages.

Posts Filling

Just as we did for our header and footer, copy the main area of your markup into a new file called "posts.php". The markup should carry on from where your header.php left off and your footer.php file should carry on from it. Your posts.php file is used to display all the published posts from a website. In other words, your blog page.

If you’ve made an HTML prototype for your blog page like me, that's even better. Now we've split them into separate files we need to link them back together, this is where the "theme_include" function comes in. At the very top of your posts.php file add the following:

1	<?php theme_include('header'); ?>

This function pulls the header.php file into the page, and by adding it at the very top that’s where it will be placed. The same goes for the footer, add the following to the very bottom of posts.php:

1	<?php theme_include('footer'); ?>

Using this method means that your header and footer stays consistent throughout the theme and makes managing code a much easier task.

Forming a Post Loop Relish

Remember what I said about keeping the menu method in mind? Take a look at this and see if you can spot any similarities:

<?php theme_include('header'); ?>
<?php if(has_posts()) : while(posts()) : ?>
	<article>
		<header>
			<h1>
				<a href="<?php echo article_url(); ?>" title="<?php echo article_title(); ?>"><?php echo article_title(); ?></a>
			</h1>
			<small><?php echo article_date(); ?></small>
		</header>
		<p><?php echo article_description(); ?></p>
	</article>
<?php endwhile; endif; ?>
<!-- Pagination -->
<?php theme_include('footer'); ?>

There are quite a few similarities, not with the names of the functions, but in how it runs. On line 2 we’re stating “if we have any posts and while we have those posts” run through each of the posts. Once it runs out of posts, the process ends on line 12. And just like the menu, the posts also go through a set of functions as well. Here are the functions in some more detail:

<?php echo article_url(); ?> - Gets the link of the post.
<?php echo article_title(); ?> - The title of the post.
<?php echo article_date(); ?> - When the post was created, in day month year format.
<?php echo article_description(); ?> - The description of the post, an optional field within the post.

Just as you did with you menu, compare these functions with your markup and replace the content and information with the functions which match.

This is great; we have our header, footer and posts all being pulled in.

A Taste of Your Work so Far

This is probably the first time you can check your theme to see if it runs. Login into Anchor and select your theme from the dropdown option within Extend > Site Metadata.

If you've followed these instructions correctly so far, you should be able to see your posts page.

If there are errors then don't worry, it’s probably just something a little out of place. Use this as an opportunity to read back and check if you've taken everything in.

Season With Pagination

Now, some of you might be saying "What if I have too many posts?". Well don't worry, as I'm going to cover that now, in a very easy manner. Check out this snippet of code:

<?php if(has_pagination()) : ?>
	<nav class="pagination">
		<?php echo posts_prev(); ?>
		<?php echo posts_next(); ?>
	</nav>
<?php endif; ?>

You’ll notice that the pagination is created in a similar, but simpler fashion to how the menu is created. On line 1 we’re asking if the amount does exceed the limit, then we create the next and previous buttons. On line 6 we’re ending the process.

Note: The amount of posts per page can be selected under Extend > Site Metadata.

This code will need to go in your posts.php file, but not inside any of the other loops. In my design it appears just before my footer, so I’ve added it to the very bottom of my posts.php file.

Article Filling

Relative to the posts page, the articles are deliciously simple. Once again you're going to need a copy of the main section of your prototype markup, or a copy of the HTML you want to use for articles. Just like your posts.php, this should match up with your header and footer code. In my example the article has a title, a date and the content.

Create a new file called "article.php" in your theme folder, and paste the markup inside. You'll also need to add your header and footer include functions, just as you did for the posts.php file. For my theme, the code for articles is minimal:

<?php theme_include('header'); ?>
<article>
	<header>
		<h1><?php echo article_title(); ?></h1>
		<small><?php echo article_date(); ?></small>
	</header>
	<?php echo article_markdown(); ?>
</article>
<?php theme_include('footer'); ?>

Once again, apart from the include functions, all I've done is replaced the static information and content with certain functions provided by Anchor. Here’s a rundown of them:

<?php echo article_title(); ?> - The title of the post.

<?php echo article_markdown(); ?> - The content of the post, the body copy.

<?php echo article_date(); ?> - When the post was created, in day month year format.

As before, go through your code and replace the static content and information with the relevant functions. After you've finished the article.php file you can view an article in action. This gives you a chance to check if everything is in working order.

Page Filling

You might not believe it, but pages are even simpler than articles. Copy your markup again, but this time paste it into a new file called "page.php" and add your include functions at the top and bottom of the file. Pages on websites normally hold static content and information that doesn't change very often. For this reason, pages don't need a date. Take a look at the code below:

<?php theme_include('header'); ?>
<article>
	<header>
		<h1><?php echo page_title(); ?></h1>
	</header>
	<?php echo page_content(); ?>
</article>
<?php theme_include('footer'); ?>

This is very much the same as article.php, but we're only using two different functions:

<?php echo page_title(); ?> - The title of the page.

<?php echo page_content(); ?> - The content of the page, the body copy.

After you’ve finished placing in the functions, go and try out viewing a normal page. The sample content that comes within Anchor (currently) doesn't give you a regular page, so you'll need to create one and add content.

Cut and Serve

If you've followed the tutorial properly, you should be left with a simple, yet solid theme for Anchor CMS. If you're experiencing problems, remember to check over your code carefully. It's easy to miss a character, or place things in the wrong order.

If things really aren't going your way, there's a blossoming community of Anchor CMS users that can help you with your theme. Just head over to the Anchor CMS Forum and either look for someone with a similar issue, or start a new discussion.

I also manage Anchor Themes, where you can download themes, check out websites that have been built with Anchor and submit your own work. I hope that this tutorial has helped you with making a theme for Anchor CMS, and I'm really interested to see what you come with! Enjoy.