Expansions basis:


When you build an expansion you can create some different parts:

- The expansion part relative to the panels;
- The expansion part relative to the pages;
- The expansion part relative to the administrators area;
- The expansion part relative to the users area;
- The expansion part relative to the kernel stage.

Each part have the rules to execute the expansion in the different area of your website. You can also create a multilanguages expansion.

To create an expansion you must create a new folder in "core/expansion", in this new folder you must create:

- A "config.php" file;
- An executable (.php) file for administrator stage;
- An executable (.php) file for user stage;
- An executable (.php) file for kernel stage;
- An executable (.php) file used in expansion pages;
- An executable (.php) file used in expansion panels;
- An "icon.png" file (a 48x48 png icon file for administrator/user menu);
- A folder with languages files.

1) Expansion config file:
The "config.php" file contains all the expansion configuration parameters and have the following structure:

<?php

defined('WM3_cEXEC') or die('Denied');

// Expansion parameters here

?>

All parameters are within the array $_EXPANSION[]. The parameters that can be used are as follows:

General parameters: Description:
$_EXPANSION['id'] Expansion unique ID (must be >= 1000 and different from any other expansion ID installed in Webmatic).
$_EXPANSION['version'] Expansion version.
$_EXPANSION['db_version'] Expansion database version, if the expansion use some extra database tables you must specify the database version needed here, this parameter is useful when you update an expansion and you want to check if the current expansion database version is the needed one (0 means no database needed).
This parameter is optional, if you do not specify this parameter db_version will have the default value "0".
$_EXPANSION['wm_version'] Minimum Webmatic version needed to use the expansion, if the expansion need a newer version of Webmatic the expansion will not be executed and an error message will be returned.
$_EXPANSION['language_path'] Expansion language relative path, is used to create multilanguage expansions and is the path to folder with languages files ("language_en.php", "language_it.php", ...). In this folder you must create at least the "language_en.php" file (english is the default expansions language).
$_EXPANSION['title_index'] Index (in language file) of expansion title (this parameter is optional, if you do not specify this parameter the language array index 0 value will be used as title).

Administrator area parameters: Description:
$_EXPANSION['admin']['enabled'] If true the administrator area for this expansion is enabled. If false the administrator area for this expansion is disabled and all the administrator area parameters will be ignored.
$_EXPANSION['admin']['exec'] The name of the executable (.php) file relative to the administrator area, is the file that will execute when this expansion its used in administrator stage.
$_EXPANSION['admin']['icon']
$_EXPANSION['admin']['big_icon']
Icon (32x32) image file and big icon (48x48) image file used in the administration menu (these parameters are optional, if you do not specify these parameters a (48x48) png image file called "icon.png" will be used).
$_EXPANSION['admin']['submenu'] Include file (.inc) with administrator submenu (this parameter is optional, if you do not specify this parameter no submenu for expansion administrator area will be rendered).
$_EXPANSION['admin']['label_index'] Index (in language file) of expansion label for administrator stage (this parameter is optional, if you do not specify this parameter the language array index 1 value will be used as administrator expansion label).
$_EXPANSION['admin']['help_index'] Index (in language file) of help text for administrator stage (this parameter is optional, if you do not specify this parameter the help button will not be rendered).
$_EXPANSION['admin']['su_only'] If true only superuser can use the expansion in admin section, if false all the administrator can use the expansion (this parameter is optional, if you do not specify this parameter su_only will have the default value false).
$_EXPANSION['admin']['groupID']
If 'su_only' is false you can restrict the use of the expansion only to the administrators of a specified group (0 means all groups).
This parameter is optional, if you do not specify this parameter groupID will have the default value "0".

User area parameters: Description:
$_EXPANSION['user']['enabled'] If true the user area for this expansion is enabled. If false the user area for this expansion is disabled and all the user area parameters will be ignored.
$_EXPANSION['user']['exec'] The name of the executable (.php) file relative to the user area, is the file that will execute when this expansion its used in user stage.
$_EXPANSION['user']['icon']
$_EXPANSION['user']['big_icon']
Icon (32x32) image file and big icon (48x48) image file used in the user menu (these parameters are optional, if you do not specify these parameters a (48x48) png image file called "icon.png" will be used).
$_EXPANSION['user']['submenu'] Include file (.inc) with user submenu (this parameter is optional, if you do not specify this parameter no submenu for expansion user area will be rendered).
$_EXPANSION['user']['label_index'] Index (in language file) of expansion label for user stage (this parameter is optional, if you do not specify this parameter the language array index 2 value will be used as user expansion label).
$_EXPANSION['user']['help_index'] Index (in language file) of help text for user stage (this parameter is optional, if you do not specify this parameter the help button will not be rendered).
$_EXPANSION['user']['groupID']
You can restrict the use of the expansion only to the users of a specified group (0 means all groups).
This parameter is optional, if you do not specify this parameter groupID will have the default value "0".

Kernel stage parameters: Description:
$_EXPANSION['kernel']['enabled'] If true you can use this expansion as a kernel function. If false you can not use this expansion as a kernel function and all the kernel stage parameters will be ignored.
If this parameter is true you can use this expansion as kernel function with an url like this:

http://www.valarsoft.com/index.php?stage=7&action=10000&section=N

When N is the value of $_EXPANSION['id'] specified in general parameters.
$_EXPANSION['kernel']['exec'] The name of the executable (.php) file relative to the kernel stage, is the file that will execute when this expansion its used as a kernel function.

When you create expansion pages or an expansion panels you can specify one or more different executable file for the pages/panels, that means you can create different pages/panels for the same expansion, to do that you can use different index for the $_EXPANSION[] array, for example you can create two different expansion pages simply writing this lines for the expansion pages config in "config.php" file:

...

// First page type
$_EXPANSION[0]['page']['enabled'] = true;
$_EXPANSION[0]['page']['exec'] = 'page1.php'; // This file is the executable for the page with index 0
$_EXPANSION[0]['page']['label_index'] = 3;

// Second page type
$_EXPANSION[1]['page']['enabled'] = true;
$_EXPANSION[1]['page']['exec'] = 'page2.php'; // This file is the executable for the page with index 1
$_EXPANSION[1]['page']['label_index'] = 4;

...



Pages parameters: Description:
$_EXPANSION[i]['page']['enabled'] If true the you can use this expansion as an expansion page. If false you can not use this expansion as an expansion page and all the pages parameters will be ignored.
$_EXPANSION[i]['page']['exec'] The name of the executable (.php) file relative to the pages, is the file that will execute when this expansion its used as expansion page.
$_EXPANSION[i]['page']['label_index'] Index (in language file) of expansion field menu label in add/edit pages form (this parameter is optional, if you do not specify this parameter the index "i" will be used as menu label).

Panels parameters: Description:
$_EXPANSION[i]['panel']['enabled'] If true the you can use this expansion as an expansion panel. If false you can not use this expansion as an expansion panel and all the panels parameters will be ignored.
$_EXPANSION[i]['panel']['exec'] The name of the executable (.php) file relative to the panels, is the file that will execute when this expansion its used as expansion panel.
$_EXPANSION[i]['panel']['label_index'] Index (in language file) of expansion field menu label in add/edit panels form (this parameter is optional, if you do not specify this parameter the index "i" will be used as menu label).

Warning: The page or panel with index 0 in $_EXPANSION array must be enabled and correctly configured for a correct use of the other pages or panels with index > 0.

2) Expansion executable files:
An executable file its a php file that will contain the expansion code, you can create a different executable file for each expansion part.
Executable file must have the following structure:

<?php

defined('WM3_cEXEC') or die('Denied');

// Your code here

?>

In the executable file you can use all the api of Webmatic (see APIs references).
In an executable file you can use also a global variable called "$w3", this variable is a global instance of "webmatic3" class. You can use the $w3 global variable to call all the public and non static methods of webmatic3 class, for example you can write:

$w3->getHomeLanguage();

to retrive the current home page language ID.

3) Expansion languages files:
To create a multilanguage expansion you need to create a language file for each language you want to support in the expansion.
According with $_EXPANSION['language_path'] parameter, you must create in the folder specified in $_EXPANSION['language_path'] parameter all the language files you need (in this folder you must create at least the "language_en.php" file because english is the default expansions language).
All the language file you need to create must have this name "language_xx.php" where "xx" is the standard language code (for example "language_it.php", "language_de.php", ...).
A language file must have the following structure:

<?php

defined('WM3_cEXEC') or die('Denied');

// Expansion words
$this->_WORD_EXPANSION[0] = "My expansion title"; // Default expansion title
$this->_WORD_EXPANSION[1] = "My expansion admin label"; // Default administrator area label
$this->_WORD_EXPANSION[2] = "My expansion user label"; // Default user area label
$this->_WORD_EXPANSION[3] = "My first word for the expansion";
$this->_WORD_EXPANSION[4] = "My second word for the expansion";
$this->_WORD_EXPANSION[5] = "Another word for the expansion";
...

?>


Expansions custom parameters:


When you build an expansion you may need to pass it some custom parameters.
To give the parameters and the respective values to an expansion page or panel, you must insert them in the "Expansion parameters" field when you create an expansion panel or an expansion page (see user manual and picture 1).
You must insert in a first line the parameter names in brackets and the values must follow the parameter names in a second line (you can use only a single line for the value). As shown in picture 1 there are 2 parameters (name and age) with 2 values ("Peter" for the "name" parameter and "32" for the "age" parameter).


(1)

You can use the expansion parameters with some simple functions, you can use those functions in an executable (.php) file.

Function: Description and example:
getParameter($name,$default='') To get a parameter value from an executable (.php) file you can use the function getParameter(). To this function you must pass a string with the name of the parameter and the value to set if the parameter its not defined (empty for default).

For example, to get the value of the parameter "total" and put it in $total variable you can write in the executable (.php) file:

<?php

defined('WM3_cEXEC') or die('Denied');


$total = $this->getParameter('total', 1);

?>

getParametersArray() This function return an array with all the parameters and the respective values.

This example show how to get all parameters/values and print out them:

<?php

defined('WM3_cEXEC') or die('Denied');

// Get all parameters and puts them into an array.
$_PARAMETERS = $this->getParametersArray();

$output = ''; // Init the output to empty
foreach ($_PARAMETERS as $key => $value)
 {
  // Get the parameter/value and put it in the output
  $output .= $key.': '.$value."<br />";
 }

echo $output; // Print out all

?>