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 theSystem > CMS > Front-end Theme
. The theme set with the Theme Selector overrides the value in theconfig/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 showtheme 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 passedsite/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 markdown
standerd 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.