How to edit OctoberCms theme

Themes define the appearance and layout of front-end of your website built with October CMS. October themes are completely file-based and can be managed with any version control system.

for example Git, Svn ..

You can check active theme from the main Dashboard

This page gives you the description of October themes. You will find more details about pages, partials, layouts and content files in the corresponding sections.

Directory structure

---

themes/
 - oc-plaza/          <=== Theme name
   = pages/           <=== Pages directory
     => home.htm
   = layouts/         <=== Layouts directory
     => default.htm
   = partials/        <=== Partials directory
     => sidebar.htm
   = content/         <=== Content directory
     => hero.htm
   = assets/          <=== Assets directory
     = css/
       => site.css
     = js/
       = images/
         => site-logo.svg

Above you can see an example oc-plaza theme directory structure. Each October theme is having with a separate directory. One active theme is used for displaying the website.

You can set active theme with the activeTheme parameter in the config/cms.php file or with the Theme Selector on the System > CMS > Front-end Theme. The theme set with the Theme Selector overrides the value in the config/cms.php file.

Let us uderstand pages, layouts, partials, content and js,css

---

All these markup are using special markup (Twig), You can just write HTML for simple static structure, but for advanced operation like condition and looping in yout HTML then, you can lern it from here https://twig.symfony.com/

Note : October CMS supports a single level subdirectories for pages, partials, layouts and content files. (so you can not put partials inside nested directories only single subdirectories)

Valid file with subdirectory : themes/oc-plaza/pages/home.htm

Invalid file with subdirectories : themes/oc-plaza/pages/another-subdir/home.htm

Themes can contain the following objects

---

We use (Demo theme) which is already provided by the October CMS for further exploration

We suggest to checkout our video at top it will show theme directory properly.

• Pages
• Layouts
• Partials
• Content files/blocks

lets cehck them in little detail.

1. Pages

---

All websites do have pages. In October CMS pages are represented with page templates. Page template files reside in the /pages subdirectory of a theme directory.

Page file names do not affect the routing, slug is needed to provided separatly to show that page front-end site. The files should have the htm extension.

on front-end it will look like this

Lets create new page so we can have better idea, we will create page welcome and use slug/url : /welcome so, it will available at http://tute.test/welcome

content of page will be :

<h1>Hello Welcome !</h1>

Now You can Click preview button or navigate to http://tute.test/welcome to check your created page.

But you can see its just plain html without any head, style and scripts.

To correct this we need to move our next object layouts

2. Layouts

---

Once you apply layout to page it will start using that layout to show page content.

Now when you preview your webpage it will look like this.

You can select Layouts menu item from side menu to show all available layout.

layout file's markup is simply replace {% page %} with the content we used in page.

You can see screenshot above it will just replace our page's <h1>Hello Welcome !</h1> with {% page %} and show markup on front-end as below screenshot.

3. Partials

---

Partials contain reusable Twig markup code that can be re-used anywhere throughout the website. Partials are extremely useful for page elements that repeat on different pages or layouts. A good partial example is a page header and footer which is used in different page layouts.

We have seen that our default layout file is using some partials, you can see screen below.

You can select Partials menu item from side menu to show all available partials

Lets see footer pratial content, you can see our partial is one directory deep. Its inside site subfolder so its really easy to organize files.

Lets edit its content and saveit and check how it works on front-end side

If we preview our website now you can see footer content is updated.

If we can put to gather its same thing layout {% page %} tag was doing , here it replace {% partial 'site/footer' %} with partial's content which we passed as argument here we passed site/footer.

You can also check other pages like home page where site/footer partial is used its content is also changes, so its like change at once place and it will effect every where where its used

4. Content files/blocks

---

Content blocks are text, HTML or Markdown(.md) blocks that can be edited separately from the page or layout.

They are designed to hold static content only and support basic templating variables.

Partials are more flexible and should be used for generating dynamic content.

Content blocks files reside in the /content subdirectory of a theme directory.

The following extensions are supported for content files

• htm - Used for HTML markup.
• txt - Used for plain text.
• md - Used for Markdown syntax.

Note : The extension affects the way content blocks are displayed in the back-end user interface (with a WYSIWYG editor or with a plain text editor) and how the blocks are rendered on the website. Markdown blocks are converted to HTML before they are displayed.

1. htm file

---

These conten text are treated as HTML markup. so you need to be carefult to enter content as it can break HTML of site if entered wrong.

If we open Home page you can see here {% content "welcome.htm" %} is used.

You can select Content menu item from side menu to show all content blocks

From above screenshot you can see HTML markup of welcome.htm block

You can see Its output on home page as below its treated as HTML

2. text file

---

These conten text are treated as normal text no matter how you write them. so user can be sure it wont create any problem in front-end. It will display as text.

3. md file

---

These conten text are markdown content you can check more information. here Markdown Docs.

So, this content will be transfered to HTML based on markdownstanderd and displayed on front-end.

Conclusion

---

October CMS themes are really basic and powerfull to enhance your front-end apperiance. You can easily modify them and it provides tones of options to use them.

For developer October CMS provides all the require tools to edit theme, Also it provides enough UI for End-users who can edit basic stuff.

It do not have any extra overhead so, its win-win condition for developers and end user clietns.

We will cover advanced use of theme and how to modify it in up coming tutorials.