Creating/editing October CMS theme

October is an open-sourced CMS that is built on the Laravel PHP framework. In its unmolested form, October is very different than other CMSes in that is does not require a heavy backend to integrate with its templates. Unlike that of Wordpress, ExpressionEngine, and Django, October allows you to create single pages while leveraging the power of dynamic templating. The best part is that it allows easy integration with version control.

Sites using October

As of 9/17/15, we have 3 websites that are currently that utilize October. They are as follows:

Steps for editing

Install October

To be able to see any updates made to these themes, a working install of October will need to be setup. To do so, follow the steps outlined in the October installation section of the documentation.

Install and activate theme

Once October is up and running locally on your machine, we now need to add the theme to the site. Like that of Wordpress and unlike that of ExpressionEngine, the content as well as the visual asthetics of an October site are located within the theme. This allows you to change the structure and content of the site just by activating and deactivating themes within the control panel.

Creating a new theme

If you are creating a new theme, we need to create a directory within your themes directory that is located just inside the root of the October install. Feel free to make the name of the folder anything you want as it does not mater.

When you are creating an October theme, there are 6 possible files/directories that you will have within the root directory of your theme. There are two files that are REQUIRED. The first is the theme.yaml file. This tells October the name of the theme and some of the of the configuration settings. Below is a boilerplate of what it should look like:

name: Salva O Renick  
description: Theme made for the Salva O Renick marketing agency.  
author: Salva O Renick  
homepage: 'http://salvaorenick.com'  

Additionally there is a file named theme-preview.png that should reside within the themes/[your-theme]/assets/images directory. This thumbnail should be 600 x 350 pixels. This will appear within the October CMS control panel when previewing all of the available themes.

Once these files are in place, log in to the control panel of October, select the "Settings" button, followed by the "Front-end theme" tab. Assuming you did the prior steps correctly you should see your theme on the right of the screen. Select the "Activate" button to activate the theme.

Now you are ready to start building your website as a theme. Refer to October's theme documentation for additional information on how to proceed.

Installing an existing theme

To install an existing theme utilizing a theme from GitHub, simply clone the repository into the themes directory. Once complete, navigate to the control panel, select the "Settings" button, followed by the "Front-end theme" tab. Once there, select the "Activate" button to activate the new theme.

Make changes to theme

Making changes within a theme are just like anything changes within a CMS or HTML template. Make your changes and then commit/push them to the theme's respective repository.

Pulling changes

To retrieve the changes from the theme's repository, simply navigate via Terminal to the theme's directory and perform your standard git pull command. Now all of the new changes are present on the live server.

More often then not, just pulling the new template code and image assets won't be enough. Since October runs on Laravel, Laravel will cache templates/views to help with performance; meaning your changes will not be reflected on the live site. To clear the template cache, perform the following command:

php artisan cache:clear  

NOTE: depending on the server's directory permissions, you may need to prepend the above command with sudo.