Developer's Manual  Blocks  Configuration File

Configuration File

Block configuration file is PHP script that defines block's properties and their configuration parameters.

<?
[$info  = string info;]
[$cache = int mode;]
[$cacheTTL = int time_in_seconds;]
[$cacheTTL1 = int time_in_seconds;]
[$type  = string block_type;]
[$skip  = int skip;]
[$labelWidth = int width;]
[$properties = array properties;]
?>

$info

Optional. The description of the block you may provide for SiteSupra administrator as a reference of what block is doing.

$cache

Optional. Specifies wheter cache block output or not. Possible values for $cache are:

Value Description
0 Block output is not cached
1 Block output is fully cached
2 Cache for a block is turned on but developer has to specify which variables to cache

If $cache is omitted then 0 is assumed as a value. For more information on how to use SiteSupra cache refer to Using Cache.

$cacheTTL

Optional. Specifies cache data time-to-live in seconds. After that time SiteSupra executes block and stores its output in cache field again. Valid only when $cache == 1.

$cacheTTL1

Optional. Together with $cacheTTL specifies the range of time when cache data should expire. SiteSupra compares time passed from the moment block cache was created with the result of executing rand($cacheTTL, $cacheTTL1). If time passed is greater than rand($cacheTTL, $cacheTTL1), then SiteSupra executes block and stores its output in cache field again. Valid only when $cache == 1.

$type

Optional. Specifies a type of a block. Possible values for $type are:

Value Description
php Block has PHP code.
html Block does not have PHP code.

Specifying correct block type can speed up block loading time. For php type SiteSupra uses include() function that works slower than file_get_contents() function used for html type. If $type is omited then php type is assumed.

$skip

Optional. Specifies whether to skip block when rereading configuration files or not. Possible values for $skip are:

Value Description
0 Do not skip block.
1 Skip block.

Example

<?
// Skip block for german langauge,
// i.e. the block will not appear in the blocks list on german language
if(suLANG == 'de')
    $skip = 1;
$cache = 2;
$properties = Array();
?>

If $skip is omited then 0 is assumed as a value.

$labelWidth

Optional. Specifies width of label field in pixels. Default value is 70 pixels.

$properties

Optional. Defines properties of a block and their paremeters. The $properties array has the following format:

<?
$properties = Array(
  'property_name' => Array(
    'type'     => string type,
    'value'    => mixed value,
    'label'    => string label,
    ['help'    => string message,]
    ['color'   => string hex_color,]
    ['global'  => int global,]
    ['empty'   => int empty,]
  )
);
?>

Every property is an array of configuration parameters. A parameter may specify a type of a block or its default value, for example. There are three mandatory elements (type, value, and label) and a number of optional parameters.

Parameter Description
type Required. Specifies type of a block. SiteSupra has 15 property types. Every type has a SiteSupra built-in editor assigned to it. For example, XHTML editor is used to edit a property of html type.
value Required. Default value of a property.
label Required. Caption text for a property. The label text is displayed in SiteSupra console after right cliclikng a block. In block properties mode click the label holding Shift to view property configuration..
help Optional. A hint message for a property. The message is displayed when a user moves mouse cursor over the property label or its value in SiteSupra concole.
color Optional. Specifies foreground and background color of property label.
global Optional. Specifies whether the property value is site-wide.
empty Optional. Specifies whether to assign default property value to the property value if it is empty.

Examples

<?
$properties = Array(
  'text' => Array(
    'type'     => 'html',
    'value'    => 'Hello world',
    'label'    => 'Text',
    'help'     => 'Simple text',
    'color'    => '#FFFFFF',     // label color is white
    'empty'    => '0'            // if property value is empty then don't assign default value instead
  ),
  'file' => Array(
    'type'     => 'file',
    'value'    => 'index.txt',
    'label'    => 'File',
    'color'    => '#FFFFFF|#000000', // label color is white and background is black
    'empty'    => '1'                // if property value is empty then assign default value in public mode only
  ),
  'date' => Array(
    'type'     => 'date',
    'value'    => '2004-09-29',
    'label'    => 'DOB',
    'empty'    => '1|2'              // if property value is empty then assign default value in public and edit modes
  )
);
?>
note Since block configuration file is PHP script you can use any valid PHP operations in the file. Please note, those operations will be executed only when SiteSupra reads configuration files.
Please login to add comments.