PHP

Introducing OctoberCMS – a Laravel-based CMS

Nick Salloum
Share

October CMS is a lightweight, back to basics content management system built on Laravel, and on a mission to make your web development workflow easy again. It boasts a very simple and fast learning curve, with a guarantee that you’ll be off the ground and up and running in no time at all. It’s scalable and extensible through the plugin system, is easily maintainable through its file-based system, and allows for the effortless creation of administrative back-end interfaces. Before we dig a bit deeper into this promising CMS, let’s look at the foundation a bit.

october

Built On Laravel PHP Framework

The Laravel PHP framework is lightweight, sturdy, and elegant. According to them, it’s a framework built with a creative user in mind, transforming mundane tasks into effortless, enjoyable ones. The philosophies of both Laravel and October CMS coincide very nicely, and it’s no surprise to see that October has gone with this type of framework. The combination provides the perfect mesh of simplicity, speed, elegance, and artisanal-style programming. Let’s now take a look at setting up our first October CMS project.

Get Started In No Time

October makes installation a breeze for us. The following steps will set you on course for development:

  1. Either clone their repo on GitHub, or download the installer. The recommended way is to download the installer, as it’s simple and quick, and allows you to make some configurations right inside the browser in an easy-to-follow stepwise interface.
  2. Extract the files into your desired local directory, and configure your local server to match the local path.
  3. Set up a new database, and take note of the database name.
  4. Navigate to the install.php file in your browser, follow the instructions on screen, and enter your configuration variables.

As prompted, delete the install files after successful installation, and you’ll be ready to go. You can now navigate to your site’s front end, and explore the admin area too. Let’s dig in to the inner workings of October CMS.

How It All Works – Themes & Templates

The theme directory is the foundation for the end-output of any new October CMS installation. This directory contains all the sub-directories and files necessary for the CMS to tick. By default, October CMS kicks you off with a demo theme. Creating your own is as easy as creating a new directory (name it whatever you want), a theme configuration file called theme.yaml in the root of this directory, and a pages directory with a page file in it. For now, let’s explore the demo theme to get a grasp of the inner workings.

Every theme consists of sub-directories for pages, partials, layouts, content files, and assets. Each of these directories may contain sub-directories, allowing for simplification of larger scale projects. Here’s what the demo directory structure looks like:

themes/
  demo/
    assets/
      css/
      images/
      javascript/
      ...
    content/
    layouts/
    pages/
    partials/
    theme.yaml

Template files take on a simple structure, and make use of Twig markup. Twig is a PHP templating engine, enhancing and speeding up templating, and reducing common verbose tasks to simple code snippets. There are three parts to any of the page, layout, and partial template files:

  1. Configuration
  2. PHP code
  3. Twig markup

The configuration section is structured like a php.ini file, and is marked as finished by two = symbols, making way for the PHP section. The PHP section is optional for any template file, and is also marked as finished by typing two more = symbols. Finally, the Twig markup contains the actual contents of the template file. This is what a template file might look like, taken from their website:

url = "/blog"
layout = "default"
==
function onStart()
{
  $this['posts'] = ...;
}
==
<h3>Blog archive</h3>
{% for post in posts %}
  <h4>{{ post.title }}</h4>
  {{ post.content }}
{% endfor %}

Let’s look a bit more into what purpose each template file and section serves.

Pages

Page files have a self-explanatory title – they describe your site’s pages. They take on three parameters in the configuration section:

  1. url – the page url (required)
  2. title – the page title (required)
  3. layout – the page layout, which may point to a layout file (optional)
  4. description – the description for the page in the back-end (optional)

The page url can take on parameters, depending on the page in question. 404 and error pages can also be specified. Here’s a simple example of a page layout:

url = "/"
title = "Welcome"
description = "The home page."
==
<h1>Welcome Home</h1>

You can read up more on pages here.

Partials

Partials also have a fairly self-explanatory name – they refer to files that contain partial amounts of code. Partial files are powerful, because they can be called and reused in pages, layouts, or other partials. You can use the {% partial %} tag to call a partial from inside another file. Partials only support one configuration parameter:

  1. description – the partial description for the back-end (optional)

Here’s a basic example of a partial (right sidebar) calling another partial (recent posts):

description = "Right sidebar."
==
<div class="sidebar">
  <aside>
    {% partial "recent-posts" %}
  </aside>
</div>

You can read up on partials here.

Layouts

Layout files specify the layout of a page, following suit with the self-explanatory nature of the first two template file types we looked at. They act as the major building blocks for any October CMS project. They take on two configuration options, both of which are used in the back-end interface:

  1. name – the name of the layout file for the back-end (optional)
  2. description – the layout file description for the back-end (optional)

A layout page might look something like this:

name = "Default"
description = "The default layout for our template"
==
<!doctype html>
<html>
  <body>
    {% page %}
  </body>
</html>

Let’s assume that we named this layout file default.htm and placed it in our layouts directory. A page can then call on this layout like this:

title = "Welcome"
url = "/"
layout = "default"
description = "Welcome home!"
==
<h2>Welcome Home!</h2>
<p>...</p>

Pretty neat! More on layouts here.

Content Blocks

Content files contain content sections, and can be called from inside layout, page, or partial files. Content files support three extensions:

  1. .htm (for HTML markup)
  2. .txt (for plain text)
  3. .md (for markdown) <- awesome

You can call a content file using twig markup by running the {% content %} tag. Here’s an example of a page rendering a couple of content blocks:

<div class="sidebar">
  <aside class="recent-posts">
    {% content "einstein-quote.htm" %}
  </aside>
  <aside class="newsletter">
    {% content "newsletter.htm" %}
  </aside>
</div>

Check out more about content files here.

AJAX Module

October CMS has a very robust AJAX framework built in, allowing you to make AJAX requests and interact with a number of data attributes very easily. To add the AJAX framework, simply include it by placing the {% framework %} tag anywhere inside the page or layout in question. It requires jQuery (which should be loaded before the framework), so your page might look like this:

<script src="{{ [
    'assets/js/jquery.min.js',
]|theme }}"></script> 
 
{% framework %}

AJAX requests work by invoking an event handler on the server. This event handler can then update page elements using partials. There are two API’s at our disposal for performing AJAX tasks:

The Data Attributes API

This API lets you issue AJAX requests without any JavaScript (less verbose than the JavaScript API). Here’s an example from their website using the Data Attributes API. It redirects a user to another page after a successful request:

<form data-request="onLogin" data-request-redirect="/admin">

Easy and efficient. The only shortcoming I can see here so far is the limited list of data-attributes at our disposal. However, the JavaScript API offers a more powerful option.

The JavaScript API

This API is more powerful than the data attributes API, as it allows us to use any options and methods compatible with the jQuery AJAX function. We can use the request() method with any element inside a form, or on the form itself. The request() method has a single required parameter – the handler name. Here’s an example:

<form onsubmit="$(this).request('onProcess'); return false;">

With this method, we gain a lot more flexibility and control. For more on the AJAX module, check out the docs here.

Easy Extensibility

October CMS is easily extendable via plugins and components. According to the documentation:

Plugins are the foundation for adding new features to the CMS by extending it…Components are building blocks that can be attached to any page or layout.

Let’s take a look at each of these features in detail.

Plugins

Plugins are the basis of extending October CMS beyond out of the box functionality. They can define components, add back-end pages, interact and edit the functionality of other plugins, among other things. They are easily described and set up, and reside in the /plugins directory. To get started with plugin development, visit the plugin docs, or stay tuned for an upcoming tutorial on SitePoint in a day or two.

Components

Components provide us with configurable building blocks, and they can be attached to any page, partial, or layout. They extend the behaviour of front-end pages by:

  1. Injecting variables by participating in the page execution cycle
  2. Handling AJAX events triggered by the page
  3. Providing basic markup using partials

To read up more on components, check up on the documentation here.

Wrap Up

October CMS’s very own philosophy is represented throughout their documentation. Getting started is an extremely simple process, making you feel comfortable with the CMS off the bat. The two guys behind it, Alexey Bobkov and Samuel Georges, are dead set on making web development and deployment simple, and that for me is a huge attribute to this project.

If I could find one single thing to dislike about it, it would be that the AJAX framework is jQuery dependent. That’s not to say that it’s not sturdy and highly functional – in fact I personally think the jQuery AJAX function is awesome. In any case, you shouldn’t have much of a problem implementing your own set of JS should you desire. Other than that, I’m really excited about this CMS, and am already planning to use it in an upcoming project.