|
|
Manual and Documentation
NOTE: This manual describes HammerKit version 3.5. To view documentation for the current release of HammerKit Studio, please go to http://manual.hammerkit.com/ |
|
|
|
|
|
|
|
|
|
|
|
|
| / / Modules |
|
|
|
|
|
|
|
|
|
|
|
NOTE! EXPERIMENTAL. WILL BE IMPLEMENTED IN HammerKit v4
Modules are pieces of code or software that bring some capabilities and functionalities to HammerKit. All components in HammerKit are built from instances of modules, which are called elements. Anyone can extend the capabilities of HammerKit by making own modules. This page explains in detail how modules are built.
The Module Package
A module is a ZIP-file containing a strictly defined set of files and folders. The first level in the ZIP-file hierarchy is a folder with exactly the same name as the module class name. Inside this folder is the main module class file with the file name Module.class.php. The class inside the module class file must be named exactly the same as the main folder of the module. The main module class must extend the HammerKit_Element class. More detailed info can be found on the manual page for the HammerKit_Element class.
Below is the file hierarchy of a module where [module_class_name] represents the class name of the module. The name should be globally as unique as possible, so don't be afraid to give your module classes long names.
[module_class_name]/
Class.php
Class.js
icon_[small|large].[gif|jpg|png]
lang/
eng.ini
fin.ini
swe.ini
...
The Class.php file contains the definition of the module class with the name [module_class_name].
The lang folder contains files with user interface texts definitions in different languages. The files are named [language_code].lang where [language_code] is the ISO 639-3 3-letter language code of the language. The file is automatically parsed by HammerKit and the interface texts are set in the module's lang property. The format of the language files are such that each interface text definition is on it's own row with the text key and the text separated by "=":
text1="Some interface text"
text2="another string"
The text keys will become the keys of the module's lang property array with according interface text as value. If there is no language file present for the currently used language, then the default language is English, with the ISO 639-3 language code eng.
The author of a module can freely specify subfolders to the module for files and for instance other class definition files for classes the module might need. For the system to be able to locate class definition files they have to be placed in the root of the module folder and named exactly [class_name].php, where class_name is the globally as unique as possible name of the class. By complying to this class definition file naming it is possible to autoload class definitions when the class is needed.
Module Settings User Interface
The module method getSettingsUi returns the XHTML of the module's
settings form elements. The form's start and end tags are added by
HammerKit, but the settings form elements for the module have to be
added by the module developer.
All the XHTML form elements have to be named as param[parameter_name], where the param part comes from the HammerKit_Element class method getParameterName and the parameter_name inside the brackets is the name of a module's settings parameter accessed in the module's action code as $this->parameters_parsed['parameter_name']. So a simple text input in the form with a parameter name of "foo" would be constructed in PHP like this:
'<input type="text" name="' . $this->getParameterName('foo') . '" value="' . $this->parameters['foo'] . '" />'
It is possible to give the module parameters type information by
appending a class name to the parameter name, separated by a colon. If
a module parameter with the name image_file is a HammerKit_File id, then it
would be named in the form as param[image_file:HammerKit_File]. It is also
possible to specify scalar types like integer, Boolean or float. If no
parameter type is specified then the value is always interpreted as a
string.
The Module Class
This class specifies the methods that all HammerKit_Element
extending module classes have to implement. The module classes are the
core of all functionality in HammerKit for building applications. All
module classes must extend the HammerKit_Element class which provides the common properties and methods for accessing component elements.
string AUTHOR
Description: The name of the author of the module.
string COPYRIGHT
Description: Copyright text for the module.
string GROUP
Description: The group of the module. This is used in the user interface where modules are listed and related modules are grouped together. The constant can have the following values: HammerKit_ElementGroup_Content, HammerKit_ElementGroup_Form, HammerKit_ElementGroup_Control, HammerKit_ElementGroup_DataHandling, HammerKit_ElementGroup_Other. If the constant is not defined the module will be placen in the HammerKit_ElementGroup_Other group.
string MAX_PHP_VERSION
Description: The number of the PHP version the module has been tested to work with. If this PHP version in use is newer than this, it does not mean the module doesn't work. PHP usually ensures a backwards compatibility with older PHP versions.
string MAX_SYSTEM_VERSION
Description: The number of the HammerKit version the module has been
tested to work with. If this HammerKit version in use is newer than this, it
does not mean the module doesn't work. HammerKit usually ensures a backwards
compatibility with older HammerKit versions.
string MIN_PHP_VERSION
Description: The number of the PHP version that is required for this module to work.
This value is used for generating automatic error messages if the
requirements are not met.
string MIN_SYSTEM_VERSION
Description: The number of the HammerKit version that is required for this module to work.
This value is used for generating automatic error messages if the
requirements are not met.
boolean QUICK_ADD
Description: This constant defines the behavior of the module when it is dragged to the component editing canvas. If this value is set to true no element settings window is opened when an element is added to the canvas and the element is added with default values for all the settings.
string RELEASE_DATE
Description: The date when the module version was released. The date must be represented in a format understood by PHP's strtotime function, but the format YYYY-MM-DD is recommended.
string REQUIRED_PHP_EXTENSIONS
Description: A comma separated list of the required PHP extensions this module needs to work. The name of the extension must be the same as reported by PHP's get_loaded_extensions function, which does a case sensitive comparison of the extension name.
string VERSION
Description: The version number of the module. The version must comply with the PHP version numbering scheme. See PHP function version_compare for more information. HammerKit uses this information for determining if the module's compat method
should be called. If an element has been saved with a version of this
module which is older than the current version number, then HammerKit
automatically calls the module's compat method at run time.
optional public string[] compat(string[] parameters, string old_module_version_number)
Description: This method handles backwards compatibility between
different versions of the module. If the parameters have been saved
with an older version of the module and the parameters or the values of
the parameters have changed since then it is possible to correct the
parameters to work with the new version of the module. This method is
optional and is only called if it is defined and the module's version
number is grater than the version number was when the element was last
saved.
Arguments: old_parameters is the parameters array of the module, old_module_version_number is the version number of this module when the parameters were last saved
Returns: The parameters array with corrected values
public string exec(void)
Description: Execute the module's functions.
Returns: The result output of the module.
optional public string[] getSettingsGroups(void)
Description: Get a list of the settings groups for the module's settings user interface.
Returns: An array where the keys are the names of the settings groups and the corresponding values are language dependent names of the groups shown in the user interface.
public string getSettingsUi(string group)
Description: Returns the user interface for the module's settings.
Arguments: group is the name of the settings group to show used for tabbing the settings ui
Returns: The XHTML string for the UI for module settings.
optional public string getTag(void)
Description: Gets the tag for representing the element of this module in the content editor.
Returns: The XHTML string for the tag.
optional public string getTagInfo(void)
Description: Gets the XHTML for an info box that is shown when the mouse is over the element tag in the content editor.
Returns: The XHTML string for the info box contents.
class MyGloballyVeryUniqueModuleClassName extends HammerKit_Element {
const VERSION = '1.0.2';
const RELEASE_DATE = '';
const MAX_PHP_VERSION = '5.2.5';
const MIN_PHP_VERSION = '5.2.1';
const MAX_SYSTEM_VERSION = '';
const MIN_SYSTEM_VERSION = '4.0.0';
const REQUIRED_PHP_EXTENSIONS = 'gd,json';
const CREATOR = 'Matti Meik�l�inen / Koodaajat Oy';
const COPYRIGHT = 'Bla bla';
const QUICK_ADD = false;
public function compat(array $oldParameters, $oldModuleVersionNumber) {
return $fixedParameters;
}
public function exec() {
}
public function getDescription() {
return $this->lang['description'];
}
public function getName() {
return $this->lang['name'];
}
public function getSettingsGroups() {
$groupList = array();
return $groupList;
}
public function getSettingsUi($group) {
}
public function getTag() {
}
public function getTagInfo() {
}
} |
| � HammerKit Oy 2008 |
UPDATED: 26.11.2009 16:26 |
|