matty.co.za » Magento Themes http://matty.co.za Web developer, WordPress enthusiast, avid musician, music lover and blogger Thu, 26 Jan 2012 18:06:55 +0000 en hourly 1 http://wordpress.org/?v=3.3.1 Theming for Magento — Part 04 – How it all works http://matty.co.za/2010/04/magento-themes-part-04/ http://matty.co.za/2010/04/magento-themes-part-04/#comments Sun, 25 Apr 2010 08:42:15 +0000 Matty http://matty.co.za/?p=917 Wow, part 4 already? This is where the real fun comes in, folks. Today we’ll be opening up some *.phtml and *.xml files, looking at what’s going on under the hood and finding out how the theme files all tie together. Lets get started, shall we?

Before we get to those files…

Folks, before we dive into the files, lets get some concepts down that are crucial to understanding how the Magento theme files play together.

Magento themes consist of, aside from styling assets (CSS, images, Javascript, etc) a collection of *.phtml (essentially, XHTML files that can execute PHP) and *.xml (Extensible Markup Language) files that make the theme work.

The *.xml files define blocks and regions, which template files get used for which blocks & regions as well as various attributes and parameters for each if these definitions, where applicable.

While the *.xml files tell everything where to be and what to look like, the *.phtml files contain the actual XHTML code required for each block and region.

  • At the time of writing this tutorial, I have upgraded my Magento installation to Community Edition 1.4. All further tutorials, as well as this one, will be  referencing Magento Community Edition 1.4 unless otherwise stated. Please be sure you have the latest version.

Blocks and regions? Huh?

Yes, blocks and regions.

Magento has a system called “Static Blocks”, which allows theme authors to define areas which are updatable via the administration console using a simple textarea. This is used, by default, in the footer as well as for one or two other areas, and can be very  useful for allowing the theme users to update small chunks of content on their store. These are referred to in this tutorial as “blocks”.

Regions. This is where we need to get conceptual.

The easiest way I’ve found to explain this concept is by comparing regions to widgetised areas in WordPress. When users create widgetised areas in WordPress, they are creating areas that are open for the user to insert blocks of content (widgets) that will take on appropriate styling. The region concept is similar.

In Magento, by default, certain blocks are placed in certain regions (for example, Layered Navigation in the left column). This is the reason why it is so important to make use of all possible template types when theming for Magento (3 columns, 2 columns, 1 column, etc), as there is a tried and tested reason why each block is placed in a particular region. This can, however, be modified via the *.xml file (which does all the “do this, do that”, remember?), so its not a major worry if you need to move a block.

So, what’s a *.phtml file anyway?

A *.phtml file is a template file. It can either define a page template to be used when displaying a particular type of page (product page, category page, CMS page, etc) or a template to be used in a particular area, for example, the way each single product is displayed when a category is in list mode or grid mode, or the way your footer links static block (activated by default when Magento is installed) is displayed within your theme.

Lets take a look at a fairly standard *.phtml file, 2columns-right.phtml, found in your theme’s directory within the “app > design” folder.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->getLang() ?>" lang="<?php echo $this->getLang() ?>">
<head>
<?php echo $this->getChildHtml('head') ?>
</head>
<body<?php echo $this->getBodyClass()?' class="'.$this->getBodyClass().'"':'' ?>>
<?php echo $this->getChildHtml('after_body_start') ?>
<div class="wrapper">
    <?php echo $this->getChildHtml('global_notices') ?>
    <div class="page">
        <?php echo $this->getChildHtml('header') ?>
        <div class="main-container col2-right-layout">
            <div class="main">
                <?php echo $this->getChildHtml('breadcrumbs') ?>
                <div class="col-main">
                    <?php echo $this->getChildHtml('global_messages') ?>
                    <?php echo $this->getChildHtml('content') ?>
                </div>
                <div class="col-right sidebar"><?php echo $this->getChildHtml('right') ?></div>
            </div>
        </div>
        <?php echo $this->getChildHtml('footer') ?>
        <?php echo $this->getChildHtml('before_body_end') ?>
    </div>
</div>
<?php echo $this->getAbsoluteFooter() ?>
</body>
</html>

The above code is a direct copy/paste of the 2columns-right.phtml file, packaged with the base > default theme in Magento 1.4. The use of $this->getChildHtml() is directed at retrieving specific template files, declared within the page.xml file. The other functions, getAbsoluteFooter() and getBodyClass() are, for the scope of this tutorial, not relevant.

… and the XML?

This file defines our regions, sets up blocks within those regions and tells each region which template to use. It is also used for loading theme-specific CSS and JavaScript, as well as activating and deactivating blocks within specific regions in particular sections of your Magento theme. Essentially, the XML file controls everything related to the module in question.

In most cases, the majority of your time when theming will be spent within page.xml. As this file is well and truly gigantic for pasting into a blog post (approximately 182 lines), I’ll paste just the relevant snippets for getting the aim of this tutorial across.

<block type="core/text_list" name="left" as="left" translate="label">
<label>Left Column</label>
</block>
What you see above is the creation of the region called “left”. This is telling Magento that we have a region called “left”, to which blocks in a multitude of modules can be assigned. This is a blank area of the theme, to which content, in the form of blocks, is pointed (emphasising the point, there).
<reference name="left">


<block type="core/template" name="left.permanent.callout" template="callouts/left_col.phtml">


<action method="setImgSrc"><src>images/media/col_left_callout.jpg</src></action>


<action method="setImgAlt" translate="alt" module="catalog"><alt>Our customer service is available 24/7. Call us at (555) 555-0123.</alt></action>


<action method="setLinkUrl"><url>checkout/cart</url></action>


</block>


</reference>

The block of code above is from catalog.xml, the controller XML file for all things related to the Magento catalog. The above block of code creates one of the default callout blocks (a block with an image and a URL) that is bundled with the default Magento theme. Lets spend some time on this block of code.

So… how do I use these files?

The first and last lines, in this case, are the most important. They tell Magento that anything within them (ie: the block inside the <reference> tags) will be assigned to the “left” region. Inside that, the <block> tags setup the callout block with it’s various attributes. As the <action> tags are rather specific to this callout (they use specific image-related methods to setup the source of the image, it’s alternate text and the URL to which it points), lets focus on the opening <block> tag.

The opening <block> tag has the following attributes: type, name and template. These do exactly what they say on the tin.

type- Tells Magento what type of block this is (it could be a product list, catalog, a display of only new products, etc). This is dependent on the type of content within the block. In this case, it’s a raw image using a specific template, so it’s a core/template.

name- What this block is referred to as within the XML files.

template- What template file is used to render this block within the theme. In this case, it’s a template called left_col.phtml within the “callouts” folder. This file looks like this:




   <div class="block block-banner">


<div class="block-content">
        <?php if(strtolower(substr($this->getLinkUrl(),0,4))==='http'): ?>
            <a href="<?php echo $this->getLinkUrl() ?>" title="<?php echo $this->__($this->getImgAlt()) ?>">
        <?php elseif($this->getLinkUrl()): ?>
            <a href="<?php echo $this->getUrl($this->getLinkUrl()) ?>" title="<?php echo $this->__($this->getImgAlt()) ?>">
        <?php endif; ?>
            <img src="<?php echo $this->getSkinUrl($this->getImgSrc()) ?>"<?php if(!$this->getLinkUrl()): ?> title="<?php echo $this->__($this->getImgAlt()) ?>"<?php endif; ?> alt="<?php echo $this->__($this->getImgAlt()) ?>" />
        <?php if($this->getLinkUrl()): ?>
        </a>
        <?php endif ?>
    </div>
</div>

Above you can see some familiar functions such as getImgSrc() (related to setImgSrc() within the XML file). These functions retrieve the data that is set within the <reference> tags in the XML file.

… and to sum it all up …

Okay. Lets sum this up in a single paragraph.

Wherever dynamic content is set within your theme, it is more often than not done using a region. These regions are usually set within the page.xml file, as the “page” module defines the main skeleton of the Magento theme. Blocks specific to the module they work with are set in that modules XML file, with a <reference> to the region in which they are displayed. A template file, usually stored within the module in question, is used to render the content that is retrieved by the block it is used on.

Wow, this was a busy tutorial. There’s a lot to take in above, folks. If any of it seems unclear, please leave a comment and I’ll do my best to help clarify things.

]]> http://matty.co.za/2010/04/magento-themes-part-04/feed/ 6 Theming for Magento — Part 03 – Theming Basics http://matty.co.za/2009/10/magento-themes-part-03/ http://matty.co.za/2009/10/magento-themes-part-03/#comments Sun, 18 Oct 2009 16:54:00 +0000 Matty http://matty.co.za/?p=711 Right. We’re in part 03 of our “Theming for Magento” tutorial collection. Time to get down to some theming.

A quick word on conventions

Magento, like many other content management systems, likes to follow conventions. Adopting these conventions when designing your theme, as well as during the theming process, can greatly minimize the amount of code required by your theme. As mentioned on Part 02, Magento has a “fall back” feature where it looks for required files, when not in your theme, within all other themes in the current interface until it finds the file it requires. This essentially allows users to keep a copy of the default theme in the interface in which they are coding their theme (either the “default” or a custom interface) and to only modify the files that require customisation.

An example of the above-mentioned conventions can be seen in the way that boxes are styled within Magento. Boxes are not unlike “widgets” in WordPress. Each box is assigned a unique class for specific styling to that box, as well as a generic class for global styling.

A CSS block for global Magento box styling looks like this (no attributes currently set for each class):

.box {}
.box .head {}
.box .head h4 {}
.box .content {}

By styling the above tags in a CSS file within your theme, you should be able to style the majority of sidebar blocks within your Magento theme.

Setting up your theme’s stylesheets

As mentioned in Part 02, Magento themes are made up of templates and XML files, as well as a folder to hold all images, CSS files and other assets. For starters, I’d recommend making copies of all CSS files within the default theme and placing them in the same relative location within your custom theme (most likely the “CSS” folder within your theme’s “skin” folder). Once you’ve got the hang of working with these CSS files, or to add your own so your own CSS file conventions can be used, the calls to the CSS files are located in page.xml near the top of the file. Once you get the hang of the conventions used within Magento, adjusting the theme’s CSS becomes a lot easier.

Great, so what other conventions are there?

If you’re working in Firefox, I’d recommend installing the Firebug extension, or something similar. In Safari, use the “inspect Element” command. This will allow you to inspect the code of your Magento installation and to identify conventions within the code. As there are an almost endless amount of template files, when styling your theme I find it best to keep a copy of the default theme within the interface in which I’m coding and to make as many changes as possible via the CSS and images without modifying the template *.phtml files or *.xml files. This way, when your theme is done, you may end up with only several modified *.phtml and *.xml files. Also, if you want to then package your theme as a standalone theme (ie: without requiring the need of the default theme), you can simply copy the unmodified files from the default theme over to yours and voila!

A Very Important Final Note

Well, folks, that’s it for this round of the “Theming For Magento” tutorial collection. In Part 04, we’ll be opening up one or two *.xml and *.phtml files, checking out how they work and looking into ways to create smaller code snippets where possible.

A very important last note: when creating your Magento theme, make a note of all the files you’ve modified along the way. For example, if you only modify the CSS files, make a note of that. It will help greatly later in when identifying unmodified files for copying over from the default theme and can, in general, be a real time-saver.

]]> http://matty.co.za/2009/10/magento-themes-part-03/feed/ 8 Theming for Magento – Part 02 – Theme Architecture http://matty.co.za/2009/08/magento-themes-part-02/ http://matty.co.za/2009/08/magento-themes-part-02/#comments Fri, 14 Aug 2009 08:25:30 +0000 Matty http://matty.co.za/?p=565 OK folks, we’re not going to rush things. Lets take this theming for Magento one step at a time. :)

In today’s tutorial, I’ll be discussing the architecture of Magento themes, the reason for this architecture and a brief introduction into a general idea of what goes where and why.

The installation… lets get it out of the way

The Magento installation is, essentially, a click-through process. You need to have a MySQL database created on a server, as well as the login details for this database. Other than that, the various options are fairly clear and straight forward.

For further information on installing Magento, visit the Magento Installation Guide and Knowledge Base.

Right, it’s installed. So… where do I start then?

The core idea, I believe, within the Magento theme architecture, is the complete separation of form and function (ie: design and functional code). For this reason, each theme is, first and foremost, stored in two folders- app and skin. The app folder holds all templates (consisting of *.phtml and *.xml files… I’ll explain in a bit) while the skin folder holds all images, CSS stylesheets, Javascript files, etc.

Cool. But how do I structure my theme?

First things first. It is very important that your basic folder structure is exactly the same in both the app and skin folders. The structure is divided into two levels- the “interface” and the “theme”. An interface is, essentially, a group of themes or can be seen as a folder in which your theme resides. In your interface, it is always good to make sure that at least one theme within the interface contains all necessary template files (the same applies to the skin folder interface). If you’re creating one theme for a single store, it may make sense to create your theme within the default interface (the “default” theme within this interface contains all necessary files for theming). Alternatively, simply creating a copy of the “default” theme within your custom interface would do the same thing.

To visually illustrate the concept of interfaces and themes, the folders will look something like this:


root_directory
|_app
|__default
|___default
|__your_new_interface
|___default
|___your_new_theme
|____all template files within your theme


root_directory
|_skin
|__default
|___default
|__your_new_interface
|___default
|___your_new_theme
|____all asset files within your theme

OK. My structure is set. What about those template files you mentioned earlier?

Templates are, essentially, the various areas of your Magento store. They use a combination of *.phtml files (HTML files that can execute PHP commands) and *.xml files (determine layout, declare sidebar block calls, etc) to structure and set out the content for the various sections of your Magento store.

Working with these templates is another tutorial, for now I’d like to mention one thought that helped me a lot when theming for Magento. The system is built in a completely logical manner. For example, if you wish to customise a newsletter signup block for a particular template (theoretical example) you will look in the newsletter.xml file, and not in the template file you’re wanting to customise. That’s just a mindset thing that you may have to get your head around before theming for Magento.

A quick word on falling back

Before I wrap things up, I’d like to comment on the way Magento themes fall back. By “fall back”, I’m referring to the concept of “looking” for a particular file in the current theme and, if the file doesn’t exist, falling back on a fail safe copy of the file. This is the purpose of making sure we always have a fully featured theme within our desired interface. If, for example, your theme template files require button.jpg and your existing theme doesn’t have the file, Magento will look at all other themes in your interface until it finds the file. There is a much more complex explanation for this in a slideshow presentation I read through a few months ago. The presentation is by Jonathan Lackey and can be found here. Essentially, this also means that, if we so with, we’re able to make our theme smaller and rely on existing templates from our “fully featured” theme (for example, simply modifying CSS and selected XML files instead of the entire theme).

Until next time…

I think this is where I’ll leave it this time ’round, folks. In the next tutorial, I’d like to get into a bit of actual theming (now that our architecture is in place) and touch on a few conventions that could greatly speed up the theming process, as well as a few concepts that can become quite important when theming regularly.

]]> http://matty.co.za/2009/08/magento-themes-part-02/feed/ 0 Theming for Magento – Part 01 http://matty.co.za/2009/08/magento-themes-part-01/ http://matty.co.za/2009/08/magento-themes-part-01/#comments Sun, 02 Aug 2009 18:27:58 +0000 Matty http://matty.co.za/?p=561 Magento, the popular e-commerce website platform, has, over the past few years, become a prominant player in the content management market. Utilising its robust array of features as well as its stock and sales management fascilities, Magento is a great choice for a system to manage your online store.

When setting up your Magento store, the system comes packaged with a default theme. In the majority of situations, this is not ideal. Enter theming… the process of designing and building a custom theme for your Magento store. This post is an introduction to a collection of blog posts discussing theming for Magento, general concepts and a few tips and tricks. These posts are intended as guidelines to theming and not as a verbatim point-for-point on how to create Magento themes. :)

Before we start, there are a few things you’ll need:

The latest version of Magento.

Self-explanatory. Found at http://magentocommerce.com

A web browser with a debug fascility.

Magento sets up various CSS styles and elements which are applied throughout the store. You’ll be best off identifying the conventions used and styling those, instead of re-creating each section.

A debug fascility could be either Firefox’s Firebug addon, Safari’s built-in debug console or Google Chrome’s built in debug console.

A design for your store.

This is where things may start getting tricky. Its generally best to stay within the guidelines in terms of the elements on the screen for each page of the store. That being said, one doesn’t want to limit the design. Therefore, a solution I found is to think in terms of a “header – footer” concept… ie, think in terms of designing “around” the content area. You’ve got a header and footer area that stay the same on all pages, while the content area changes (this includes the sidebars).

The XHTML/CSS for your store.

For the scope of these blog posts, I’d recommend having your store already built in XHTML. Just the header and footer will be enough for now. We’ll get to the content area once we’re in Magento.

A basic understanding of Magento’s architecture.

For a basic Magento theme, there isn’t much need to understand the underlying workings of the system. Essentially, just the templating architecture will suffice. This will be explained in the next blog post.

A local server installation.

This could be WampServer (Windows), MAMP (Mac) or any other local server installation. Either way, developing your theme on a local server is recommended.

And yeah, that should be all you’ll need for now. In the next post, I’ll briefly discuss installing Magento and explain the theme architecture and how to go about starting your theme off. :)

]]> http://matty.co.za/2009/08/magento-themes-part-01/feed/ 0