Back to CS-Cart.com

Layout

A layout is a powerful tool for customizing the look and feel of your store. You can change the position of certain information on the page by simply dragging and dropping information blocks.

Layouts are available under Website → Themes → Layouts in the CS-Cart/Multi-Vendor Administration panel.

To use the settings described below, you need an .xml file, which should be moved to the theme folder after configuration.

Note

The layout grid is based on the Bootstrap 2.3 framework. Learn more about the Bootstrap framework at the Bootstrap official site.

Layout Settings

A layout has the following settings:

  • scheme—the current version is 1.1. It extends the layout possibilities. You can specify edition (ULTIMATE, MULTIVENDOR) and build (RU, B2B) for elements, and you do not have to create several layouts for each product version.

  • edition—the product edition for the layout, e.g. <layout edition="MULTIVENDOR">. Normally, edition is not specified in scheme 1.1.

  • Grid columns—the number of columns in a grid (12 or 16). The 16-column grid is preferable and is used by default. This grid allows building more column combinations because the width of each column is smaller, so, there are more columns in a grid overall.

    In Bootstrap, the 12-column grid is used as default, and there is a big number of templates based on it. You should use this grid if you have the complete layout based on it and you need to move it to CS-Cart.

    Important

    If you have a 16-column grid and want to change it to a 12-column grid, the grid width values will be changed asymmetrically in the Administration panel. In the customer area, the grid width will not change, but the whole site width will be changed instead. You will have to change the grid width value for each grid separately.

  • Layout width—choose the Fixed, Fluid, or Full width layout.

    • With the Fixed layout you can define the column width in pixels (px). The widths of a column and a gutter between columns are defined in the css/tygh/grid.less file. They are defined with the LESS variables: @gridColumnWidth and @gridGutterWidth. By default, the widths are 40px and 20px.
    • For the Fluid layout you can define the minimum and maximum site width. The column width is defined in percents (%). The widths of a column and gutter are defined proportionally according to the values of the variables used for the Fixed layout.

    Note

    Find out the maximum site width with the following equation: (@gridColumns * @gridColumnWidth) + ((@gridGutterWidth * (@gridColumns - 1). By default, the maximum width is 1175px.

    • With the Full width layout the site will be adapted to the full screen width.

You can also use Media queries to change the blocks width depending on the screen width.

Layout includes

Locations

A location defines the appearance of a specific page. When adding a location, set:

  • Name—the location name.

  • edition—the product edition for the location, e.g. <location edition="MULTIVENDOR" dispatch="companies.apply_for_vendor" ... >.

  • build—the product build for the location, e.g. <location build="B2B" ... >.

  • Dispatch—a specific page or page type that the location is associated with. The dispatch parameter has the following format: [controller_name].[mode_name]

    • [controller_name]—the name of the controller.
    • [mode_name]—the mode in which the controller works.

    The value of dispatch is added to the index.php?dispatch= part of the page and points to a specific location. For example:

    • index.php?dispatch=checkout.cart points to the cart contents page.
    • index.php?dispatch=checkout.checkout points to the checkout page.

    You can choose the predefined values from the drop-down list.

Such elements of the site as header and footer are usually identical for every page. Use the Default location so as not to duplicate this content for each page.

The Default location is not attached to any specific page, but defines the appearance common for all the locations. The Default location must always be defined. To make a location default, choose the Default checkbox in the location settings.

Containers

A location layout consists of 4 containers: top panel, header, content, and footer.

Container

The top panel, header, and footer containers are defined only for the Default location.

In Bootstrap, containers have the following structure:

  • For the Fixed layout:

    <div class="container">...</div>

  • For the Fluid layout:

    <div class="container-fluid">...</div>

Containers have the following settings:

  • edition—the product edition for the container, e.g. <container edition="MULTIVENDOR" ... >.
  • build—the product build for the container, e.g. <container build="B2B" ... >.

Grids

Grids are placed in containers. In Bootstrap, a grid includes .span and .row. By default, the 16-column grid is used in CS-Cart.

Grid

You can define the following parameters for a grid:

  • edition—the product edition for the grid, e.g. <grid edition="MULTIVENDOR" ... >.
  • build—the product build for the grid, e.g. <grid build="B2B" ... >.
  • Width—the number of columns used in the container. For child containers, this number cannot exceed the length of the root container. This setting defines .span to be used for a block (.span1—.span16).
  • Content alignment—the position of the container inside the root (or parent) container:
    • Right (adds the ty-float-right class).
    • Left (adds the ty-float-left class).
    • Full Length.
  • Offset—adds the block shift from the left side. Uses the same values as .span. The .offset class is added to the grid.
  • User-defined CSS-class—adds a CSS class.

Blocks

A block is a separate box which represents a particular storefront component. Blocks are added to grids.

Blocks are created based on schemas. A schema is a file where all the blocks, their settings and templates are defined. The path to the blocks schema file is: app/schemas/block_manager/blocks.php

Block settings:

  • Name—the name of the block.

  • edition—the product edition for the block, e.g. <block edition="MULTIVENDOR" ... >.

  • build—the product build for the block, e.g. <block build="B2B" ... >.

  • Template—the template (.tpl) defined for a block. Block templates are stored in the templates/blocks/ directory.

  • Wrapper—the template that includes the content. Wrappers are stored in the /templates/blocks/wrappers/ directory.

    Note

    Some wrappers may be used only for specific blocks. For example, the Lite checkout wrapper is available only for the “Checkout” block.

  • User-defined CSS-class—used to add a CSS-class.

Hint

If you need to place a block in the top panel, header, or footer (containers that are used only in the Default location) for a certain page, use the HTML block with Smarty support. In this block use the $runtime.controller and $runtime.mode variables to define the current page.

Example:

To display some text in the header of the Categories page:

  • Create an HTML block with Smarty support in the header container.

  • In the block, add the following code:

    {if $runtime.controller == "categories" && $runtime.mode == "view"}
        <p>Categories page</p>
{/if}

Layout Export/Import

You can export a layout to a file, or import a previously created layout:

  1. In the Administration panel, go to Design → Layouts.
  2. Click the gear button in the right upper corner of the page.
  3. Choose the desired action.

When creating the new theme, export the layout to the layouts directory after adjusting blocks (remove the old files first). This layout will be automatically enabled when installing a theme.

The export/import file includes:

  • Layout settings.

  • The structure and settings of containers, grids, and blocks.

  • The content of the blocks. It is defined on the Content tab and depends on the block type. But not all the blocks have content.

    For example, for the HTML block and HTML block with Smarty support the content is the text included in the text area.

    In a Products block, the content is the criteria for displaying products (i.e. newest, recently viewed).

Warning

A layout is installed only when you install a theme. If you install a theme and then switch to another one, the layout of the latest installed theme will be active.

Layout Compatibility

When you develop a theme, you can specify whether the layout works with CS-Cart, Multi-Vendor, or both. To do that:

  1. Export the layout.
  2. Open the exported file.
  3. Add the edition attribute to the Layout element. For example
<?xml version="1.0"?>
<block_scheme scheme="1.0">
    <settings>
        <default_language>en</default_language>
    </settings>
    <layout edition="MULTIVENDOR">
        <name>Main</name>
        <is_default>1</is_default>
        <width>16</width>
        <layout_width>fluid</layout_width>
        <min_width>280</min_width>
        <max_width>1200</max_width>
        <style_id>Modern</style_id>
    </layout>
</block_scheme>

Here are the possible values of edition:

  • ULTIMATE—the layout works only with CS-Cart.
  • MULTIVENDOR—the layout works only with Multi-Vendor.
  • ULTIMATE/MULTIVENDOR—the layout works with both CS-Cart and Multi-Vendor.

When a theme is installed, all the layouts with the matching edition will be installed from the layouts directory.

For scheme 1.1

Scheme 1.1 allows specifying edition (ULTIMATE, MULTIVENDOR) and build (RU, B2B) for any element. Layout elements with these attributes that do not match the product edition or the product build, will be deleted during processing.

Layouts of Add-ons

Add-ons can add their own layouts. This is done via the layouts.xml file located in the add-on’s folder: app/addons/[addon_name]/layouts.xml.

Themes can redefine the layouts of add-ons. If the theme directory has layouts/addons/[addon_name]/layouts.xml in it, then those layouts will be used during add-on installation instead of the layouts that come with the add-on.