8/9/2019 Create a Custom Theme With OpenCart
1/31
Create a Custom Theme
With OpenCart:Introduction
In this series, I am going to explain how you can build a custom theme with the popular
open source e-commerce framework OpenCart. In this first part, I'll explain basic
structure of the OpenCart theme.
Before proceeding further, I assume that you hae working OpenCart installation on
your local workstation. If that's not the case, check the OpenCart online documentation
and set it up !as doing so is outside the scope of this tutorial". Once you hae a working
OpenCart installation you are ready to die in#
A Quick Look at the OpenCart Structure
OpenCart is built using $%C design pattern which allows separation of concerns
between the data and the presentation. &s a theme deeloper, you don't need to worry
http://www.opencart.com/http://www.opencart.com/8/9/2019 Create a Custom Theme With OpenCart
2/31
about tweaking the files all the time which contains the application logic and template
code together.
OpenCart proides really clean directory structure when it comes to organiation of the
framework. &ll the files related to the back-end interface are placed inthe admin directory. (iles dealing with front-end interface are placed in
the catalog directory. But what we are really interested in is the catalog directory as
eentually we will end up with the custom front-end theme at the end of this tutorial
series.
The OpenCart Design Pattern: MVCL
$odel %iew Controller, or $%C, is a ery popular design pattern in the field of software
deelopment. OpenCart )ust adds an another element to it*Language, which is why we
refer to it as $%C-+.
In our case, the view part is where we will place all the theme related code. In a uick
oeriew of the catalog structure, we will see how OpenCart does its magic.
8/9/2019 Create a Custom Theme With OpenCart
3/31
!"ements O#er#ie$
. Contro""er. It's responsible for handling the application logic.
. Language. It's useful for separating language specific information for multilingual sites.
/. Mode". It's responsible for fetching the data from back-end database.
0. Vie$. 1his is where we will spend most of our time# It's responsible for rendering the
front-end layout.
%etting &ami"iar With the Presentation La'er
& default OpenCart theme is aailable in view directory. 1his is the part which we will
explore in this section. &t the deeper leel, there are two more
directories* javascript and theme .
8/9/2019 Create a Custom Theme With OpenCart
4/31
(or now, let's )ust assume that all of the reuired 2aa3cript files are placed in
the javascript directory. 3ometimes there is an exception to this in which case we
can also place stylesheets and related image files under this directory, as well. (or
example, OpenCart proides the colorbox library which contains more than )ust
2aa3cript.
4hat we are really interested in is the theme directory. +ooking further, there is a
directory named default which is the only built-in theme proided by OpenCart. 5on't
get )ust oerwhelmed by the deeper theme structure as we'll explore that in more detail
soon. (or now, see what a theme's structure looks like.
De(au"t Theme Structure
. Image. &s you'e likely guessed, all the image files related to the theme go here.
. St'"esheet. 3kinning related code, which is likely to be stylesheets, will go here.
/. Temp"ate. &s the name suggests, you can find all the front-end template files here. &ll
the template files are organied in a modular way to keep things neat and clean.
(or example, if you gie a uick look at the account directory under template you will
see most of the files are related to user screens in the front-end. 4e'll look at this in
more detail in the next article.
8/9/2019 Create a Custom Theme With OpenCart
5/31
The Wor"d o( Temp"ates
&s I mentioned earlier OpenCart proides a nice way to organie template files. In this
article, I'll try explain what it looks like within the template directory. Before moing
ahead, it's worth noting that although OpenCart comes with a bunch of built-in modules
that proide the features reuired by a basic shopping cart, you can deelop your own
modules as well for your custom reuirements.
4ith that said, let's hae a closer look at the template categoriation.
&dertisement
Temp"ate Categori)ation
. Common*1emplate files for the common elements across different pages are placed in
this directory. 6xamples include header, footer, and sidebar related templates. 7ou
should also place your template files here if you plan to use that across different pages
8/9/2019 Create a Custom Theme With OpenCart
6/31
which makes it easier to maintainin the long run. Of course it's not mandatory to do so,
but it's nice to do the things the way itshould be done.
. !rror*&t the moment, it's )ust the error template which resides here.
/. In(ormation*7ou can find here templates related to Contact 8age, 3itemap 8age and
3tatic informational page.
0. Modu"e*It's an important directory in terms of the kind of templates it keeps. &s I said
earlier in OpenCart we can create our own custom module to fulfill our custom
reuirements so this is the place where you would like to put your template files related
to your custom module.
&part from the template structure explained aboe, there are still other template
directories that contain page-specific template files. In terms of OpenCart, we can say
that they are routespecific template files.
(or example, when you isit the 9$y &ccount9 page in the front-end, the template
associated with that should be found
under catalog/view/theme/default/template/account . +ater in the series, we'll see
how to find a specific template file looking at the url path of that page.
Summar'
1hat's the end of the first part of this series. 7ou should be familiar with the basic theme
structure of the OpenCart.
In the next part, we'll learn how to create a custom theme in the OpenCart. If you hae
any uestions or feedback, feel free to leae your comment#
we explored the basic theme structure of OpenCart. :ow, let's moe one step further
and learn how to can create a custom theme. If you haen't gone through the first part
of this tutorial series yet, read through it so that you understand where we're headed in
this article as we continue to build our own theme.
8/9/2019 Create a Custom Theme With OpenCart
7/31
OpenCart comes with the decent default theme which will sere as a base theme for our
new custom theme. ;enerally speaking, there are two scenarios in which you would
want to create your custom theme*
. 7ou want to replace the default front-end interface completely with a new interface of
your choice,
. 7ou would like to change couple of things like color combination, layout structure and
branding related changes.
In either case, I recommend creating a new custom theme instead of modifying the
default theme files directly as it'll make the life easier during the ersion upgrade of the
OpenCart.
Before proceeding, you should hae a working installation of OpenCart. If you haen't
done that, go ahead and set up the same.
Once done, let's get started#
Setting +p the Ske"eton
+et's create a new directory,
named mycustomtheme underneath catalog/view/theme . 1his will sere as a
container for the other files like images, stylesheets, and templates. (urthermore, you
need to create three more directories within the mycustomtheme
directory* image , stylesheet , and templates .
8/9/2019 Create a Custom Theme With OpenCart
8/31
7ou hae set up the basic skeleton structure needed for your custom theme once
you'e done with this. In fact, you can )ust go ahead and enable your custom theme
from the back-end and it'll workjustfine.
Acti#ate the ,e$ Theme
+et's go ahead and actiate your custom theme from the back-end. Once you're logged
in the back-end, go to System > Settings.It'll list out all the stores aailable in your
OpenCart installation.
8/9/2019 Create a Custom Theme With OpenCart
9/31
In most cases, it'll display a single store entry, but if you hae multiple stores set up,
you'll see more than a single row. OpenCart allows you to set up multiple stores using
single installation.
1his is really an important feature if you'e multiple stores and you don't want to set up
OpenCart installation for each and eery store. 7ou can manage all the stores using
single admin interface# $ulti-store set up is something out of the scope of this tutorial
but it's an important feature worth to explore.
Back to our business, click on the Editlink in theActioncolumn which should open the
store configuration interface.
8/9/2019 Create a Custom Theme With OpenCart
10/31
Click on the Storetab. 1his will open the configuration form that allows us to select a
front-end theme. 7ou should see that our custom theme, mycustomtheme , is also listed
along with the default theme in the 1emplate dropdown box. 3elect that and click
on Savebutton to apply our changes.
8/9/2019 Create a Custom Theme With OpenCart
11/31
:ow if you check the front-end, eerything is working fine. 4e haen't created a single
file in our custom theme yet - how does this work< 1hat's where template oerriding
comes into play.
+nderstand the Magic o( Temp"ate O#erriding
6en if we hae set up our new theme, mycustomtheme , as an actie theme of the
store, the front-end is still looking exactly like as it was before we enabled our new
theme from the back-end. 1his is due to the fact that the template oerriding system is
in place.
+et's take a look at a uick example so we can more easily understand this* 1o render
the home page, OpenCart uses template located
at catalog/view/theme/*/template/common/home.tpl . 1he asterisk here in the path
maps to the theme name. :ow OpenCart will execute following procedure in order to
find the home.tpl template*
&s we hae set up mycustomtheme as an actie theme for the store, first it will try to
find the file
at catalog/view/theme/mycustomtheme/template/common/home.tpl . If it's
found, OpenCart is happy and it will take that file and stop the process here.
If OpenCart can't find home.tpl in the actie theme, it will fallback to the default theme
and try to pull catalog/view/theme/default/template/common/home.tpl .
Obiously, it's guaranteed that home.tpl will be there unless you'e tyed with the
default theme template files#
OpenCart will always fallback to default theme wheneer it can't find the reuired
template file in the actie custom theme. 3o irtually we can say that it's
the default theme sering files at the moment een if mycustomtheme is in place.
8/9/2019 Create a Custom Theme With OpenCart
12/31
1his is really handy in the case where you only need to tweak few selected template
files. In that case, you would only copy those files to the custom theme directory to fulfill
the )ob.
!-tending the ."ank Custom Theme
It's an empty basket as far as our custom theme, mycustomtheme , is concerned. +ets
enrich it with some useful content.
;o ahead and create a new directory named common under the template directory of
our custom theme. :ow copy home.tpl and header.tpl template files from
the template/common directory of the default theme. 7ou should paste those files in
newly created common directory of our theme.
3imilarly, copy all the stylesheet files from the stylesheet directory of
the default theme and paste it under the stylesheet directory of our theme. =epeat
the same process for all the images under image directory although we'll ignore this
directory for now.
&t this point, your new theme directory tree should look something this like*
8/9/2019 Create a Custom Theme With OpenCart
13/31
1here are couple of important things to note here before we proceed further. 7ou should
only copy the template files to the custom theme that reuires customiation. 1he
reason is that the missing file will be always picked up from the default theme so
there's no need to keep the duplicate of the same file unless you need to modify it.
¬her thing to notice is that you should maintain the structureof the files similar to
the default theme specifically in the case of template files. &s you'e seen, we
created a common directory when we copied home.tpl and header.tpl files to
mimic the structure with the default theme.
(rom now on, I'll mention all the file paths relatie to our custom theme directory. ;oing
further, open the template/common/header.tpl file in your faorite text editor. 1he
code in this file is responsible for displaying header part throughout the site. If you look
8/9/2019 Create a Custom Theme With OpenCart
14/31
at the code closely, there are few stylesheet references hard coded to the >default?
theme.
+et's change it so it's fetched from the custom theme.
(ind the following code,
1
8/9/2019 Create a Custom Theme With OpenCart
15/31
12
13
14
8/9/2019 Create a Custom Theme With OpenCart
16/31
La'out Temp"ates
In terms of OpenCart, templates are called layouts. 7ou can imagine a layout template
is a decorator template that collects the content for the different areas of the page,
pushes that content into the layout, and then generates a complete page.
3lots may refer to elements like the header, the footer, a sidebar element, and module
content. (or nearly eery page in the store front-end, there's an associated layout
template that exists.
It's important to note that OpenCart also allows you to create layouts from the back-end
which is another way you can change the partial structure of the certain front-end
pages.
Su/Temp"ates
1his kind of template generates a slot for specific content. In a general scenario, the
content is generated by a sub-template and is pushed into the layout template. 1he
simplest example of this kind is template/common/header.tpl . It's responsible for
generating the header part for the eery page in the front-end.
&nd as we discussed earlier, OpenCart proides a nice way to organie template files
such that it makes sense that header.tpl is placed within the common directory. $ost
of the templates in this directory generate slot-specific content which is eentually
plugged into the layout.
Modu"e Temp"ates
=emember that a module is something like a block that is pushed to a specific region in
the layout template. &s you'e probably guessed, module templates these are related to
8/9/2019 Create a Custom Theme With OpenCart
17/31
different modules, and, as we'e seen, OpenCart comes with a lot of built-in modules to
extend the core functionality.
By default, there are four different region positions aailable in the layout template. 1hey
are*
. Content 1op
. Content Bottom
/. Column +eft
0. Column =ight
7ou can assign a module to any of these positions. &s the name suggests, if you hae
assigned a module to a 9Content 1op9 position, it'll be displayed aboe the main content
of the page. $odule templates are found within the template/module directory so if
you are creating a new module, you must place an associated template in this directory.
$odule templates and sub-templates are similar in the way that they are treated by
OpenCart. Both of these are considered as a child template and pushed to the layout
template in the process of page generation.
La'out Temp"ate Disco#er' in the &ront!nd
(irst, let's go through the process followed by OpenCart to render any page in the front-
end. 4heneer you access the page in the front-end, the following procedure is
executed by the application*
Based on the 9route9 ariable set in the @=+, OpenCart finds an appropriate controller to
handle the reuest. 4e'll see exactly what a 9route9 ariable is and what it does in a later
section. (or now, let's )ust assume that it guides OpenCart to an appropriate controller
file for execution.
8/9/2019 Create a Custom Theme With OpenCart
18/31
It's up to the controller now to do all the heay lifting for the rest of the process. 1he
controller is the place where other elements like language files and model files are
included. It also fetches and sets up the actual content to be pushed to the layout
template for the display.
Once the controller is done with content set up, it hands oer this information to a iew
element that is responsible for displaying the final output to the user. 1he important thing
to note here is that the controller also sets the layout template filename which will be
used by the iew at later stage.
(inally, a iew element pulls the reuired template file and decorates it with the content
which was prepared earlier in controller. 1he process ends here by sending the output to
the end user.
:ow consider a scenario in which you would like to change the layout structure of any
gien page in the store front-end. 1he first uestion that this raises is how do we go
about finding a template associated with that particular page, 1hough there's no
specificway to do this, let's take a look at some of the options that are aailable.
0* Prediction .ased on the Structure
1his is the easiest way to predict the associated template with any route. In the
terminology of OpenCart, 9route9 is a uery-string ariable in the link @=+.
(or example, consider the following link @=+ in the front-end which displays the login
page to the user*
http%//www.youropencartdomain.com/index.php?route=account/login .
3o in the aboe @=+, account/login is the alue of the 9route9 parameter which will
be useful to us. 7ou can simply map this alue to the template directory of the default
theme. In this case, the template path you end up with is something like*
0opencart#document#root1/catalog/view/theme/default/template/account/logi
n.tpl
8/9/2019 Create a Custom Theme With OpenCart
19/31
&s you may hae noticed, the second part of the 9route9 alue, 9login9, becomes the
template filename ! login.tpl in aboe case". +et's take an another example*
http%//www.youropencartdomain.com/index.php?
route=product/product2path=2product#id=
1his is the example of 9route9 parameter format for the product detail page. %alue of the
9route9 parameter is product/product , so the template for this route should be found
at*
0opencart#document#root1/catalog/view/theme/default/template/product/prod
uct.tpl
1* The %eek Wa'
In most of the cases, the way described aboe should work but there are few
exceptions in which case you'll need to look into the controller file. &gain, the route
parameter comes to the rescue which also helps to find an associated controller file.
+et's consider the link @=+ that displays the login page to the user in the front-end*
http%//www.youropencartdomain.com/index.php?route=account/login
7ou can map the alue of the route relatie to the catalog/controller to find an
associated controller file. 3o in this case, the controller file you should end up with is*
0opencart#document#root1/catalog/controller/account/login.php
&s you may hae noticed, the second part of the 9route9 alue, 9login9, becomes the
controller filename ! login.php in aboe case". Once you find an associated controller
file, you should look for the code something like*
this)template = default/template/account/login.tpl!
8/9/2019 Create a Custom Theme With OpenCart
20/31
1his is the way of controller to tell the OpenCart that it should display the 9login.tpl9
layout template from the 9default9 theme. &nd yes of course, if this template has been
oerridden in your custom theme, it'll be gien the first priority#
&mong the two methods discussed to find a layout template for any page, the first one
is more theme-deeloper friendly and the second one is for those who feel a bit more
comfortable digging into the code.
&dertisement
The Common !"ements o( the La'out Temp"ate
&t this point, you should feel a bit more comfortable finding a specific layout template
that you would like to customie. In the last section of this article, we'll catch a glimpse
of some of the usual elements in the layout template. 4e'll stick with our example for
the sake of this exercise.
+et's open the layout template file default/template/account/login.tpl for the
reference.
2headerdisplays the content of the header part in an OpenCart page. 1he template
related to this can be found at default/template/common/header.tpl .
2(ooterdisplays the content of the footer part in an OpenCart page. 1he template
related to this can be found at default/template/common/footer.tpl .
2co"umn3"e(tis responsible for displaying the output of all the modules assigned to
9Column +eft9 position from the back-end. 1he template related to this can be found
at default/template/common/column#left.tpl .
2co"umn3rightis responsible for displaying the output of all of the modules assigned to
the 9Column =ight9 position from the back-end. 1he template related to this can be
found at default/template/common/column#right.tpl .
8/9/2019 Create a Custom Theme With OpenCart
21/31
&n 9&ccount9 block displayed in the right sidebar of login page proides an example of
this kind of content. In the case in which you would like to customie the output of a
specific module, you should find that file at default/template/module/
0modulename.tpl1 .
In the case of the 9&ccount9 module, the file
is default/template/module/account.tpl . &s you can see, the naming conention of
the module template file is pretty easy to guess as it's exactly the same as the name of
module.
2content3topis responsible for displaying the output of all the modules assigned to
9Content 1op9 position from the back-end. 1he template related to this can be found
at default/template/common/content#top.tpl .
2content3/ottomis responsible for displaying the output of all the modules assigned to
9Content Bottom9 position from the back-end. 1he template related to this can be found
at default/template/common/content#$ottom.tpl .
8/9/2019 Create a Custom Theme With OpenCart
22/31
&t this point, you should feel confident in the exercise of customiing templates for
OpenCart's front-end. &s you may hae noticed, you need to modify ery few templatesin order to completely change the look and feel of the whole site.
Summar'
In this part, we'e thoroughly discussed the nature of templates and methods to
discoer the templates in front-end for customiation. 4e also discussed some of the
common ariables used in layout templates all oer the site.
In the final part of this series, we'll see a detailed use case to change the layout
structure of an OpenCart home page. 7our thoughts and comments are welcome in the
feed below#
8/9/2019 Create a Custom Theme With OpenCart
23/31
If you'e followed the series thus far, you should be able to find the location of home
page layout template. <hough a uick look at the templates here and there inside
9 Adefault9 theme should gie you a hint that it's located at
A default/template/common/home.tpl .
But if you may hae noticed the route of the home page, it contains the
alue 3common/home . 3o, as we discussed earlier, you can always map this route to
find the appropriate layout template file.
8/9/2019 Create a Custom Theme With OpenCart
24/31
+ooking at the A home.tpl file, you'll realie that most of the content is generated
ia the generic elements like header , footer etc. 4e won't discuss
the header and footer elements as you already know that the contents of those
ariables are coming from A header.tpl and A footer.tpl files underneath
template/common directory, respectiely.
In the case of default OpenCart home page, there are no modules assigned at the
9 AColumn +eft9 or 9 AColumn =ight9 position so you can say
that column#left and column#right ariables are not doing anything. 3o
eerything you see on the home page except for the header and footer, is coming from
either content#top orcontent#$ottom ariable. 9 A3lideshow9 and
9 A(eatured9 modules are assigned to 9 AContent 1op9 position and
9 ACarousel9 module is assigned to 9 AContent Bottom9 position to the
9 Aome9 layout.
:ow lets go further and see how exactly these modules are assigned to 9 Aome9
page layout.
Modu"e Assignment &rom the .ack!nd
;et logged into the back-end and go to 9 4 6xtensions $odules9 . 1his will list out
all the modules aailable in the system. :ow, click on the 9 4 6dit9 link for the
9 4 3lideshow9 module which will display the module assignment interface.
8/9/2019 Create a Custom Theme With OpenCart
25/31
<hough there is uite a bit of configuration aailable here,the important column for us
are 9 4 +ayout9 and 9 4 8osition9 . &s per the alues assigned there,9 4 3lideshow9 module will be displayed at 9 AContent 1op9 part in the
9 Aome9 layout.
(rom here, you can also assign a 9 4 3lideshow9 module to any layout at any
position using 9&dd $odule9 button. :ow let's take a look at an another example, on the
module listing page click on the 9 4 6dit9 link for the 9 4 (eatured9 module.
8/9/2019 Create a Custom Theme With OpenCart
26/31
&gain you can see that, the 9 4 +ayout9 and 9 4 8osition9 alues are same as that
of the 9 4 3lideshow9 module. 3o now you should be familiar with how exactly thesemodules are displayed in the home page. &s you may hae noticed that there is also
9 4 =emoe9 button aailable which is used to un-assign a module from the specific
layout. ;o ahead and explore the settings for 9 4 Carousel9 module yourseles#
5omepage La'out T$eaking
:ow that you are aware with how module is assigned and unassigned to a specific page
and position, we'll go through the same to tweak the home page layout. 2ump into the
admin section, and go to the 9 4 6xtension $odules9 to bring the module listing
page on the table.
In this step, we'll remoe all the assigned modules from the home page.
8/9/2019 Create a Custom Theme With OpenCart
27/31
Click on the 96dit9 link for the 93lideshow9 module. :ow, click on the 9=emoe9 button
to un-assign a module from 9ome9 layout. &fter that click on 93ae9 button to apply
the changes. =epeat the same procedure for the 9Carousel9 and 9(eatured9 modules.
&t the end of this step if you check your home page, you should see almost an empty
home page except 9header9 and 9footer9 parts. 5on't worry, that's what we really
intended to do# In the next step, we'll assign a bit different set of modules to 9 AColumn
+eft9 and 9 AColumn =ight9 positions in home page. +et's go to the module listing
page again.
Click on the 9 4 6dit9 link for the 9 4 Category9 module. &t the bottom right of the
page, you'll see an 9 A&dd $odule9 button, clicking upon which would add a new row
to the listing. In that row, in the 9 4 +ayout9 column select 9 Aome9 and in the 9 4 8osition9 column select 9 AColumn +eft9 . &fter that click on 9 4 3ae9
button to apply the changes.
Click on the 9 4 6dit9 link for the 9 4 &ccount9 module. Click on the 9 A&dd
$odule9 button to add a new row. In the newly added row, in the 9 4 +ayout9
column select 9 Aome9 and in the 9 4 8osition9 column select 9 AColumn
=ight9 . &pply your changes using the 9 4 3ae9 button.
3o now let's hae a look at our front-page*
8/9/2019 Create a Custom Theme With OpenCart
28/31
La'out &i"e Changes
3o far we hae done all the layout related tweaking from the back-end itself. In this
section, we'll add a bit of static text content to the A home.tpl . 4heneer you need to
add a static text in any template, instead of putting the text directly inside the template
you should follow the standard way of the OpenCart. +et's exercise the same.
Of course, you won't directly edit the A home.tpl file in the 9 Adefault9 theme, lets
oerride it in your custom theme#
;o ahead and open catalog/language/english/english.php . &dd the following
line at the end of the file )ust before the line which contains A ? .
1#4text#welcome5 = "6orem +psum is simply dummy text of the printing and ty
7''s, when an unknown printer took a galley of type and scram$led it to make a typ
8/9/2019 Create a Custom Theme With OpenCart
29/31
typesetting, remaining essentially unchanged. +t was popularised in the 89's with
pu$lishing software like :ldus ;ageaker including versions of 6orem +psum."!
:ow go ahead and open A catalog/controller/common/home.php . 4e'll include the
language ariable added in the english.php file in this controller file so it's aailable inthe A home.tpl file for display.
In 9 A home.php9 before the following line,
1 this)response)set-utputthis)render>>!
&dd this one,
1 this)data4welcome#text5 = this)language)gettext#welcome>!
1his will make sure that the welcome#text ariable is aailable in the layout template
file )ust like any other ariables. :ow the only thing remaining is to
include welcome#text in the home.tpl file. 3o your home.tpl should look like
this,
01
02
03
04
05
06
07
08
09
10
8/9/2019 Create a Custom Theme With OpenCart
30/31
I'e done ery few changes in this file. I'e added the
ariable welcome#text surrounded by
8/9/2019 Create a Custom Theme With OpenCart
31/31
Of course, that is something reuires a bit of knowledge of how OpenCart model works.
7ou're encouraged to go further and assign couple of more modules to the different
positions to see how things work.
Summar'
I hope this series helped you to understand what exactly OpenCart theme is all about
and how to customie the default theme with your own. 7ou can always shoot your
comments and uestions in the feed below.
Top Related