Table of contents

Overview

TODO: describe here: Intended audience. Purposes. Main points of howto.

Simpliest way to customize default theme

How to download default theme (folders structure)

To make you custom theme from one of default themes, you should first download one from themes download section at our site and unzip it. All default themes have common folders structure. When edit theme .phtml files and resources you should leave folders structure unchanged. When customization completed you should change information in metadata.xml file. Theme name, author, version and description should be set there. Then pack your theme into .zip file and it is ready to use! Please note, your theme name in the system will got this .zip file's name, so it should be unique.

How to change css and images

The easiest way to make default theme distinctive is to change colour scheme of the page and images like header, footer etc. To do this you should open resources/ folder in downloaded theme. File resources/css/styles.css contains css rules for both: common parts (like Topbar, Breadcrumbs) and specific pages (Products, News). And to change webshop skins you can replace needed images in resources/images/ folder with your custom images.

How change theme translations or create new translation

You can both change existing translation or create you own translation. In case you want to edit existing translations, you should download proper .po language file at download section, change it, complie it to .mo file and put corresponding .mo file in languages/. In case you want to create your own translation you should likewise create .mo file from original Gettext format .po file and place it to languages folder. The name of .mo file should be standard two-letter code of language. You can read more about theme translations here.

Default theme intermediate customization: changing pages

Webshop site content cutted onto parts which are responsible for a structure (layouts) and parts, containing meaningful data (content blocks). The way how they will be combined depends on blocks.xml file rules and on page url. Lets discuss how this works for webshop main page for example.

Page parts named according to theis positions: left, right, middle_top, middle (see left image). Lets call them "structural blocks". Layout file contains HTML code, which define structural blocks placement on page (see file soruce here). Then, blocks.xml file XML rules define, which content blocks will be rendered inside of which structural block. For example, if you look at left and right images, you'll see:

The blocks.xml file is a flexible tool which allows both: set common associations for all webshop pages, and some another associations for specific page (read more here). As you see at the right picture, content block files contains each own specific data like product list or quick search form (see example). Now we'll talk in more detail how to add changes in layout and content files and in blocks.xml file.



How to change page layout

At this moment default theme has main layout, which is common for all pages, and one specific layout for product page. You can find them at: templates/layouts/[layout_name].phtml. You can remove unnecessary structural block from layout file or add yours. Changing .phtml file please don't forget about css rules attached to it. For example, if you want to reject three-columns default layout and use two-columnt or some other, you should add changes both into layout file and to related css rules. need here example -- what css must be changed, and why

Also you can left existing default layouts as they are and add your own: common layouts and specific pages layouts. You should place them in layouts folder as it is written above and add proper rules to blocks.xml file. This is example how common layout can be redeclared: You can see more examples of how to set your template for specific pages here. Making your own template, please not forget to include main content block into page: {$layout->content}. It is obligatory!

How to change some parts of page

But what if you want to change not whole site view but make custom changes — like show product categories not at the left side but at the right. Or show cart/short under the produt filter form instead of showing it above. Or hide cart/short at client profile page at all.. File blocks.xml rules will help you do these. Lets use this XML rule example:

To remove for example currency/select block from your webshop theme you should only delete corresponding row in this rule. You can add it to another structural block rule if you want. Also, as you can see in example, each content block description has position parameter. Changing them you can set which block will go first and which after. Here positions with number '0', '10', '20' are used, so you easy can add one more row in this rule, for example this one: As a result, search-by-name block will appear between product cart and filter form in right structural block.

How to move-show-hide content blocks only for some pages

As you already noticed, content blocks named by their action. E.g. in example about we used content block for search-by-name action. Actions are placed under some group, like filter here. These groups called controllers. You can read about this naming more here. Default theme provide fixed list of avaiable content blocks. You can view entire list of page content blocs (main content like product details) in this list with descriptions, and list of other content blocks (news, filter forms etc) here.
Please notice, main content blocks naming match with page address, for example http://webshop_domain_name/product/details page will got page template named 'product/details'.

We will operate information above when configure appearence of specific pages. For instance, product short cart usually placed in the right part of page, as it defined in common rule: For example you need to do the following changes: hide short cart and show your custom template with short list of promotion products at the left side when client view product cart. To do this, you should add to blocks.xml file the following rules: The first rule here denies short cart in the right block, the second will show promotion products list. The same way you can add some additional content block at proper page part for specific action, or for several actions, grouped under one controller. You can see more detailed description of controller and action params using here.

How to change auxialiary content on the page

The section above desribes the ways of positioning blocks on the page. If you want to change something inside of some block, you should edit the block template. Template files placed as templates/blocks/[block_controller_name]/[block_action_name].phtml. Please look at the content block layout example. This is a part of product/popular-gird content block layout:

As you've already noticed smarty variables are used here e.g. {$product}. There are variables specific for each page and common variables, accessable at all webshop pages. To work with them please look throught the list of variables here. Variables output can be formated using variable modifiers as it is shown here for product price and for text contstants. Common smarty modifiers and Notando eCommerce modifiers (see here) are avaiable to usage. Add here remark: some css classes are used for javascript treatment of data, changing templates please not remove these classes!

How to change main content on the page

Main content block of the page (Page content plock) can be treated in exactly the same way as all other content blocks (explained above).

But its including into site has the following difference. Main content block placement on page not depends on blocks.xml file rules. It will be rendered always into this block of layout template: {$layout->content}. So, to change main content block placement on webshop pages you should add changes into layout file. Main content block can be different for different pages, it content depends on page url. You can read more about this, and also see entire list of existing pages here. Main page content block files are stored as templates/controllers/[controller_name]/[action_name].phtml according to their controller and action. Changing templates please not forget about related css. Style rules of specific page templates are placed in common stylesheet file under controller/action subtitle

Making your custom theme from a scratch

How to properly cut your design into layouts and blocks

Webshop pages are stored not as static content for each page, but as a parts. This solution makes application flexible and well-ordered, and also allows templates reuse for different pages. After your .phtml designs are completed they should be cutted onto content block files and layout files.

Your custom theme must contain main.phtml layout file, placed as templates/layouts/main.phtml. . It'll be used as default layout. If you want to set specific layouts for some pages you should put them into 'layouts' folder also. To define to wich pages this layout will be rendered, write proper rules in blocks.xml file. Look at examples. Please not forget, all your templates should contain this code: {$layout->content} to render main page content.

According to the functionality, Notando eCommerce provide, the fixed list of pages exists. Default theme uses this list of pages (main content blocks of each page). If you want to provide the user with a complete set of functionality you should create templates for all actions from this list. Template files should be named according their actions and placed as templates/controllers/[controller_name]/[action_name].phtml. Adding style rules of concrete page you should mark the section with controller/action name also. This allows have the same coding style in whole theme. Styles should be placed as resources/styles/[your_stylesheet].css

The same way auxiliary content blocks on pages should be named and stored: templates/blocks/[block_controller_name]/[block_action_name].phtml. There is default list of auxiliary blocks at Notando eCommerce. Each has special view variables accesable in it. You can also create any other content blocks, but only common view variables can be used in that case.

How to properly bind layouts and content blocks

Writing custom themes you maybe use to include auxiliary files directly in your template. This is also possible to do in Notando eCommerce, see examples:

{include file="common/view_parts/grid_builder.phtml"}
{include file="controllers/cart/short.phtml"}

When directly include template files or resources you must use template modifiers (see here template modifiers description and list). Using modifiers allows properly define absolute path to directory with needed file. For example, you can write this:

{'images/list_no_product_image.png'|selectable_resource}
{include file='controllers/login/index.phtml'|theme_template}

But direct file including is not very flexible method for templates — including some file directly into the page you define it placement strictly for all webshop pages. Notando eCommers provide more handy tool to include files, it is blocks.xml file. To use it you should first name a page parts in your layout according to their placement (this is example of how structural parts are added in a layout file). Then you should write which content blocks will be rendered in which structural blocks using blocks.xml file rules. There are alot of examples how to do this in text above, and here.

How to write content for page blocks: auxiliary tools

Here we'll describe the tools you can use when create pages content. First of all to output data you should learn the list of view variables. You can format variables output using standart Smarty modifiers and custom Notando eCommerce modifiers (see complete list and details here).

All additional modifiers are also available as Zend View Helpers. For example {'Text to translate'|lang} and {$this->lang('Text to translate')} are both correct. Using Zend View Helpers tool you can call any PHP function except these. In additional custom Notando eCommerce functions are avaiable as Zend View Helpers. They can be used for some often used tools like pager for product list (see all custom functions).

Also you can customize some page setting, for example product list parameters. To do this, add this block of rules into blocks.xml file:

This settings can be used in product grid as view variables e.g. {$list_style}.

Making your custom theme you can use default theme content blocks and pages as an example 'cause there you can see how to use view variables, and these pages are completed solutions of data presentation such as product grid, product categories menu tree etc. Pages and content blocks are places in default theme according to their 'controller/action' naming. Also there exist auxiliary common view parts — auxiliary content blocks which are used in many places. They can be included directly into page. See the placement of all types of files in default theme folders structure. Here you can see the entire lists: pages, content blocks, common view parts.

After you theme is done you should fill the theme metadata and make theme package as it is described here.














TODO 1: we need strict division in css file -- what styles are for layouts (common parts) and what are for content blocks. as designer should be able easy remove not-necessary css part if he've removed some .phtml. Also structure and color settings in css should be somehow separated!
TODO 2: how designer can makes experiments?!! -- he has not project installed, there are only pieses in default theme. we must provide something like static pages set (with one index with menu) where proper blocks included -- to get designer full picture of future webshop site and to let him use this for css changing etc.
TODO 3: also i haven't understand about images -- what is standard and what will be uploaded by each company (like should designer set header etc). is there some images set (like, in default theme 'header' and 'footer' both are orange, so if i've changed one i should change another also. the same is for other images, and seems for css rules also)
TODO 4: Default theme already has folder with all translations, avaiable at our site download section, or designer should download and add to his theme necessary ones?
TODO 5: what is product_page and products_page layouts for (what the difference). What set of templates will be in default theme? and what 2columns-right template is?


TODO 6: Will it works if designer will create some additional actions templates? (if we have no such a pages)