Loading...

Block Manager

We no longer maintain the Knowledge Base since version 4.3.x. All the latest user and developer documentation for 4.3.x and newer versions is now available at docs.cs-cart.com.

  • This article applies to CS-Cart versions:
  • 3.0.x

Contents:

Layout principles

960.gs

Page layout is created according to the 960.gs philosophy.

Long story short, according to 960.gs principles each page has fixed 960 pixels width and is divided to 12 or 16 vertical columns separated with fixed-width gaps. Visual blocks are snapped to these columns. The benefits of such layout are that the page will look the same on all monitors and browsers, and it looks neat just by default. The restrictions by 960.gs make it harder to spoil a page with a wrong markup grid.

Layouting

Different parts of a CS-Cart storefront are called locations. For example, home page and product catalog are locations. Each location has a dispatch (which must have a respective controller) and can have a description (which includes name, title and meta information).

Each location is divided into 3 containers: TOP, CENTRAL and BOTTOM. Their number is pre-defined and can't be changed.

One location should be selected as default. Its TOP and BOTTOM containers will be used by all other locations (and will override their own TOPs and BOTTOMs).

Containers are page-wide and inherit their content height. Containers can be divided to 12 or 16 vertical columns individually.

Page layout is configured by adjusting grids that are placed inside containers. The whole page area is partitioned with grids.

Data presentation

Blocks

Page data is presented in blocks. A block is a container (not to mess up with the containers described above) of a certain type defining the content to be put in it: products, categories, html block, etc. Blocks are packed in grids and never outside them (you can't just put a block in a container). A block takes the full width of its hosting grid by default. So if several blocks are packed within the same grid, they are placed one above another. This behavior can be overridden with the use of a CSS-classes assigned to particular blocks.

Blocks can be filled manually or automatically (e.g. most viewed products or latest news).

Some block types use specific settings.

The important thing about blocks is that one block can be used multiple times in different places and different contexts. The same block can have different content and wrapper depending on the context it is placed in. Still, block template is set only once for all block instances: when it is changed for one instance it is changed for all of them.

Block manager objects and behavior are defined in 6 files:

  • block_cache_properties.php - Global update handlers for block cache.
  • dispatch_descriptions.php - Dispatch list with the respective language variables. Used solely for list generating for the Dispatch field during location adding/editing.
  • blocks.php - Main block scheme.
  • dynamic_objects.php - Dynamic objects descriptions.
  • fillings.php - Additional parameters for fillings.
  • templates.php - Additional parameters for templates.

Block types

There are 14 pre-defined block types. Each one corresponds to a particular data type:

  • My account - customer account access.
  • Breadcrumbs - navigation breadcrumbs.
  • Menu - different types of menus.
  • Template - configurable template block. Blocks of this type can use any template from the [skins/basic/customer/blocks/static_templates] folder.
  • Main - main block. Its content is loaded by a respective controller.
  • HTML_block - block with any non-empty HTML content. Multi-lingual.
  • Products - product block. Can be filled either manually or automatically (e.g. show the newest, the most popular, etc.).
  • Categories - categories block. Can be filled either manually or automatically (e.g. show the newest, the most popular, etc.).
  • Product filters - block with different product filters (e.g. filter by price, options, etc.)
  • Pages - block of page links. 3 templates are available: dropdown, emenu and text_links. Can be filled either manually or automatically (e.g. current page neighbors, page children, etc.)
  • Payment methods - available payment methods list
  • Shipping methods - available shipping methods list
  • Currencies - available currencies list. Items can be shown as symbols or full titles, and placed in a drop-box.
  • Languages - available languages list. Items can be shown as icons or full titles, and placed in a drop-box.

Apart from these ones there can exist different add-on blocks.

Block scheme

Schemes describe general object structure. Available block types are also defined in the scheme. Block scheme is stored in the schemas/block_manager/blocks.php file.

Block scheme is an array of block types, each one being an array of block properties (some of which are arrays too).

Main block scheme described

1
2
3
4
5
6
7
8
9
'block type'    =>  array (
        'settings'  =>  Settings list   		(a)
        'templates' =>  Template list   		(b)
        'content'   =>  Content list    		(c)
        'wrappers'  =>  Wrapper list    		(d)
        'cache'     =>  Cache parameters. 
			It missing, block is not cached (e)
        'icon'      =>  Path to icon
),
  • a. Settings. A block itself can have settings that are set in the block settings dialog in the Settings tab.
    Settings can have templates and fillings. In the block settings dialog they can be displayed in different places, but they all are stored in the same properties array of a block and can be accessed from a template.
    They are also passed to the items getting function for the enumeration type.
    Settings list is a set of pairs key => value where setting name is the key. According to this name a respective language variable for the output should be defined.
    The value is an array:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    
    'setting name'  =>  array (
            'remove_indent'     =>  If true, the setting will not have right indentation when shown in the admin panel
            'required'          =>  If true, the respective field will be mandatory in block settings
            'option_name'       =>  Language variable to be used as title. If no defined, setting name is used instead
            'default_value'     =>  Default value
            'values'            =>  Setting options list: array of key=>value pairs for the selectbox and multiple checkboxes type settings
            'no_lang'           =>  If true, option name is not interpreted as a language variable and shown "as is".
            'values_settings'   =>  Used only with a selectbox type setting.
                                    Defines options list and additional settings to be displayed only when certain options from the parent list are selected.
                                    See usage example in the RSS Feed add-on scheme
            'picker'            =>  Picker template. Used only with the picker type settings
            'picker_params'     =>  Picker parameters. Used only with the picker type settings
            'template'          =>  Path to template. Used only with the template type settings
    	'type'		    =>  Setting type. See the available types list below
    ), 

    Available setting types:  
    • checkbox - Checkbox
    • input - Simple text field  
    • input_long - Text field with class input-text-long
    • multiple_checkboxes - A set of checkboxes
    • text - WYSIWYG text input field
    • simple_text - Non-WYSIWYG text input field
    • picker - Picker
    • template - Template. A particular template is shown. The template is specified in the template parameter
    • enum - Object enumeration. Used only in the Content section
  • b. Templates. Template list can be:
    1
    2
    3
    4
    5
    6
    
    'path_to_template'  =>  array (
            'settings'      =>  Setting list (see above)
            'fillings'      =>  Array of filling that are available for this template. All other fillings will be excluded from the list automatically
            'params'        =>  Array of parameters to be passed to the get block elements function before output
            'bulk_modifier' =>  Bulk modifier. Function to be applied to the block elements before output
    )
     
    All data from the template parameter of a block scheme will be combined with the parameters defined in templates.php during scheme generating. Path to template is used as key.
    The following items can correspond to the 'template' key in block scheme:
    • Template path list. All parameters are listed directly. In this case templates.php does not require any editing.
    • Template path list. All parameters are listed in templates.php.
    • Template folder path. All parameters are listed in templates.php.
    • Name of the function that returns the template path list. All parameters with respective keys are listed in templates.php or also returned by the function.
  • c. Content. Any block can contain any number of variables to be passed to template.
    For example:
    1
    2
    3
    4
    5
    6
    7
    
    'test_block' => array (
            'content' => array(
                    'some_value' => array(
                            'type' => 'text',
                    )
            )
    )

    A text input field will appear in the block settings dialog in the admin panel. When this block is shown in the customer area variable $some_value with the value prior defined in the admin panel will be available.

    Details

    Values of block content elements can be:
    • any setting value
    • enumeration type value
    • value returned by a function
    It's quiet clear with settings — what user saves in the admin panel goes to template.  
    Enumeration type is used to define element lists with different filling types, for instance a product or category list. Enumeration type parameters:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    'variable_name' =>  array (
            'type'              =>  'enum',
            'object'            =>  Dynamic object name in the scheme,
            'items_function'    => Item generating function,
            'fillings' => array ( 
                    /* Filling types */
     
                    'manually'  =>  array ( 
                            /* Manual filling, requires picker parameters */
     
                            'picker'        =>  'pickers/companies_picker.tpl',
                            'picker_params' =>  array (
                                    'multiple'  =>  true,
                            ),
                    ),
     
                    'some_other_filling'    =>  array (
                            'params'    =>  array (
                            ),
                    ),
            ),
    ),

    For non-manual fillings it is possible to define a params section, which will contain the list of parameters to be passed to the item generating function.
    It is also possible to define a setting list by the settings key for a filling, like for templates and blocks. If a function is used as a content element, the value of the variable will equal the result returned by the function.
    Usage format: 
    1
    2
    3
    4
    
    'variable_name' =>  array (
            'type'  =>  'function',
                    'function'  =>  array ('fn_do_something'[, 'param1'][, 'param2'][..]),
    ),
  • d. Wrappers The wrappers param can be either wrapper list or a path to a wrapper folder, similar to templates. There are no additional params.
  • e. Cache If a block should be cached, it should have the cache property defined in in the scheme.
    A list of tables is defined there by the update_handlers key. When those tables are updated the cache is updated too.

Static Blocks

In the new block manager the former static blocks are called template blocks with the only template property, which defines a particular output template from the add-on ../blocks/static_templates subfolder of the skin directory folder. If your add-on uses such block, it is enough to create a subfolder ../blocks/static_templates in the add-on folder and place there the template, which will be automatically added to the others.
Generally this way of template adding can be used with all basic cart blocks: template list can be extended by adding a respective folder.

Dynamic Objects

Dynamic objects in the block manager are the objects that support individual block content and status overriding, i.e. content and status of a particular block can be different from the global default for a particular object. The object-specific content is shown on its detailed page.

There are 5 pre-defined default dynamic objects: Products, Pages, Categories, News and Companies (only in CS-Cart Multi-Vendor).

Usage

Let's take a closer look on dynamic objects using the example of Products. The following is similar for all the other dynamic objects.

When block content is modified on a product editing page the modifications are saved only for the particular product. Every time this block is modified anywhere in the cart information about all where the modification will be applied is shown as well as a checkbox to apply the modification globally when checked.

Block status can be set as well as content too. So a block can be activated for a particular block whereas is is globally inactive or vice versa.

Implementation

The dynamic objects functionality is implemented with the help of the dynamic_objects scheme (schemas/block_manager/dynamic_objects.php). If needed this scheme can be extended with additional objects. For example the News & Emails add-on extends the default scheme.

Scheme description for products:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php
array(
	// Dynamic object name, used as object_type
	'products' => array (
	 	// Dynamic object editing page. The Blocks tab must be present on the page in the admin panel
		'admin_dispatch' => 'products.update', 
 
		// Address of the page in the customer area and in the block manager
		'customer_dispatch' => 'products.view', 
 
		// Key in $_REQUEST to be used to identify the object
		'key' => 'product_id',
 
		// Admin panel picker settings
		'picker' => 'pickers/products_picker.tpl',
		'picker_params' => array (
			'type' => 'links',
		),
	),
)

When a page with dispatch=products.view is requested the software automatically defines that the page belongs to a dynamic object 'product' and looks for product_id among the script input parameters. If the one is found, all the data necessary for page content generating will be requested via block API for a particular object type and identifier. If no page found by the given dispatch, dynamic object properties will be ignored and global values will be used.

<< Read previous Read next >>
Home / Docs / Design and Layout / Block Manager