Creating a new theme

Table of Contents
How to create a design theme...............................................................................................................................................2
How to setup a new theme in administration area..........................................................................................................4
Adding custom stylesheets and js libraries (part I..........................................................................................................!
"sing #$% to change layout...............................................................................................................................................&
Changing $'TA section..................................................................................................................................................&
"nderstanding layout #$% files..........................................................................................................................................(
Introduction...................................................................................................................................................................(
%ayout ) page structure..................................................................................................................................................(
*eference name +alues)attributes,...............................................................................................................................-.
Action methods,...........................................................................................................................................................-4
%ayout bloc/s...............................................................................................................................................................22
"nderstanding .phtml files ..............................................................................................................................................2.
Introduction.................................................................................................................................................................2.
0older structure...........................................................................................................................................................2&
Appending basic changes to our templates..................................................................................................................21
Calling layout bloc/s using $agento functions.............................................................................................................22
e. Adding custom C33 and 43 files to a layout (part II...................................................................................................2(
5pening .phtml files in 6reamwea+er............................................................................................................................7
How to create a design theme
8arning, 65 95T 6":%ICAT' A9 '#I3TI9; TH'$'. <es= this would ma/e it slightly easier to create your new theme= but it will
also ma/e your new theme horribly incompatible with $agento updates. $any designers (including some major $agento design
companies did this for a long time= and left the $agento world in a bit of a mess when -.4 was released. Instead= use the >least impact?
approach= outlined in this article to ma@imiAe compatibility with updates.
The first step will be creating the folders for the new theme. 8eBll call your new design newCtheme. Create the following folders,
9ew folders,
1. /app/design/frontend/default/new_theme/ - our new theme
2. /app/design/frontend/default/new_theme/layout
3. /app/design/frontend/default/new_theme/templates
4. /skin/frontend/default/new_theme/ - our new skins folder
5. /skin/frontend/default/new_theme/css/
6. /skin/frontend/default/new_theme/images/
Also= create the following new files,
9ew files,
1. /app/design/frontend/default/new_theme/layout/local.ml
2. /skin/frontend/default/new_theme/css/local.css
0inally= add some boiler plate to local.@ml= so that local.css will get included,
local.@ml,
1. !"ml #ersion$%1.&% encoding$%'()-*%"+
2. !layout+
3.
4. !default+
5. !,-- -emo#e callouts and rarely used stuff --+
6. !remo#e name$%right.poll%/+
.. !remo#e name$%right.permanent.callout%/+
*.
/. !remo#e name$%left.permanent.callout%/+
1&. !,-- add the local stylesheet --+
11.
12. !reference name$%head%+
13. !action method$%add0ss%+
14. !stylesheet+css/local.css!/stylesheet+
15. !/action+
16. !/reference+
1.. !/default+
1*.
1/. !/layout+
A well coded theme should ha+e the following traits,
-. A single layout file= named local.@ml= where all layout updates are placed.
2. no layout files with the same name as any layout file in the base theme
.. no css files with the same name as any css file in the default s/in
4. no .phtml template files= e@cept for those that were modified to support the new theme. ("sually this number will be +ery small.
How to setup a new theme in administration area
After creating the folders we need to switch the theme from the administration area.
3tep -. ;o to 3ystem D Configuration D 6esign +ia the top na+igation bar
3tep 2. "nder >Themes? and in the >6efault? te@t field= type, newCtheme
3tep .. :ress the >3a+e config? button in the upper right corner
Adding custom stylesheets and js libraries (part I
Any additional e@ternal stylesheet files (css or ja+ascript)aja@ libraries (js that we want to include in our new project must be also
copied to the proper folders.
3tylesheets Copy the files to )s/in)frontend)default)newCtheme)css) folder. To lin/ these files in= you can either modify local.@ml to
add the new file= or add an import in local.css= li/e this,
1import url23my_new.css345
4a+ascript ) A4A# libraries Create a new folder under )js) named newCtheme and copy your files to it. If you are using ja+ascript libraries
then this is also a good place to put the library files.
The 4a+ascript files can be added to your theme by adding the following to local.@ml,
1. !"ml #ersion$%1.&% encoding$%'()-*%"+
2. !layout+
3. ...
4. !default+
5. ...
6. !reference name$%head%+
.. ...
*. !action method$%add6s%+
/. !script+#arien/7s.7s!/script+
1&. !/action+
11. ...
12. !/reference+
13. ...
14. !/default+
15. ...
16. !/layout+
"sing #$% to change layout
8ith the use of #$% we can change almost e+ery aspect of our newCtemplate. 0or e@ample we can set an alternate column layout for
particular pages= change $'TA information= page encoding= bloc/ types used on each page etc. To accomplish this= you will simply add
+arious sections to your local.@ml file. A good place to loo/ at to understand this is,
app/design/frontend/8ase/default/layout/page.ml
In -...@ and earlier= this is located at,,
app/design/frontend/default/default/layout/page.ml
Changing $'TA section
(IsnBt this section horribly obsoleteE The main file used to control +alues for $'TA tags and other miscelaneous details is config.@ml
which is located in the )app)design)frontend)newCtemplate)default)etc) folder.
Felow is a short description of e+ery $'TA tag and possible +alues,
!title+9agento 0ommerce!/title+
This is the name of our ecommerce site. This te@t will appear in the browserBs title bar or the browser tab for the site. This te@t is also
highly important for search engine /eyword optimiAation.
!media_type+tet/html!/media_type+
This is default page header encoding so we should lea+e this as is.
!charset+utf*!/charset+
"T02 is a +ariableGlength character encoding for "nicode. It is able to represent any character in the "nicode standard= yet the initial
encoding of byte codes and character assignments for "T0G2 is bac/wards compatible with the A3CII table. 0or these reasons= it is
steadily becoming the preferred encoding for eGmail= web pages= and other places where characters are stored or streamed.
5f course we can change it to any other encoding (e@. I35G22!(G- or I35G22!(G2 but there is no need as long as weBre sa+ing our
files with proper "T02 encoding.
$ore information about "T02 is in the 8i/i, http,))en.wi/ipedia.org)wi/i)"T0G2
!description+:efault :escription!/description+
The description tag controls the description meta tag and allows us to enter a short description about our site. ItBs often a way to get a
nice description of your page to show up in the search results if your page does ran/ highly in a search engine. <our best bet is to write
a succinct sentence or two that uses the /eyword phrases that sum up the page content.
!keywords+9agento; <arien; =-commerce!/keywords+
The /eywords tag controls the /eyword meta tag and is the place to put the most important words that refer to the site content. Fest
practices suggest to enter no more than !77 characters in no more than 27 words for best results.
!ro8ots+>!/ro8ots+
The robots tag controls the robots meta directi+e and is a simple mechanism to indicate to +isiting web bots and search engine spiders
if a page should be inde@ed= or lin/s on the page should be followed. The content of the *obots meta tag contains directi+es separated
by commas. The currently defined directi+es are inde@= noinde@= follow and nofollow. The two inde@ directi+es specify if an inde@ing
robot should inde@ the page or not. The two follow directi+es specify if a robot is to follow lin/s on the page or not. The defaults are
inde@ and follow. The +alues all and none set all directi+es on or off, allHinde@=follow and noneHnoinde@=nofollow 8e can simply
o+erride $agentoBs default directi+e by placing one of the four following lines here= howe+er itBs not recommended. The options are,
inde;follow
noinde;follow
inde;nofollow
noinde;nofollow
The file config.@ml also contains two additional tags= not connected with any meta tags but used as a default settings for e+ery page in
our shop.
!logo_src+images/logo.gif!/logo_src+
The logoCsrc tag sets up a reference to the logo file we wish to use on our site. The image logo.gif is located in the folder
)s/in)frontend)newCtemplate)default)images) so if we want to change it we must copy a new logo file to that folder. 8e can also
create a new folder inside the images folder (e@. newCimages and put all our new files used by new template into it and change this tag
appropriately. The easiest way to customiAe the logo it to simply o+erwrite the default logo.gif file with a new logo.gif file.
!logo_alt+9agento 0ommerce!/logo_alt+
The logoCalt tag defines the alt attribute for our logo image and is mostly used by screen readers or browsers with images disabled. If
one of our customers uses a screen reader or has images disabled he will see the alt te@t instead of image.
"nderstanding layout #$% files
Introduction
"sing @ml instead of other methods (4359= .ini files= include ) reIuire functions allows us to change many aspects on our page without
manually changing the .phtml files. This chapter refers to our default theme so after changing the theme (as we ha+e done abo+e the
paths will also change.
%ayout ) page structure
The core %ayout is defined by page.@ml which is located in
/app/design/frontend/8ase/default/layout/page.ml
There are two large tas/s layout carries out.
0irst it defines the +isual layout for your store. Fy default $agento uses a .Gcolumn layout= so it defines use of .columns.phtml
(%ocated in your template)page) folder,
!8lock type$%page/html% name$%root% output$%to?tml% template$%page/3columns.phtml%+
If you wanted to change your store a 2Gcolumn layout= for instance= you would reference this section in local.@ml= and use an action to
change to the .phtml youBd li/e to use (in this case= 2columnsGleft.phtml or 2columnsGright.phtml.
1. !reference name$%root%+
2. !action method$%set(emplate%+
3. !template+page/2columns-right.phtml!/template+
4. !,-- 9ark root page 8lock that template is applied --+
5. !action method$%set@s?andle%+
6. !applied+1!/applied+
.. !/action+
*. !/action+
<ou could also add a new custom layout,
1. !new_layout translate$%la8el%+
2. !la8el+Aew Bayout!/la8el+
3. !reference name$%root%+
4. !action method$%set(emplate%+
5. !template+page/new-layout.phtml!/template+
6. !/action+
.. !,-- 9ark root page 8lock that template is applied --+
*. !action method$%set@s?andle%+
/. !applied+1!/applied+
1&. !/action+
11. !/reference+
12. !/new_layout+
$ore information about the action tag and associated methods is located in section d of this chapter.
3econdly it creates >bloc/ containers? filled with application data for output to your .phtml template files. 0irst= if ta/e a loo/ at your
standard .column.phtml file youBll see it calls the method (function getChildHtml( a number of times,
(e@cerpt from .columns.phtml G 3tarting at line !&,
1. !"$Cthis-+get0hild?tml23header34"+
2. !/di#+!,-- DendE header --+!,-- DstartE middle F
3. !di# class$%main-container%+
4. !di# id$%main% class$%col-3-layout%+
5. !"$Cthis-+get0hild?tml238readcrum8s34"+
6. !,-- DstartE left --+
.. !di# class$%col-left side-col%+
*. !"$Cthis-+get0hild?tml23store34"+
/. !"$Cthis-+get0hild?tml23left34"+
1&. !/di#+
11. !,-- DendE left --+
'ach of these references point towards the >bloc/ containers? defined in your page.@ml and subseIuent $odule .@ml files. <ouBll notice
a container for the >left? column= for the >right?= for >content?= and other standard areas. It ser+es up output for your .phtml template
files to use. Ta/e a loo/ at it,
/app/design/frontend/default/default/layout/page.ml
1. !8lock type$%page/html_8readcrum8s% name$%8readcrum8s% as$%8readcrum8s%/+
2. !8lock type$%core/tet_list% name$%left% as$%left%/+
3. !8lock type$%core/messages% name$%glo8al_messages% as$%glo8al_messages%/+
4. !8lock type$%core/messages% name$%messages% as$%messages%/+
5. !8lock type$%core/tet_list% name$%content% as$%content%/+
6. !8lock type$%core/tet_list% name$%right% as$%right%+
3o basically page.@ml creates 6ata Floc/s= your .phtml 5utputs that data where you want it. Hence= the names for left= right and so
forth in your .phtml.
To add= remo+e= or modify bloc/s in your theme= use your local.@ml file= not a copy of page.@ml. The reference tag allows you to define
what part of the theme you are wor/ing with= then you can declare additional bloc/s= or use actions to modify or remo+e bloc/s.
<ouBre aware now that page.@ml contains a handle called >JdefaultD?. The #$% commands nested within the JdefaultD layout sets up
the default layout for the whole site. The subseIuent handles(as listed in the top of page.@ml= simply updates the default layout with
the according layout for the page.
1. !layout'pdate+
2. !reference name$%top.menu%+
3. !8lock type$%catalog/na#igation% name$%catalog.topna#%+
4. !action method$%set(emplate%+
5. !template+catalog/na#igation/top.phtml!/template+
6. !/action+
.. !/8lock+
*. !/reference+
/.
1&. !reference name$%right%+
11. !8lock type$%catalog/product_compare_side8ar% name$%catalog.compare.side8ar%+
12. !action method$%set(emplate%+
13. !template+catalog/product/compare/side8ar.phtml!/template+
14. !/action+
15. !/8lock+
16. !/reference+
If you read the code and thin/ about whats going on it ma/es sense. Jlayout"pdateD is ":6ATI9; your code with new bloc/s. How
does it /now where to put the new bloc/sE 8ell remember in your default you defined >bloc/ containers? for left= right= etc. 3o when it
says
!reference name $ %right%+
itBs telling $agento to insert the following bloc/ into the *I;HT column when you get into >Catalog? +iew. (*emember= its located at
layout)catalog) so it appears once youB+e entered the catalog section of the shop. It also defines a T'$:%AT' for the new bloc/ to use=
so for the e@ample abo+e the compare bo@ has its own template located at catalog)product)compare)sidebar.phtml (in your template
folder.
These same handles can be used in local.@ml to restrict the scope of a particular update.
0or instance= letBs say you want a wishlist e+erywhere in your store= but you donBt want it in the customer account pages. <ou would
loo/ for the handle used on account pages (it is in customer.@ml and add that handle to local.@ml. Then remo+e the wishlist so it does
not load in the account pages.
The e@ample below remo+es >%ogin? and adds >*egister? instead= but only if the customer is not already logged in,
1. !customer_logged_out+
2. !reference name$%top.links%+
3. !action method$%remo#eBinkGy'rl% module$%catalog%+
4. !url helper$%customer/getBogin'rl% /+
5. !/action+
6. !action method$%addBink% translate$%la8el title% module$%customer%+
.. !la8el+-egister!/la8el+
*. !url helper$%customer/get-egister'rl%/+
/. !title+-egister!/title+
1&. !prepare/+
11. !urlHarams/+
12. !position+1&&!/position+
13. !/action+
14. !/reference+
15. !/customer_logged_out+
*eference name +alues)attributes,
As weB+e seen= the references can use different attributes for displaying bloc/s on our page. :ossible +alues are,
root G we will change it mostly to set up another .phtml file as a root template e@. (-column.phtml = 2columnsGleft.phtml =
2columnsGright.phtml etc.
head G as this reffers to our JH'A6D section on page= we will use this reference name to reflect our changes in this section
top.menu G defines our content for top menu section
left G defines our content for left column
right G as abo+e but for right column
content G defines bloc/s placed in main content of our page
beforeCbodyCend G is used to add a bloc/ before end of our page so before J)F56<D
There are more reference names that we could use but they are more pageGspecific than for global use for e@ample,
customerCaccountCna+igation
customerCaccountCdashboard
are used on our clients account page
product.info.additional G sets up additional bloc/ for placing related items= shipping estimator etc.
Action methods,
Action methods allow us to change many theme settings without appending manual changes to our .phtml files. The method listed in
the method attribute refers to a method in the $odel that is associated with the particular bloc/ in Iuestion. The most important
methods are described below.
setTemplate
Action method setTemplate allows us to change the default .phtml file used in particular bloc/. 0or e@ample by na+igating to
app)design)frontend)default)default)layout)catalog)product)+iew.@ml we can see the reference,
1. !reference name$%root%+
2. !action method$%set(emplate%+
3. !template+page/2columns-right.phtml!/template+
4. !/action+
5. !/reference+
and by using another JtemplateD +alue we are allowed to change default .phtml file used on our products page. :ossible +alues are,
-column.phtml
2columnsGleft.phtml
2columnsGright.phtml
.columns.phtml
oneGcolumn.phtml
dashboard.phtml
As we see in app)design)frontend)default)default)layout)chec/out)cart.@ml = there also additional 2 +alues for empty and nonGempty
cart
1. !action method$%set0art(emplate%+
2. !#alue+checkout/cart.phtml!/#alue+
3. !/action+
4.
5. !action method$%set=mpty(emplate%+
6. !#alue+checkout/cart/no@tems.phtml!/#alue+
.. !/action+
2.
/. !action method$%choose(emplate%/+
The method chooseTemplate is used to set a template (setCartTemplate ) set'mptyTemplate depending on Iuantity of items in our
cart. If we ha+e more than 7 than the
1. !action method$%set0art(emplate%+
2. !#alue+checkout/cart.phtml!/#alue+
3. !/action+
is used. If we ha+e no items in cart then the following will be used.
1. !action method$%set=mpty(emplate%+
2. !#alue+checkout/cart/no@tems.phtml!/#alue+
3. !/action+
The function pro+ided by the $odel is shown below,
1. pu8lic function choose(emplate24
2.
3. I
4. if 2Cthis-+getJuote24-+has@tems244 I
5.
6. Cthis-+set(emplate2Cthis-+get0art(emplate2445
..
*. K else I
/.
1&. Cthis-+set(emplate2Cthis-+get=mpty(emplate2445
11. K
12. K
That should clarify how we can use this particular switch. 6epending on our needs we can write custom functions in our bloc/s and
than assign a template depending on parameters returned by a function.
addCss
This method allows us to add an additional C33 file to our page on perGpage basis or globally for our template. If we use a reference
name >head? and action method addCss by using
1. !reference name$%head%+
2. !action method$%add0ss%+!link+style.css!/link+!/action+
3. !/reference+
then our page will ha+e an additional line of code to attach the C33 file= for e@ample,
1. !link rel$%stylesheet% type$%tet/css% media$%all%
href$%httpL//www.ourstore.com/skin/frontend/default/default/css/style.css% +!/link+
As we can see= the Jlin/D path refers to the )s/in)frontend)default)default)css) folder.
addCssIe
This method is +ery similar to the abo+e but it will output a css file when a "serGAgent (browser is Internet '@plorer or $a@thon. 3o
using this method we can attach a specific css file for those browsers. This is +ery helpful if our page will reIuires changes in css
dependant on a specific browser.
"sage,
1. !reference name$%head%+
2. !action method$%add0ss@e%+!link+style.css!/link+!/action+
3. !/reference+
5utput in page source,
1. !,--Dif @=E+
2. !link rel$%stylesheet% type$%tet/css% media$%all%
href$%httpL//www.ourstore.com/skin/frontend/default/default/css/style.css% +!/link+
3. !,DendifE--+
add4s
The below method allows us to attach a .js script in the same way as we attached a C33 file. The script path refers to the )js)test) folder
but you can specify any subdirectory of )js)
"sage,
1. !reference name$%head%+
2. !action method$%add6s%+test/script.7s!/action+
3. !/reference+
It will add a script to our page with src attribute of
1. !script src$%httpL//www.ourstore.com/7s/test/script.7s% /+
add4sIe G adding a .js file to head section of page and using it if "ser Agent (browser is Internet '@plorer.
If we can add different css files depending on "serGAgent we can do the same with our .js files. Than we can use different scripts for
our I')$a@thone users and another for other browsers.
"sage,
1. !reference name$%head%+
2. !action method$%add6s@e%+our/script.7s!/action+
3. !/reference+
It will add a script to our page with src attribute of
1. !script src$%httpL//www.ourstore.com/7s/our/script.7s% /+
but also inside I' comments
1. !,--Dif @=E+!,DendifE--+
setContentType
This method can o+erride default headers sent by our page to the browser. 3o we can set a te@t)@ml instead of te@t)html (or another as
we wish.
"sage,
1. !reference name$%head%+
2. !action method$%set0ontent(ype%+!content+tet/ml!/content+!/action+
3. !/reference+
setCharset
allows us to o+erride default page encoding on perGpage basis or globally. As long as we are sa+ing our files with proper encoding this
will not be necessary.
"sage,
1. !reference name$%head%+
2. !action method$%set0harset%+!charset+@MN-**5/-2!/charset+!/action+
3. !/reference+
3o in this case our page will ha+e Central 'uropean encoding instead of default "T0G2
add%in/
add%in/ methods can be used to set a setting to which we can refer in our .phtml template files also without manually changing the
.phtml files.
'@ample usage ,
8arning= this e@ample reIuires account.@ml to be duplicated= which can brea/ things after updates. 3omeone should rewrite this to use
local.@ml instead. Fy adding a bloc/ which was found in app)design)frontend)default)default)layout)customer)account.@ml into our
Jreference nameH?content?D in app)design)frontend)default)default)layout)chec/out)cart.@ml we can allow the customer to s/ip to
the account information directly from the cart.
!8lock type$%customer/account_na#igation% name$%customer_account_na#igation% 8efore$%-%+
!action method$%set(emplate%+
!template+customer/account/na#igation.phtml!/template+
!/action+
!action method$%addBink% translate$%la8el%+
!name+account!/name+
!path+customer/account/!/path+
!la8el+Occount :ash8oard!/la8el+
!/action+
!action method$%addBink% translate$%la8el%+
!name+address_8ook!/name+
!path+customer/address/!/path+
!la8el+Oddress Gook!/la8el+
!/action+
!action method$%addBink% translate$%la8el%+
!name+account_edit!/name+
!path+customer/account/edit/!/path+
!la8el+Occount @nformation!/la8el+
!/8lock+
The cart.@ml file should loo/ li/e below
1. !layout'pdate+
2. !reference name$%root%+
3. !action method$%set(emplate%+
4. !template+page/1column.phtml!/template+
5. !/action+
6. !/reference+
..
*. !reference name$%content%+
/. !8lock type$%customer/account_na#igation% name$%customer_account_na#igation% 8efore$%-%+
1&. !action method$%set(emplate%+
11. !template+customer/account/na#igation.phtml!/template+
12. !/action+
13.
14. !action method$%addBink% translate$%la8el%+
15. !name+account!/name+
16. !path+customer/account/!/path+
1.. !la8el+Occount :ash8oard!/la8el+
1*. !/action+
1/.
2&. !action method$%addBink% translate$%la8el%+
21. !name+address_8ook!/name+
22. !path+customer/address/!/path+
23. !la8el+Oddress Gook!/la8el+
24. !/action+
25.
26. !action method$%addBink% translate$%la8el%+
2.. !name+account_edit!/name+
2*. !path+customer/account/edit/!/path+
2/. !la8el+Occount @nformation!/la8el+
3&. !8ase+II8aseMecure'rlKK!/8ase+
31. !/action+
32. !/8lock+
33.
34. !8lock type$%checkout/cart% name$%checkout.cart%+
35. !action method$%set0art(emplate%+
36. !#alue+checkout/cart.phtml!/#alue+
3.. !/action+
3*.
3/. !action method$%set=mpty(emplate%+
4&. !#alue+checkout/cart/no@tems.phtml!/#alue+
41. !/action+
42.
43. !action method$%choose(emplate%/+
44.
45. !8lock type$%checkout/cart_coupon% name$%checkout.cart.coupon% as$%coupon%+
46. !action method$%set(emplate%+
4.. !template+checkout/cart/coupon.phtml!/template+
4*. !/action+
4/. !/8lock+
5&.
51. !8lock type$%checkout/cart_shipping% name$%checkout.cart.shipping% as$%shipping%+
52. !action method$%set(emplate%+
53. !template+checkout/cart/shipping.phtml!/template+
54. !/action+
55. !/8lock+
56.
5.. !8lock type$%checkout/cart_crosssell% name$%checkout.cart.crosssell% as$%crosssell%+
5*. !action method$%set(emplate%+
5/. !template+checkout/cart/crosssell.phtml!/template+
6&. !/action+
61. !/8lock+
62. !/8lock+
63. !/reference+
64. !/layout'pdate+
5f course according to the pre+ious references we can also change
1. !action method$%set(emplate%+
2. !template+page/1column.phtml!/template+
3. !/action+
in the abo+e code to suit our needs. IB+e used for e@ample
1. !action method$%set(emplate%+
2. !template+page/one-column.phtml!/template+
3. !/action+
to show only our cart without other bloc/s.
%ayout bloc/s
As weB+e seen before= most of our @ml files ha+e a Jbloc/D tag. It defines a type of bloc/= its name and alias >as? so we can refer to it
on our page. Fasic bloc/ structure loo/s li/e this,
1. !8lock type$%catalog/product_#iew_super_config% name$%product.info.config% as$%super_config%+
2. !action method$%set(emplate%+
3. !template+catalog/product/#iew/super/config.phtml!/template+
4. !/action+
5. !/8lock+
typeH?catalog)productC+iewCsuperCconfig? G defines the type of our bloc/ on page. This e@ample would refer to the file
)app)code)core)$age)Catalog)Floc/):roduct)Kiew)3uper)Config.php which defines the class
$ageCCatalogCFloc/C:roductCKiewC3uperCConfig nameH?product.info.config? G defines a name for our bloc/ and should be uniIue
asH?superCconfig? G defines a shortname for our bloc/ which can we use with getChild function on particular page
Floc/s used in our #$% files can change or o+erride most e+ery aspect of our design. 8e can use them to simply change used phtml
files on perGpage basis= to add additional scripts= stylesheets to our page = to mo+e particular sections of page without needing to
change phtml files.
"nderstanding .phtml files
Introduction
:html files are template files that handle the output to browser. They are nothing more than html files with nested php tags. 8e use
them to style our page and the loo/ of our site.
Changing .phtml files reIuires basic /nowledge about #HT$%= C33 and understanding how to use :H: functions on a page.
I$:5*TA9T, Fefore changing a .phtml file= it has to be copied from the base (or default theme= into the new theme. 8hen $agento
finds one of these files in your new theme= it will ignore the .phtml file from the base theme= so it is important to 59%< copy o+er the
files that you absolutely need to modify. This will minimiAe errors when updating $agento. The additional effort reIuired to indi+idually
copy the 4G! files you e+entually modify will more than ma/e up for itself the first time $agento needs to be updated.
%etBs ha+e loo/ at header.phtml placed in templates)page)html.
1. !di# class$%header-top-container%+
2.
3. !di# class$%header-top%+
4.
5. !h1 id$%logo%+
6. !a href$%!"$Cthis-+get'rl2334"+%+
.. !img src$%!"$Cthis-+getBogoMrc24"+% alt$%!"$Cthis-+getBogoOlt24"+%/+
*. !/a+
/. !/h1+
1&. !p class$%no-show%+!a href$%Pmain%+!strong+!"$__23Mkip to main content34"+ QraRuo5!/strong+!/a+!/p+
11. !di# class$%Ruick-access%+
12. !di# class$%account-access%+
13. !strong+!"$Cthis-+getSelcome24"+!/strong+ !"$Cthis-+get0hild?tml23topBeftBinks34"+
14. !/di#+
15.
16. !di# class$%shop-access%+
1.. !"$Cthis-+get0hild?tml23top-ightBinks34"+
1*. !/di#+
1/.
2&. !/di#+
21.
22. !/di#+
23.
24. !/di#+
25. !"$Cthis-+get0hild?tml23top9enu34"+
In this file we see basic #HT$% tags= usage of C33 classes but most important G $agento functions used to get layout #$% bloc/s and
render it in our phtml file.
$ostly in our template weBll see JE ED tags used for functions calls. Fasing on abo+e e@ample, JEHLthis get"rl(BMED G used without
parameters will return base path of our store JEHLthis get%ogo3rc(ED G will render a logo image based on path used in
etc)config.@ml JlogoCsrcDimages)logo.gifJ)logoCsrcD
If weBd li/e to change our logo we can do this in two ways. 0irst possibility is to change JlogoCsrcD path to anything else. 3econd
possibility is to hardcode the path directly in phtml file so
1. !img src$%!"$Cthis-+getBogoMrc24"+% alt$%!"$Cthis-+getBogoOlt24"+%/+
but this resolution isnBt recommended since we should use core functions and learn their usage.
JEHLthis get%ogoAlt(ED G this function will allow us to change the alt tag for our logo so if it will be una+ailable = the alt tag will
appear. Any changes we can also append by changing JlogoCaltD$agentso CommerceJ)logoCaltD or setting it direclty in phtml file up.
JEHCC(3/ip to main contentED G all tags that loo/ li/e this will be used to dynamically translate page content to other languages. 8e
should understand it as JEHCC(N'nglish te@t to translateNED
JEHLthis getChildHtml(Btop%eft%in/sBED G The getChildHtml( function is the most important function used in our template. It calls
particular bloc/ defined in #$% file and renders it as HT$% = then outputs it to the browser. 8e can call bloc/s from e+erywhere and
from corresponding #$% files.
To use getChildHtml(Btop%eft%in/sB we must ha+e defined first the child >as? so ta/e a closer loo/ at page.@ml (layout) folder. HereBs
what you should see,
1. !8lock type$%page/html_toplinks% name$%top.left.links% as$%topBeftBinks%/+
As we see= getChildHtml(Btop%eft%in/sB uses its alias >as? and calls it from the #$%. The getChildHtml( function only allows $agento to
call a bloc/ if that bloc/ was defined in the corresponding #$% file.
8e can also o+erride this mechanism by using another function call,
!"$CthisFgetBayout24FgetGlock2Ttop.left.linksT4Fto?tml24"+
This structure will call the top.search bloc/ (based on its name= not its alias >as? from anywhere in any of our templates so we do not
need to define it e+erywhere in our #$% files. *emember to use the >name? attribute instead of the >as? attribute with this wor/around.
8e must be aware that e+ery phtml file and e+ery function will always refer to the corresponding #$% file or files. 8e can identify used
phtml files simply by searching for the following,
1. !action method$%set(emplate%+!template+wishlist/side8ar.phtml!/template+!/action+
which tells us which phtml file will be used.
0older structure
'+ery Kiew used in our application has separate folders and subfolders to store template files. %etBs ha+e a loo/ at the folder structure,
callouts G folder where are files for our callouts and ads are placed
catalog G folder to store files used on our category= layered na+igation= product= comparision pages
catalogsearch G here we find files that are used to s/in our search engine and result pages
chec/out G all the pages utilised during chec/out and shopping in our shop. Here weBll also find the shopping cart templates
and bloc/s for crossGselling and coupons.
cms G folder for static pages templates.
core G folder containing storeGswitching templates (not yet acti+e
customer G all customer pages (e@. account dashboard= address forms= orders list and re+iews
datafeed G folder to store our cs+= t@t= @ml files= used for comparision engines and other e@ternal applications
directory G here we find currency switcher for our shop
email G here weBll find all pages that reIuire email transport so for e@ample order= password reco+ery= newsletter signup
install G template files for $agentoBs installer
newsl etter G subscribe.phtml placed in this folder will allow us to change the loo/ of newsletter signup bo@ on our page
page G the most important folder in which weBll find all main files used to style our site. $ore about it will be described in
following subchapter.
payment G templates used to style our payment forms (e@. CC payment.
poll G 2 files to change the loo/ of our poll depending on state (didnBt +ote yet ) show result
rating G rating bloc/ used on our products pages
re+iew G all files used to render the bloc/s used by re+iews
sales G pages for order details= in+oices= recent orders
searchlucene G result output for OendC%ucene controller used in $agento
tag G product tags templates are stored here
wishlist G template files to handle the output of our wishlist actions.
Appending basic changes to our templates
'+ery file used to s/in the basic loo/ of our template is placed in template)page folder. Here weBll see
-column.phtml 2columnsGleft.phtml 2columnsGright.phtml .columns.phtml oneGcolumn.phtml dashboard.phtml
These are essentially the HT$% s/eleton files for our pages. Fy changing those files we can set up a new loo/ of the page structure.
There is also an html subfolder placed under template)page in which we can change footer= header and lin/s bloc/s of our template.
'+ery one of them uses simple function calls (e@. getChildHtml( so we can also identify the bloc/ by searching in layout #$% files .
0or e@ample when weBll see
1. !reference name$%root%+
2. !action method$%set(emplate%+
3. !template+page/2columns-right.phtml!/template+
4. !/action+
5. !/reference+
this tells us that the page will use 2columnsGright.phtml as a s/eleton for our page.
Calling layout bloc/s using $agento functions
As it was described abo+e= there are two ways of calling bloc/s .
!8lock type$%page/html_toplinks% name$%top.left.links% as$%topBeftBinks%/+
JEHLthis getChildHtml(BasBED G by using the bloc/ alias >as? from the #$% file we can display a bloc/ on our page pro+iding that it
was defined already in the corresponding #$% file
JEHLthis get%ayout( getFloc/(BnameB toHtml(ED G by using the bloc/ name from the #$% file= we can call any bloc/ whether or
not it was already defined in corresponding #$% file
e. Adding custom C33 and 43 files to a layout (part II
There are 2 ways of adding custom js and css files to our template. The recommended way is by e@tending the head section in the
default #$% file. Fut you also ha+e the ability to add the files directly in the particular root template file.
1. !script type$%tet/7a#ascript% src$%!"$Cthis-+get6s'rl24"+#arien/7s.7s% +!/script+
2. !script type$%tet/7a#ascript% src$%!"$Cthis-+get6s'rl24"+#arien/form.7s% +!/script+
3. !script type$%tet/7a#ascript% src$%!"$Cthis-+get6s'rl24"+#arien/menu.7s% +!/script+
As we see here = we can also use get4s"rl method which adds a scripts path to our src attribute. This should output
http,))yoursite.com)js) so the source will loo/ li/e the following,
1. !script type$%tet/7a#ascript% src$%httpL//yoursite.com/7s/#arien/7s.7s% +!/script+
2. !script type$%tet/7a#ascript% src$%httpL//yoursite.com/7s/#arien/form.7s% +!/script+
3. !script type$%tet/7a#ascript% src$%httpL//yoursite.com/7s/#arien/menu.7s% +!/script+
Adding a css file isnBt harder than adding a js file. 8e do this also by using a function that outputs a path to our s/ins folder.
1. !link rel$%stylesheet% href$%!"$Cthis-+getMkin'rl23css/styles.css34"+% type$%tet/css% media$%all%/+
And the output will be
1. !link rel$%stylesheet% href$%httpL//yoursite.com/skin/frontend/default/default/css/styles.css% type$%tet/css%
media$%all%/+
so get3/in"rl( sets actual path to our s/ins folder , http,))yoursite.com)s/in)frontend)default)default)
5pening .phtml files in 6reamwea+er
Fy default= 6reamwea+er cannot read :HT$% files. <ou can add the file type to the >5pen in Code Kiew? section of the preferences if you
wish to ha+e fast access= howe+er you cannot +iew the file in design +iew if you do that. 3o if you use 6reamwea+er (+ersions 4= $#=
$#2774= 2= or (= a/a C3. to design your sites= and you wish to open $agentoBs Template files (they ha+e .phtml e@tensions in
6reamwea+er= you can follow these steps to add support for .phtml and ma/e 6reamwea+er render :H: code (with coloring= hinting= et
al as well as allow you to see the design in code +iew if desired. Felow are three steps to follow.P
I$:5*TA9T 95T'3, This guide is for 6reamwea+er on 8indows (#: or Kista or $ac 53 #. 9ote, I ha+e e@cluded +ersion numbers from
the file locations shown= and if you are using a +ersion older than 6reamwea+er ( (C3. replace >Adobe? with >$acromedia? in the file
locations shown. 3ome spaces ha+e also been remo+ed to /eep the references on one line.
P 6reamwea+er 4 users, if you are using the archaic 6reamwea+er 4= you only need to follow step one. Howe+er= itBs highly
recommended that you just upgrade to +ersion 2 or newer for superb C33 and 8eb 3tandards support.
3tep 5ne, Add .phtml to the e@tension.t@t configuration file
5pen the following e@tension configuration file in a notepad and change the lines as specified below,
#:= Kista, C,:rogram 0ilesAdobe6reamwea+erConfiguration'@tensions.t@t
$ac 53 #, Applications D Adobe 6reamwea+er C3. D configuration D '@tensions.t@t In the first line add :HT$% li/e so,
HT$=HT$%=3HT$=3HT$%= ... =T#T=:H:=:H:.=:H:4=:H:!=:HT$%=43:=8$%=T:%= ... =$A3T'*,All 6ocuments
In the :H: 0iles line add :HT$% li/e so,
:H:=:H:.=:H:4=:H:!=:HT$%=T:%=:HT$%,:H: 0iles
3tep Two, Add .phtml to e@tension.t@t in your Application 6ata
This file is pretty much e@actly li/e the e@tensions.t@t file located in 6reamwea+erBs configuration folder= e@cept it is in your users
Application 6ata folder (App6ata folder for Kista users. 4ust as in 3tep 5ne= find the file and change the lines as specified below.
#:, C,6ocuments and 3ettingsQuserRApplication 6ataAdobe6reamwea+erConfiguratione@tensions.t@t
Kista, C,"sersQuserRApp6ata*oamingAdobe6reamwea+erConfiguration'@tensions.t@t
$ac 53 #, "sers D %ibrary D Application 3upport D Adobe D 6reamwea+er ( D Configuration D '@tensions.t@t
In the first line add :HT$% li/e so,
HT$=HT$%=3HT$=3HT$%= ... =T#T=:H:=:H:.=:H:4=:H:!=:HT$%=43:=8$%=T:%= ... =$A3T'*,All 6ocuments
In the :H: 0iles line add :HT$% li/e so,
:H:=:H:.=:H:4=:H:!=:HT$%=T:%=:HT$%,:H: 0iles
3tep Three, Add :HT$% to $$6ocumentTypes.@ml
This file is an #$% file which should be located in,
C,:rogram 0ilesAdobe6reamwea+erConfiguration6ocumentTypes$$6ocumentTypes.#$%
$ac 53 #, Applications D Adobe 6reamwea+er C3. D configuration D 6ocumentTypes D $$6ocumentTypes.#$%
Add :HT$% to this line (appro@. line 1! twice= li/e so,
1. !documenttype id$%H?H_9yMJB% ser#ermodel$%H?H 9yMJB% internaltype$%:ynamic%
winfileetension$%php;php3;php4;php5;phtml% macfileetension$%php;php3;php4;php5;phtml% file$%:efault.php%
write8yteordermark$%false% /+
*estart or 5pen 6reamwea+er and you shouldnBt ha+e any problems with :HT$% files any longer.