Datatype.pod
NAME
Communiware::Datatype::* - pluggable datatype modules
SYNOPSIS
$datatype = $dbh->selectrow_array("select content_type from item_type
where type_id=?,{},getattr('TYPE_ID'));
eval "\$text=Communiware::Datatype::${datatype::save}(\$id,\$text,
\$attrs,\$picnamesref)
DESCRIPTION
Pluggable datatype modules allows different Communiware item types to handle their main contents absolutely differently.
Each item type definition contain CONTENT_TYPE field, which stores name of one of the modules in the Communiware::Datatype hierarchy.
When Communiware performs editing operations on item, it calls methods of these modules to obtain editable representation of the item contents or to store it.
Pluggable datatype implementation is not a proper perl object class. It is just a module which defines set of functions with standartized interface and names, called methods below.
Name of the module must be in the Communiware::Datatype namespace
METHODS
save
Syntax
save($item_id,$text,$attrs,$picnames)
This method is basic method for storing information in the Communiware. It is called just before create_item or update_item operation
It recieves text of item as it is provided by user (either via web form or in the dump file) and returns processed text to pass into create_item or update_item. It may also have side effects such as storing data into Communiware pictures area.
If for some reason provided data are not acceptable as item content, this method should throw an error to be handled by caller.
Parameters:
- $item_id
- Identifier of item to be created/updated.
- $text
- Contents of the item to be preprocessed/validated etc.
- $attrs
- Hash of other item attributes, known at the time method is called.
-
At least TYPE_ID is guaranteed to present.
-
Along with attributes this hash could contain datatype-specific options See the options manpage method.
-
Method is allowed to modify this hash by adding some attribute values, which were not specified explicitely but can be derived from processing of text.
- $pictnames
- Hash, which maps names of pictures as they come in HTTP request (and possibly appear in the item text) to the names they would recieve when stored in Communiware pictures area. Only pictures which were uploaded via same form as text are counted.
upload
Syntax
upload($item_id,$filehandle,$attrs,$charset,$picnames)
This method is used instead of save when data are to be read from file (including file upload form) rather then were entered by user in the form.
It could provide support for data formats which are never entered in the form, such as rtf files for Html datatype.
Parameters are rougly same as in the the save manpage method but filehandle reference is provided instead of text itself, and there is additional parameter $charset. This parameter is only meaningful if Communiware works under Russian Apache. In this case Communiware recodes all data except file upload fields into server encoding. So information about client charset should be provided for upload method to handle non-recoded data.
get
Syntax
get($id,$text,$charset,$representation)
Should return content of the item in the form, suitable for storing in the dump files and editing.
Parameters:
- $id
- Identificator of item to be presented
- $text
- Text of this item as it was stored in the database
- $charset
- Character set data would be eventually recoded to. May be used for providing for instance <META> tag for offline Html browser/editor
- $representation
- If given datatype supports multiple editable representation, this parameter specifies representation to return. See the representations manpage
methods
Returns list of additional content handling methods, which can be defined for the particular datatype. For instance, Filter datatype can have test and explain_plan methods.
It is intended that form for editing items of such type would contain submit buttons for these methods, and when this button is pressed, appropriate method (instead of save or upload would be invoked
Actually, no presently defined datatypes use additional methods, and this is not fully supported by Communiware::Posting module
options
Returns list of options which should be passed to save and upload methods.
If there exist form parameters with names contained in returned list, they will be added to $attrs hash passed to the save manpage or the upload manpage.
representations
Syntax:
%repr = representations();
Returns hash. Keys in this hash are source representation names, values for each key are array references. These arrays contain possible representations for known source representation.
If item has several representations, it means that there is more than one editable format which contain (almost) all information of item. For instance, for HTML there is HTML representation and plain text (more exactly RICHTEXT) representation.
Methods the save manpage and the upload manpage are required to automatically distinguish between representations.
Method the get manpage recieves desired representation as a parameter.
set_errorInfo
Syntax
set_errorInfo(filename,linenumber)
When datatype is able to detect data errors and throw exception, it should return filename and linenumber of the error.
If text of item, passed into the save manpage method is extracted from bigger file, caller of the Datatype calls set_errorInfo before save and specifies file name and offset where text, passed to save method starts. This allows error message to be correctly interpreted for instance by vim quickfix subsystem without need to parse and rewrite error message by caller.