|
|
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/ |
|
|
|
|
|
|
|
|
|
|
|
|
| / / Converters |
|
|
|
|
|
|
|
|
|
|
|
NOTE! EXPERIMENTAL. WILL BE IMPLEMENTED IN HammerKit v4
Converters are pieces of PHP code with the sole purpose of converting some data from one format into another format. A typical and simple example is converting decimal representation of numbers in different countries. Internally PHP and HammerKit handles all decimals with a dot as the decimal separator. In many countries however a comma is the default character used as the decimal separator. To handle these kinds of conversions there is a converter that converts dot-separated decimal numbers into string representations with user defined decimal and thousands separators.
As a more complex example there could be a converter for converting for instance a HammerKit_User object into some kind of XML-string representation for use in another system or application.
Like modules also converters can be built by anyone and added to HammerKit as extensions to extend the converter library of HammerKit. HammerKit provides a basic set of converters for the most common data handling operations in web applications.
In practice converters are used when building modules through using the converter chooser. The converter chooser works similarly to other choosers in HammerKit. The chooser brings the list of available converters to the user interface and the selected converter's settings view. The list of converters in the chooser is context dependent and lists only the converters that handle the type of data defined by the module author. The chooser checks the converters' TYPES constant and list only the converters handling the types needed.
The Converter Package
Technically a converter resembles in many ways a module but is much lighter and simpler in functionality. Simplified the only function of a converter is to convert a value in a variable to some other value in another variable.
A HammerKit converter 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 converter class name. Inside this folder is the main converter class file with the file name Class.php. The class inside the converter class file must be named exactly the same as the main folder of the converter. The main converter class must extend the HammerKit_Converter class. More detailed info can be found on the manual page for the HammerKit_Converter class.
Below is the file hierarchy of a converter where [converter_class_name] represents the class name of the converter. The name should be globally as unique as possible, so don't be afraid to give your converter classes long names.
[converter_class_name]/
Class.php
lang/
eng.lang
fin.lang
swe.lang
...
The Class.php file contains the definition of the converter class with the name [converter_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 converter'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 converter'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 converter can freely specify subfolders to the converter for
files and for instance other class definition files for classes the converter might need. For the system to be able to locate class definition
files they have to be placed in the root of the converter 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.
Converter Settings User Interface
The converter method getSettingsUi returns the XHTML of the converter's
settings form elements. The form's start and end tags are added by
HammerKit, but the settings form elements for the converter have to be
added by the converter author.
All the XHTML form elements have to be named as param[parameter_name], where the param part comes from the HammerKit_Converter class getParameterName method and the parameter_name inside the brackets is the name of a converter's settings parameter accessed in the converter'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 converter 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 Converter Class
This class specifies the methods that all HammerKit_Converter
extending converter classes have to implement.
string COPYRIGHT
Description: Copyright text for the converter.
string CREATOR
Description: The name of the creator of the converter.
string MAX_PHP_VERSION
Description: The number of the PHP version the converter has been tested to work with. If this PHP version in use is newer than this, it does not mean the converter does not work. PHP usually ensures a backwards compatibility with older PHP versions.
string MAX_SYSTEM_VERSION
Description: The number of the HammerKit version the converter has been
tested to work with. If this HammerKit version in use is newer than this, it
does not mean the converter does not 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 converter 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 converter to work.
This value is used for generating automatic error messages if the
requirements are not met.
string RELEASE_DATE
Description: The date when the converter 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 converter 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 TYPES
Description: A comma separated list of the variable types this converter can handle. The types can be PHP's internal variable types boolean, string, integer, float and array or class names like HammerKit's internal HammerKit_Component, HammerKit_File etc.
string VERSION
Description: The version number of the converter. 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 converter's compat method
should be called. If the parameters of a converter have been saved with a version of this converter which is older than the current version number, then HammerKit
automatically calls the converter's compat method at run time.
optional public string[] compat(string[] old_parameters, string old_converter_version_number)
Description: This method handles backwards compatibility between
different versions of the converter. If the parameters have been saved
with an older version of the converter 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 converter. This method is
optional and is only called if it is defined and the converter's version
number is grater than the version number was when the element the converter is part of was last
saved.
Arguments: old_parameters is the parameters array of the converter, old_converter_version_number is the version number of this converter when the parameters were last saved
Returns: The parameters array with corrected values
public mixed exec(mixed data)
Description: All extending classes must implement this method. This method handles
the converting of the data according to the parameters given by the user.
Arguments: data is the value to be converted
Returns: The converted data.
public string getSettingsUi(void)
Description: Get the user interface for the converter's settings used in the converter chooser.
Returns: A valid XHTML string containing the form elements for setting the converter's parameter values.
class MyGloballyVeryUniqueConverterClassName extends HammerKit_Converter {
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 TYPES = 'integer,float';
public function compat(array $oldParameters, $oldConverterVersionNumber) {
return $fixedParameters;
}
public function exec($data) {
}
public function getSettingsUi() {
}
} |
| � HammerKit Oy 2008 |
UPDATED: 13.01.2009 15:57 |
|