2015 Oct 06

For many years the content management system (CMS) market has been dominated by a few common names like Wordpress, Drupal, and Squarespace, all of which have been around since the early 2000’s.

Recently I was introduced to a relatively new CMS by the name October which has proven itself as an efficient, simple, modern and most of all fun alternative.

October is …

"A free, open-source, self-hosted CMS platform based on the Laravel PHP Framework. A simple and modular CMS that grows with you, with a precise and beautiful interface that comes as second nature."

October currently boasts over 160 plugins to extend your site and over 30 pre-built themes, many of which are free to use. One of the most useful and fun features included in October is the ability to develop your own custom theme directly from the browser. October provides many tools to help you get a theme up and running very quickly while having fun doing it.

To begin building your own custom theme in October you first need to create a blank theme. In order to create a blank theme you need to navigate to the settings page in the main navigation bar, then click on Front-end theme in the CMS section of the sidebar. This view will display the existing themes that are installed as well as present you with options to find more themes or create a new blank theme.

screen shot of settings interface

Clicking on "Create a new blank theme" will present you with a popup where you may fill in the details of your theme such as the name and description. Finally after filling in the details of your theme and clicking create a directory will be created in your themes folder which contains the files for your new theme, and your new theme will be activated by default.

Now that you have a new blank theme configured you can navigate to "CMS" in the main navigation. Here you will find the files that make up your current theme, as well as any assets you have uploaded to your site. The next step in creating your custom theme is to setup some templates. October uses the twig templating engine and is broken down into four primary elements which are defined in the sidebar on this page:

screenshot of CMS interface

  • Layouts

    Layouts are the primary template structure used to house your pages. Primary elements that are repeated across all pages such as the header/footer should be placed here.

  • Pages

    Pages are somewhat self explanatory. Each page of your site is defined in a page file which contains fields that allow you to set the title, URL slug, and meta data to the individual page.

  • Partials

    Partials are blocks that you intend to reuse throughout various pages such as a contact form or common sidebar content.

  • Content

    Lastly Content contains the information you want to display in your pages and/or partials. If you are developing a site for a client, this is likely what they will be managing.

Let's start by building out our primary layout file. Click on Layouts in the sidebar and then click the blue "Add" button at the top of the slide-out. The main view will change into a text editor with a couple of inputs, one for the filename and one for the description. Set the filename to whatever you would like with the file extension .htm, default.htm for example. The description field is optional and is used to tell any backend administrators what this file is for.

Inside the text editor section you can start building your layout. In my example the layout contains the html, head, body, header, and footer elements as well as any resource links such as css files and/or scripts. Optionally you can leave the header/footer elements out for use in a partial later.

<!-- layouts/default.htm -->
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Your Site - {{ this.page.title }}</title>
        <!-- meta data set by individual page fields -->
        <meta name="description" content="{{ this.page.meta_description }}">
        <meta name="title" content="{{ this.page.meta_title }}">
        <meta name="author" content="Industrial">
        <link href="{{'assets/main.css'|theme}}" rel="stylesheet">
    </head>
    <body>
        <!-- Header -->
        <header>
        </header>

        <!-- Page Content -->
        {% page %}

        <!-- Footer -->
        <footer>
        </footer>
    </body>
</html>

In the above example there is a code block using twig, {% page %}. This is where the content of your pages will render.

Now that you have a layout, you can build your first page. As an example we will build a landing page with some basic content. Click on the "Pages" link in the sidebar and then click the blue "add" button. Pages present you with a few new fields. In addition to the filename and description, you also have fields for a title, url, layout, and a tab for page meta data. The url field will determine how the page is accessed. By inputting a "/" into the url field this will set the page as the default landing page, or you can input "/about" to access a page at yoururl/about. Again any template file you create should be named with the extension .htm. Below I have included an example home page with some basic content.

<!-- pages/home.htm -->
<main>
    <h1>Home</h1>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
</main>

<aside>
    <div>
        <h2>Newest Post</h2>
        <h3>Post Title</h3>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
    </div>
</aside>

Although the above example will work, it does not allow us to reuse content or manage the content cleanly. By moving our code blocks into a partial this will allow us to reuse that code across many pages. Click on the "partials" link in the sidebar and then click on the blue "add" button. Name your partial with the file extension .htm and move the code block from the sidebar in the above example into the partial.

<!-- partials/your-partial.htm -->
<div>
    <h2>Newest Post</h2>
    <h3>Post Title</h3>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</div>

By replacing the code block in the page with a reference to the partial it will be included in our page.

<!-- pages/home.htm -->
<main>
    <h1>Home</h1>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
</main>

<aside>
    {% partial "your-partial" %}
</aside>

Page content can be included in the same way as a partial. The main difference between a partial and content is that partials are code blocks that are to be reused throughout your site where as content should contain as little code as possible to make it easy for average users to come back and edit later. October features many plugins which extend the functionality of content such as WYSIWYG editors or front end editors. Click on the "content" link in the sidebar and then click the blue "add" button. The only field available is the filename, make sure to include the file extension .htm. As an example we will move the main content of our page out of the page file and into our new content file.

<!-- content/your-content.htm -->
<h1>Home</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>

This content will be included in our page the same way we include the partial.

<!-- pages/home.htm -->
<main>
    {% content "your-content.htm" %}
</main>

<aside>
    {% partial "your-partial" %}
</aside>

At this point we have completed a basic code structure for our site, But we have no css to style it. In the sidebar we have an assets link where we can create a css file or script file if we want to include javascript. Additionally we can upload images here as well by uploading a file. When we created our layout we included a link tag to a main.css file. Click on the blue "add" button and name the file main.css. Any css code written here will now be applied to your theme.

As you can see October makes theming your sites simple and efficient. October does not present any restraints in how you write your code and provides tools to make the process fast and fun.