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 home page (not jet implemented).

Each part have the rules to execute the expansion in the different area of your website. You can also create a multilanguage 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 used in expansion pages;
- An executable (.php) file used in expansion panels;
- An executable (.php) file for home page (not jet implemented);
- 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 parameter: 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 parameter: 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 parameter: 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".

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 parameter: 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 parameter: 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.

Home parameter: Description: (not jet implemented)
$_EXPANSION['home']['enabled'] If true the you can use this expansion in home page. If false you can not use this expansion in home page and all the home parameters will be ignored.
$_EXPANSION['home']['exec'] The name of the executable (.php) file relative to the panels, is the file that will execute when this expansion its used in home page.

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";
...

?>