[commits] [Wiki] created: Doc/Dev/HordeKolabFormat
Wiki Guest
wikiguest at horde.org
Sat Nov 12 21:10:00 UTC 2011
guest [63.252.205.228] Sat, 12 Nov 2011 21:10:00 +0000
Created page: http://wiki.horde.org/Doc/Dev/HordeKolabFormat
+Introduction
The '''Kolab_Format''' package allows you to easily read and write the
Kolab format using PHP.
++Installation
The package is being distributed as a standard [http://pear.php.net
PEAR] package by the Horde project. As long as you have
[http://pear.php.net PEAR] installed, installation should be straight
forward.
<code type="php">
pear channel-discover pear.horde.org
pear install --force channel://pear.horde.org/Kolab_Format
</code>
'''pear''' will probably complain about the library (and its
dependencies) not being marked stable yet but the '''--force''' option
allows to ignore these warnings.
++Using the package
This section will present the construction of a short example script
to demonstrate reading/writing an event in the Kolab XML format. The
first required statement is the inclusion of the package:
<code type="php">
require_once 'Horde/Kolab/Format.php';
</code>
The API provided by the package is very simple. It only provides a
'''load()''' and a '''save()''' function.
In order to have access to these methods it is necessary to create the
'''Horde_Kolab_Format''' object. The call looks like this:
<code type="php">
$format = Horde_Kolab_Format::factory('XML', 'event');
</code>
The function takes three arguments:
# '''Format type''': Currently only ''''XML'''' is supported here.
# '''Object type''': The type of object you want to read/write. The
package currently implements ''''contact'''',
''''distributionslist'''', ''''event'''', ''''note'''', ''''task''''
and '''hprefs''''
The <tt>$format</tt> variable created above now provides the means to
save and load events in Kolab XML format. In order to save an event we
need to prepare an array with all relevant information about this event:
<code type="php">
$object = array(
'uid' => 1,
'summary' => 'test event',
'start-date' => time(),
'end-date' => time() + 24 * 60 * 60,
);
</code>
This is an event that has the '''UID''' of '''1''' and carries the
title ''''test event''''. It starts right now (''time()'') and ends in
a day (''time() + 24 * 60 * 60'').
This event can now be saved using the '''save()''' function of the
format handler:
$xml = $format->save($object);
The function returns the Kolab XML format as a result. This string can
be fed back into the '''load()''' function:
<code type="php">
$read_object = $format->load($xml);
</code>
If we dump the contents of the two variables <tt>$xml</tt> and
<tt>$read_object</tt> this will be the result:
<code type="php">
var_dump($xml);
string(438) "<?xml version="1.0"?>
<event version="1.0">
<uid>1</uid>
<body></body>
<categories></categories>
<creation-date>2008-07-10T12:51:51Z</creation-date>
<last-modification-date>2008-07-10T12:51:51Z</last-modification-date>
<sensitivity>public</sensitivity>
<product-id>Horde::Kolab</product-id>
<summary>test event</summary>
<start-date>2008-07-10T12:51:51Z</start-date>
<end-date>2008-07-11T12:51:51Z</end-date>
</event>
"
var_dump($read_object);
array(11) {
["uid"]=>
string(1) "1"
["body"]=>
string(0) ""
["categories"]=>
string(0) ""
["creation-date"]=>
int(1215694311)
["last-modification-date"]=>
int(1215694311)
["sensitivity"]=>
string(6) "public"
["product-id"]=>
string(12) "Horde::Kolab"
["summary"]=>
string(10) "test event"
["start-date"]=>
int(1215694311)
["attendee"]=>
array(0) {
}
["end-date"]=>
int(1215780711)
}
</code>
We see that the format stores a lot more information than we
originally provided. The resulting XML string does not only contain
the '''uid''', '''summary''', '''start-date''', and '''end-date'''.
Several additional attributes have been added. These were either
calculated or set to a default value.
* '''body''': holds the event description. We did not specify an event
description so this value has been set to an empty string.
* '''sensitivity''': events may be '''public''' or '''private''' with
'''public''' being the default
* '''categories''': Any Kolab object may be member of different
categories. As we didn't specify a category this value is also empty.
* '''creation-date''': The time stamp of the moment the object was created.
* '''last-modification-date''': The time stamp of the moment the
object was last modified.
* '''product-id''': The ID of the product that last touched this
object. If we use the '''Horde_Kolab_Format''' package it will always
be '''Horde::Kolab'''.
If we read the XML data back into an array all these new informations
are available within that array.
++Creating your own Kolab XML format
Currently the '''Horde_Kolab_Format''' implements the object types
'''contact''', '''distributionslist''', '''event''', '''note''',
'''task''' as they are defined within the [[Kolab Format]]
specification. In addition the Horde specific '''hprefs''' type is
available. It is used for storing Horde user preferences in the IMAP
store provided by the Kolab server.
Depending on the web application you might wish to connect with the
Kolab server these object types may not be enough. Do not hesitate to
define your own new type in that case. If you want it to find wider
distribution you should of course discuss it on the
[http://kolab.org/pipermail/kolab-format/ Kolab Format mailing list]
to get some feedback on the new type.
The '''Horde_Kolab_Format''' packages makes the definition of a new
object type rather straight forward. The following will explain the
creation of a very simple new object that only saves a single string
value.
This time it will be necessary to load the XML format definition, too.
Any new object type will extend this XML definition:
<code type="php">
require_once 'Horde/Kolab/Format.php';
require_once 'Horde/Kolab/Format/XML.php';
</code>
A new object type is represented by a class that extends
'''Horde_Kolab_Format_XML''':
<code type="php">
class Horde_Kolab_Format_XML_string extends Horde_Kolab_Format_XML {
var $_fields_specific;
function Horde_Kolab_Format_XML_string()
{
$this->_root_name = 'string';
/** Specific fields of this object type
*/
$this->_fields_specific = array(
'string' => array(
'type' => HORDE_KOLAB_XML_TYPE_STRING,
'value' => HORDE_KOLAB_XML_VALUE_MAYBE_MISSING,
),
);
parent::Horde_Kolab_Format_XML();
}
}
</code>
The class needs to end with the name of the object type. Here it is
just '''string'''.
The declaration '''var $_fields_specific;''' indicates that the new
object type has attributes beyond the basic set required for any Kolab
object. So this part may not be missing for a declaration of a new type.
The function creating the class
('''Horde_Kolab_Format_XML_string()''') needs to do three things:
* Declaring the XML root name which will be '''string''' here. It
should always match the type name.
* Declaring the specific attributes of the object. This part populates
the '''_fields_specific''' variable with an array describing the
possible object attributes. This will be described in more detail
[[Horde_Kolab_Format#Allowed fields|further below]].
* Calling the parent constructor using '''parent::Horde_Kolab_Format_XML()'''.
The new format can now be used as demonstrated in the initial event example:
<code type="php">
$format = Horde_Kolab_Format::factory('XML', 'string');
$object = array(
'uid' => 1,
'string' => 'test string',
);
$xml = $format->save($object);
$read_object = $format->load($xml);
var_dump($xml);
var_dump($read_object);
</code>
The result looks like this:
<code type="php">
string(347) "<?xml version="1.0"?>
<string version="1.0">
<uid>1</uid>
<body></body>
<categories></categories>
<creation-date>2008-07-10T13:28:36Z</creation-date>
<last-modification-date>2008-07-10T13:28:36Z</last-modification-date>
<sensitivity>public</sensitivity>
<product-id>Horde::Kolab</product-id>
<string>test string</string>
</string>
"
array(8) {
["uid"]=>
string(1) "1"
["body"]=>
string(0) ""
["categories"]=>
string(0) ""
["creation-date"]=>
int(1215696516)
["last-modification-date"]=>
int(1215696516)
["sensitivity"]=>
string(6) "public"
["product-id"]=>
string(12) "Horde::Kolab"
["string"]=>
string(11) "test string"
}
</code>
++Allowed fields
There are only a number of valid entries available to specify the
attributes a new object type may contain.
Each entry in the field list will look like this
<code type="php">
'attribute_name' => array(
'type' => HORDE_KOLAB_XML_TYPE_*,
'value' => HORDE_KOLAB_XML_VALUE_*,
),
</code>
'''attribute_name''' should be a short name describing the value that
should be stored. ''''type'''' must be set to one of the following
'''HORDE_KOLAB_XML_TYPE_*''' type values:
* '''HORDE_KOLAB_XML_TYPE_STRING''': A string.
* '''HORDE_KOLAB_XML_TYPE_INTEGER''': A number
* '''HORDE_KOLAB_XML_TYPE_BOOLEAN''': True or false.
* '''HORDE_KOLAB_XML_TYPE_DATE''': A date (e.g. 2008/08/08)
* '''HORDE_KOLAB_XML_TYPE_DATETIME''': A time and a date.
* '''HORDE_KOLAB_XML_TYPE_DATE_OR_DATETIME''': A date or a time and a date.
* '''HORDE_KOLAB_XML_TYPE_COLOR''': A color (#00BBFF).
* '''HORDE_KOLAB_XML_TYPE_COMPOSITE''': A composite element that
combines several attributes.
* '''HORDE_KOLAB_XML_TYPE_MULTIPLE''': Wrapper for an element that may
occur several times.
Examples for '''HORDE_KOLAB_XML_TYPE_COMPOSITE''' and
'''HORDE_KOLAB_XML_TYPE_MULTIPLE''' can be found in the definitions
currently provided by the '''Horde_Kolab_Format''' package.
The following ''''value'''' settings are allowed:
* '''HORDE_KOLAB_XML_VALUE_DEFAULT''': An attribute with a default value.
* '''HORDE_KOLAB_XML_VALUE_MAYBE_MISSING''': An attribute that may be
left undefined.
* '''HORDE_KOLAB_XML_VALUE_NOT_EMPTY''': An attribute that will cause
an error if it is left undefined.
* '''HORDE_KOLAB_XML_VALUE_CALCULATE''': A complex attribute that gets
its own function for calculating the correct value.
Examples for '''HORDE_KOLAB_XML_VALUE_CALCULATE''' can again be found
in the current object types implemented in '''Horde_Kolab_Format'''.
++Detailed package documentation
A detailed documentation based on the code comments and extracted via
phpDocumentor can be found [http://dev.horde.org/api/framework/ here].
Simply select the package '''Kolab_Format''' in the package selection
box in the upper right corner.
More information about the commits
mailing list