Create a Custom Theme With OpenCart

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/


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.


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 .


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.


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


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.


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


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.


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.


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.


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*


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.

&nother 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


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


15/31

12

13

14


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


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.


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


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!


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 .


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 .


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#


23/31

If you'e followed the series thus far, you should be able to find the location of home

page layout template. &lthough 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.


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.


25/31

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


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.


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*


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


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


30/31

I'e done ery few changes in this file. I'e added the

ariable welcome#text surrounded by


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.

Create a Custom Theme With OpenCart

Documents

Transcript of Create a Custom Theme With OpenCart