How to edit theme

< Back
october-cms / Jan 22, 2019 - 5 min to read.

Introduction


You can check active theme from the main Dashboard

DASHBORD_SS

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 ..

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.

You can check more information about how to install theme and activate it in this article How to Install October CMS Theme.

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.

FILE_SS

on front-end it will look like this

FE_SS

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>

PAGE_SS

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

PAGE_FE_SS

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.

LAYOUT_SELECT_SS

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

PAGE_WITH_LAYOUT_FE_SS

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.

LAYOUT_FILE_SS

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.

LAYOUT_FILE_REPLACE_SS

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.

LAYOUT_USING_PARTIAL_SS

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.

PARTIAL_CONTENT_SS

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

PARTIAL_CONTENT_EDITED_SS

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

PARTIAL_CONTENT_UPDATE_FE_SS

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

HOME_PAGE_FOOTER_SS

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.

HOME_CONTENT_SS

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

CONTET_BLOCKS_HTML_SS

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

CONTEN_HOME_OUTPUT_SS

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.

CONTENT_SS

OUTPUT_SS

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.

MARKDOWN_SS

OUTPUT_SS

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.