The Main Schema—blocks.php¶

Available parameters¶

• type (string)—one of the following types of the setting:

  • checkbox—a checkbox
  • input—an input field
  • selectbox—a <select> field
  • input_long—an input field with the input-text-long class
  • multiple_checkboxes—a list of checkboxes
  • text—a WYSIWYG text input field
  • simple_text—a simple non-WYSIWYG text input field
  • picker—a picker
  • template—instead of the setting you’ll see the template you specify here
  • enum—enumeration of objects; used only in the content section

• required (bool)—if true, this field of the block settings will be mandatory.

• option_name (string)—the name of the language variable of the setting; if the name is not specified, the identifier of the setting will be used instead.

• default_value (mixed)—the default value of the setting.

• values (array)—the list of the possible options for the settings like selectbox and multiple_checkboxes.

  It is an array of key - value pairs. The key is the name of the option that is stored in the database. The value is the name of the language variable that stores the name of the option; or, if no_lang is true, it is the actual name of the option.

• no_lang (bool)—if true, the list of the values of the options will be displayed in the admin panel as is; if false, values will be treated as language variables.

• values_settings (array)—this parameter specifies the list of options and other settings that will appear if certain options of the parent list are chosen; works only with the selectbox type.

  Example usage:

  'settings' => array(
      'foo' => array(
          'type' => 'selectbox',
          'values' => array (
              'products' => 'products',
          ),
          'values_settings' => array(
              'products' => array(
                  'settings' => array(
                      'rss_sort_by' => array(
                          'type' => 'selectbox',
                          'values' => array(
                              'A' => 'rss_created',
                              'U' => 'rss_updated'
                          ),
                      ),
                      'rss_display_sku' => array (
                          'type' => 'checkbox',
                      ),
                  )
              )
          )
      )
  );
  

• picker (string)—the path to the template of the picker; use with the picker type only.

• picker_params (array)—the settings of the picker; use with the picker type only.

• remove_indent (bool)—if true, the setting won’t have the indent on the right in the admin panel.

• template (string)—the path to the template; use with the template type only.

Possible values¶

• false—the block won’t cache.
• true—the block will cache according to the global block caching settings from the block_cache_properties scheme.
• array—an array with the caching settings of the block; the parameters specified in this array will be added to the global block caching settings from the block_cache_properties scheme.

Available parameters¶

These parameters of the cache array specify how a block is cached. The parameters are not required, unless stated otherwise.

• update_handlers (array)—the list of database tables (without prefixes), changes to which will invalidate the cache of the block. By changes we mean adding, editing or removing entries and modifying the structure of the tables with the CS-Cart tools, like functions and methods for working with databases.

  For example, a block that displays the list of users should have the users and user_profiles tables as update_handlers.

When generating the entry key in the cache, you can use serialized values of different variables and parameters for this block. List the required parameters in the arrays described below:

• request_handlers (array)—the list of the names of the HTTP-request parameters (the keys in the $_REQUEST array).

  For example, if you specify the category_id and sort_by parameters, then the line like ...|category_id=10|sort_by=price; will be added to the key—that allows to use different entries in the cache for every combination of the values of these parameters.

• session_handlers (array)—the list of the names of the variables in the user’s session (the keys in the $_SESSION array).

  For example, if you specify the items_per_page parameter here, there will be a separate entry in the cache for every value of $_SESSION['items_per_page'].

• cookie_handlers (array)—the list of the parameter names in the user’s cookies (the keys in the array returned by fn_get_session data()).

• auth_handlers (array)—the list of the keys in the $_SESSION['auth'] array.

Use special forms to enter the values for request_handlers, session_handlers, cookie_handlers, and auth_handlers

• Use Dot-syntax to access the nested elements. For example, use 'session_handlers' => array('auth.user_id') to select $_SESSION['auth']['user_id'].

• Select all values with *: for example, 'session_handlers' => array('*') selects all the values in the $_SESSION array. When the cache key is generated, the entire serialized $_SESSION array will be used.

• Comparison operators

  'auth_handlers' => array(
      'user_id' => array('gt', 0),
  ),
  

  The entry above selects the value of $_SESSION['auth']['user_id'] and adds it to the cache key, but only if the value is above 0.

  Available comparison operators:

  • gt—greater than
  • eq—equal to
  • neq—not equal to
  • lte—less than or equal
  • lt—less than
  • gte—greater than or equal
  • cont—contains this substring
  • ncont—doesn’t contain this substring
  • in—in the array
  • nin—not in the array

The cache key can also include the results of the summoned functions and methods:

• callable_handlers (array)—the list of the parameter names and corresponding functions. The results of the summoned functions will be used as the values for these parameters.

  'callable_handlers' => array(
      'currency' => array('fn_get_secondary_currency'),
  ),
  

  The entry above adds |currency=RUB to the cache key.

  This is how to describe the function to be summoned: array(Callable[, Args]).

  • Callable is the string with the name of the function, or any other value expression that can be summoned with call_user_func() (learn about Callables at php.net).

  • Args is a non-mandatory array that lists the arguments to be passed to the function. If an argument is a string that begins with $, it will be treated as the name of the variable, if it is a global variable ($_REQUEST, …) or one of the variables from $block_schema and $block_data.

    • $block_schema—contains the schema of the block

    • $block_data—contains the information about the block from the database

      For example:

      'callable_handlers' => array(
          'layout' => array('fn_get_products_layout', array('$_REQUEST')),
          'settings' => array('fn_foo_addon_cache_key_handlers', array('$block_data')),
          ),
      

    The code above adds the results of all summoned functions to the entry key in the cache.

• disable_cache_when (array)—specifies the rules for disabling cache for this block. You can use the request_handlers, session_handlers, cookie_handlers, auth_handlers and callable_handlers in the same format, as in the cache settings section, but these parameters work differently.

  For example:

  'cache' => array(
      'request_handlers' => array('sort_by', 'items_per_page'),
      'auth_handlers' => array(
          'user_id' => array('gt', 0)
      ),
      'disable_cache_when' => array(
          'request_handlers' => array('sort_by', 'items_per_page'),
          'auth_handlers' => array(
              'user_id' => array('gt', 0)
          ),
      ),
  ),
  

  Here’s what different about the work of these parameters in the cache and disable_cache_when sections:

  • cache: the values of $_REQUEST['sort_by'] and $_REQUEST['items_per_page'] will be serialized and added to the cache key of the block. The value $auth['user_id'] will be serialized and added to the key only if the value is greater than 0

  • cache.disable_cache_when: if the $_REQUEST array has sort_by or items_per_page, the block won’t cache; the block also won’t cache, if the $auth array has the user_id key with the value greater than 0

    The callable_handlers parameter also behaves differently in the cache.disable_cache_when section: if the function returns true, the block won’t cache, and the other way round.

• regenerate_cache_when (array)—describes the rules of cache invalidation for this block; it works the same way as cache.disable_cache_when.

• cache_overrides_by_dispatch (array)—describes the parameters of block cache for every separate dispatch as array('dispatch' => cache_params, ...)

  The cache_params array stores caching parameters for the specified dispatch. If the array has an entry for the current dispatch, then the caching parameters will come from this entry, rather than from the general block caching settings in the cache section. Every nested array of caching parameters for a dispatch may use the same parameters, as the cache section.

  For example:

  'cache' => array(
      // These caching parameters will be used everywhere, except for the category page
      'update_handlers' => array('users'),
  ),
  'cache_overrides_by_dispatch' => array(
      // These caching parameters will be used on the category page
      'categories.view' => array(
          'update_handlers' => array('users', 'products'),
      ),
  ),
  

• hide_on_locations (array)—the list of dispatches where the block can’t be used. For example, use the following piece of code to forbid adding the block on the cart page:

  'hide_on_locations' => array('checkout.cart'),
  

• single_for_location (bool)—if true, then every dispatch can only have one block of this kind; if this parameter is not specified, it is interpreted as false

• multilanguage (bool)—determines if this block needs multi-language support. If true, the content of the block will be determined by the language. If this parameter is not specified, it is interpreted as false.