[commits] [Wiki] changed: Doc/Dev/HordeKolabFormat
Wiki Guest
wikiguest at horde.org
Sat Nov 12 21:45:09 UTC 2011
guest [63.252.205.228] Sat, 12 Nov 2011 21:45:09 +0000
Modified page: http://wiki.horde.org/Doc/Dev/HordeKolabFormat
New Revision: 2
Change log: Rewrote part of the documentation. Still needs some more work.
@@ -1,41 +1,40 @@
-+Introduction
++Horde_Kolab_Format
-The '''Kolab_Format''' package allows you to easily read and write
the Kolab format using PHP.
+The {{Horde_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
+ pear install horde/Horde_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:
+This section will present a short example script to demonstrate
reading/writing an event in the Kolab XML format. The following
assumes you have a working '''PSR-0''' compliant autoloader setup.
+This will automatically pull in all required classes. You can of
course use the default Horde setup:
<code type="php">
- require_once 'Horde/Kolab/Format.php';
+ require_once 'Horde/Autoloader/Default.php';
</code>
-The API provided by the package is very simple. It only provides a
'''load()''' and a '''save()''' function.
+Make sure you have the '''{{Horde_Autoloader}}''' package installed
('''{{pear install horde/Horde_Autoloader}}''').
-In order to have access to these methods it is necessary to create
the '''Horde_Kolab_Format''' object. The call looks like this:
+The API provided by the central '''{{Horde_Kolab_Format}}'''
interface 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 a
parser implementing the '''{{Horde_Kolab_Format}}''' interface. The
'''{{Horde_Kolab_Format_Factory}}''' object is the helper that will
generate a parser for you. The required calls look like this:
<code type="php">
- $format = Horde_Kolab_Format::factory('XML', 'event');
+ $factory = new Horde_Kolab_Format_Factory();
+ $format = $factory->create('Xml', 'event', array('version' => 1));
</code>
-The function takes three arguments:
+The first argument indicates the '''format type''': Currently only
'''Xml''' is supported here. The second argument specifies the desired
type of object that should be read or written. The package currently
implements '''contact''', '''distributionlist''', '''event''',
'''note''', '''task''' and '''hprefs'''. The third argument holds a
set of optional parameters for the parser. Here we specify that we
expect the parser to adhere to the internal data API version 1.
-# '''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:
+The '''{{$format}}''' 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,
@@ -44,21 +43,23 @@
'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 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:
+This event can now be saved using the '''{{save()}}''' function of
the format handler:
+<code type="php">
$xml = $format->save($object);
+</code>
-The function returns the Kolab XML format as a result. This string
can be fed back into the '''load()''' function:
+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:
+If we dump the contents of the two variables '''{{$xml}}''' and
'''{{$read_object}}''' this will be the result:
<code type="php">
var_dump($xml);
string(438) "<?xml version="1.0"?>
@@ -106,9 +107,9 @@
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
+* '''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'''.
@@ -249,8 +250,20 @@
* '''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'''.
+
+++Internal API versions
+
+TODO
+
+++External API versions
+
+TODO
+
+++Xml attribute types
+
+TODO
++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.
+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 {{Horde_Kolab_Format}} in the package
selection box in the upper right corner.
More information about the commits
mailing list