Help
Layout Manipulation
LiveCart provides great amount of flexibility on customizing the layout of store pages.
You can easily add, remove or customize layout elements of any particular page or set of pages of your store.
Terminology
Before we can proceed, it is crucial to understand the basic concepts and terminology that is related to the layout of LiveCart pages and its customization.
Template file
Page layout is generated by including several template files. Each template file is responsible for generating a particular page fragment or section. Template files can include other template files.
Block
A block is a named placeholder, which can be included in any template file. A block output consists of one or more controller action results (custom logic executed before passing the variables to template renderer to generate the block output).
Although both template files and blocks can include other template files, a block itself is only a placeholder and doesn't itself decide what gets included in it.
Please refer to the wireframe diagram below to get some sense as to how blocks and template files are used to generate a product category page.
Block and page template roles in page rendering
Theme
A ready made page design (pre-configured and customized layout), that has its own page template files, stylesheets, images and other assets that are neccessary.
What is Possible
The following actions are available:
- Append or prepend a template file to another template file or block
- Entirely replace a template file with another template file or block
- Remove a template file or block from layout
- Change layout theme
- Add a custom block action
- Reorder linked blocks
- Swap blocks
Each of these actions can be matched by a number of parameters, which would determine for which pages would these actions be triggered. For example:
- All pages (the whole site)
- All actions of a particular controller (for example, all checkout pages, all user area pages, all product list pages, etc.)
- A particular action/page (for example, shipping method selection page at checkout)
- A particular resource page (for example, product with ID 123)
- A particular action with filtering by any request variable
Combining the actions with controlling parameters can provide practically unlimited possibilities to change anything in page layout within any page.
Configuration Format
All the actions are being configured through a single file, which is in INI format. The file location is storage/customize/view/block.ini.
The format of the configuration file is very simple. The file is divided into sections. Each section describes actions that can be applied for a particular block or a template file. For example
[CART]
checkout = remove
order = remove
This would remove the shopping cart block from page header in checkout and shopping basket pages.
As you can see from the example, each block can have multiple configured actions, which are presented as a key=value pair:
[block or template]
condition = action
another condition = another action
Configuration Conditions
*
Use asterisk (*) to create a catch-all condition that will apply for all pages in all cases. Example:
[CATEGORY]
* = Poll->poll
This would add a poll to the CATEGORY block in every page of your site.
controller
Create a condition that matches a certain section of your site, for example:
- category - product list pages (category pages)
- product - product detail pages
- user - user area pages
- order - shopping basket page
- checkout - checkout pages
- staticpage - information pages
- err - error pages
- etc.
This example will move the FILTER block above all the other blocks at the left side in the category (product list) pages:
[FILTER]
category = moveup:top
controller/action
Such condition would target a particular action (page), for example a user registration page, checkout payment page, product detail page, etc. For example, you can use this configuration to entirely replace the header.tpl template file with another file in the checkout payment page:
[layout/frontend/header.tpl]
checkout/pay = replace:custom/paymentHeader.tpl
controller/action/ID
This is similar to to previous condition, but in addition you can narrow the condition down to resource ID. The resource can be a category, a product or a news post (and probably other things might appear in future as well).
For example, if your store sells sports inventory and you would like to set the "winter" theme to your Winter Sports category (ID: 123) pages, the following configuration would have to be used:
[*]
category/index/123 = theme:winter
# you can also use a short-hand syntax, which has the same effect
category/123 = theme:winter
controller/action/variable~value
You can also use any request variable to build the condition.
For example, you can target only the first product list page to display a custom block with on-sale products above the product list (however this block wouldn't be displayed in 2nd, 3rd and subsequent pages).
[category/productList.tpl]
category/index/page~1 = prepend:CategoryOnSale->items
In most cases, when the custom output depends on particular values, and custom logic is required to fetch data, it would probably be a better idea to use the controller plugins and simply modify the template file. But different problems require different approaches, so feel free to pick the solution, which works better for the particular requirement.
Configuration Actions
path/to/template.tpl
Append template file to block or another template file.
The following configuration would add a template file after the product list:
[category/productList.tpl]
category = custom/categoryDescription.tpl
prepend:path/to/template.tpl
Prepend a template file before a block or another template file.
Just like the previous example, but now the template file is placed at the top of the product list:
[category/productList.tpl]
category = prepend:custom/categoryDescription.tpl
replace:path/to/template.tpl
Replace a template file or a block with another template file.
For example, you can replace the whole page header in all checkout pages:
[layout/frontend/header.tpl]
checkout = replace:custom/paymentHeader.tpl
replace:BLOCK
Replace a template file or a block with another block.
This technique is useful when blocks need to be moved around the page.
[layout/frontend/header.tpl]
checkout = replace:custom/paymentHeader.tpl