|
|
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/ |
|
|
|
|
|
|
|
|
|
|
|
|
| / / Tools |
|
|
|
|
|
|
|
|
|
|
|
NOTE! EXPERIMENTAL. WILL BE IMPLEMENTED IN HammerKit v4
Tools are the small applications that are used in the HammerKit admin
for building and managing a HammerKit site. Tools are, like modules and
filters, extensions to HammerKit and can be "installed" like
applications to be used in the admin. Tools implement a very strict
interface in order to interact with the HammerKit core. This interface
is explained in detail here.
The Tool Package
A HammerKit tool 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 tool class name. Inside this folder is the main tool class file with the file name Class.php. The class inside the tool class file must be named exactly the same as the main folder of the tool. The main tool class must extend the HammerKit_Tool class. More detailed info can be found on the manual page for the HammerKit_Converter class.
Below is the file hierarchy of a tool where [tool_class_name] represents the class name of the tool. The name should be globally as unique as possible, so don't be afraid to give your tool classes long names.
[tool_class_name]/
Class.js
Class.php
lang/
The Class.php file contains the definition of the tool class with the name [tool_class_name].
The lang folder contains files with user interface texts definitions in different languages. The files are named [language_code] 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 tool'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 tool'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 tool can freely specify subfolders to the tool for
files and for instance other class definition files for classes the tool might need. For the system to be able to locate class definition
files they have to be placed in the root of the tool 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.
Tool Groups
There are five predefined tool groups in HammerKit. All tools have to belong to one of these groups. The tool groups are home, content, storage, accounts, system and none.
The HammerKit Admin API
This API is used for making Ajax calls to HammerKit tools. The calls are made
to the tools and specifically the classes extending the HammerKit_Tool
class. HammerKit defines a global Javascript object with the name HammerKit. This object contains a property with the name admin that contains the HammerKit_Admin object. The HammerKit_Admin has a method called ajax with three arguments:
HammerKit.admin.ajax(systemCallback, successCallback, errorCallback)
Argument: systemCallback
Description: This is an object that defines the properties of the function call made to the system. The object has the following properties:
string class
Description: The name of the admin tool class extending the abstract HammerKit_Tool class.
string method
Description: The name of the admin tool class' method to call.
optional string[] args
Description: An array of arguments for the method.
optional boolean static
Description: Defines if the method call is to be made as static. The default value of this parameter is false.
optional string dataType
Description: This defines the type of the value returned by the method call. The value can be either text or json. By default the value is json.
Argument: successCallback(returnValue)
Description: This is a Javascript function that is called after a successful function call. The function gets as an argument the return value of the function call. The format of the return value is determined by the dataType property of the systemCallback object. If the value is json then the return value is automatically converted to Javascript objects.
Argument: errorCallback(XMLHttpRequest, textStatus, errorThrown)
Description: This function is called if the ajax request could not be completed due to some error.
This class specifies the methods that all HammerKit_Tool
extending converter classes have to implement. In addition to the
methods defined in the abstract HammerKit_Tool class other methods can
be freely defined. These user defined methods are used in the tool's
user interface through Ajax calls to the HammerKit Admin API which is
defined above.
string TOOL_GROUP
Description: The code name of the tool group in which this tool appears. See info about tool groups above.
integer TOOL_GROUP_ORDER_NUMBER
Description: The order number of the tool in it's tool group. This determines the position of the tool in menus and tool lists.
string COPYRIGHT
Description: Copyright text for the tool.
string AUTHOR
Description: The name of the author of the tool.
string MAX_PHP_VERSION
Description: The number of the PHP version the tool has been tested to work with. If this PHP version in use is newer than this, it does not mean the tool 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 tool has been
tested to work with. If this HammerKit version in use is newer than this, it
does not mean the tool 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 tool 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 tool 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 tool 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 tool needs to function. 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 tool. The version must comply with the PHP version numbering scheme. See PHP function version_compare for more information.
optional public string getName([$lang=null])
Description: An optional function for defining the name of the tool shown in the user interface. If this method is not defined then the name is by default fetched from the language file definition with the key name name.
Returns: A string with the name of the tool in the language specified by the $lang argument.
public string getUi(void)
Description: Get the user interface for the tool. This is appended by HammerKit admin to the DOM of the admin user interface.
Returns: A valid XHTML string containing all needed for using the tool. This includes all Javascript code and style definitions.
class MyGloballyVeryUniqueToolClassName extends HammerKit_Tool {
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 AUTHOR = 'Matti Meik�l�inen / Koodaajat Oy';
const COPYRIGHT = 'Bla bla...';
const TOOL_GROUP = 'home';
const TOOL_GROUP_ORDER_NUMBER = 3;
public function getUi() {
}
}
optional boolean __close(void)
Description: This method is called automatically when a tool is closed. The method is intended for use in tools with editor functions that require saving of changes. This method could check if the tool has any unsaved changes and can prevent the tool from being closed.
Returns: If this method returns FALSE the closing of the tool will open a confirm dialogue asking the user if it is ok to close the tool. If the confirm dialogue returns false the tool will not be closed. If this method returns TRUE the tool will be closed without asking.
optional void __init(void)
Description: This method is intended for handling initialization routines for the tool. If this method is defined it is called automatically by the admin when the tool is opened.
optional void __resize(void)
Description: This method is called when the document view is resized. For instance resizing of the browser window triggers this event.
optional void __update(void)
Description: This method is called automatically by HammerKit's admin UI at certain intervals. This method is used for updating for instance object lists in the UI. The object lists can change in the database if other users makes updates to them. Then the changes wouldn't show if the lists weren't updated automatically.
function MyGloballyVeryUniqueToolClassName() {
}
MyGloballyVeryUniqueToolClassName.prototype.__init = function() {
}
MyGloballyVeryUniqueToolClassName.prototype.__close = function() {
}
MyGloballyVeryUniqueToolClassName.prototype.__resize = function() {
}
MyGloballyVeryUniqueToolClassName.prototype.__update = function() {
}
|
| � HammerKit Oy 2008 |
UPDATED: 09.02.2009 15:00 |
|