Simple fromString and toString interface for attributes

This is a copy of only document available that describes the extremely useful toString and fromString functions of datatypes, which greatly simplify storing and retrieving attributes in php.

This is a design document, so there may be some inaccuracies but it seems to work ok into the 4.2 series. It is recommended to verify the format of not-trivial datatypes by doing toString on attribute of that type with data in it and examining output.

Source: http://pubsvn.ez.no/nextgen/trunk/doc/features/3.9/to_from_string_datatype_functionality.txt

To simplify writing of import export scripts we have added two functions to the ezcontentobjectattribute class. Also related functions with the same name have been added to the datype interfase and to all datatypes in standard eZ Publish distribution exept of ezenum which is now deprecated and ezpackage which is not used.

To show possibilities of these functionality two scripts have been added under bin/php/. These scripts are very simple CSV import/export scripts:
- ezcsvimport.php
- ezcsvexport.php
They are very basic and do not pretend to be fully functional CSV import/export for ezpublish though you can use them to do real import/export. Here is a description of formats which are accepted by the datatypes for
fromString( &$contentObjectAttribute, $string ), and generated by toString( $contentObjectAttribute ) methods.

ezauthor:
To separate one author from another '&' char is used, to separate parts of author data '|' is used. The system escapes '|','&','\' with the '\' char.
Example of toString result:

Administrator User|[email protected]|0&Sergiy|[email protected]|1&SP|[email protected]|2

To make it easy to parse such kind of strings the class ezstringutils is added under lib/ezutils. It has to functions as a members.
explodeStr( $str, $delimiter = '|' ) and implodeStr( $str, $delimiter = '|' ). The first one explodes string to an array with delimiter char, the difference from PHP explode/implode is that these functions do propper escaping/unescaping of all values.

ezbinaryfile:
toString function of this datatype return string of format:
filepath|original_filename
filepath is to a file in filesystem so you can make copy of the file.
original_filename is the original filename of uploaded file as string.
To import binary file to the attribute you need to supply it with full path
to the source file, which will be copied into system.

ezboolean:
Returns and accepts 1 or 0 for true and false accordingly.

ezcountry:
Returns comma-separated list of selected countries locale strings, ex.:
rus-RU,eng-GB,nor-NO

ezdate:
Returns and accepts unix timestamp of the date.

ezdatetime:
Returns and accepts unix timestamp of the date.

ezemail:
Returns and accepts email address.

ezenum:
Not supported (deprecated)

ezfloat:
Returns and accepts float number.

ezimage:
Returns path to file containing original alias (size) of the image, so it can be copied. Accepts full path to original image you want to import, it will be copied into system.

ezinisetting:
Returns and accepts value of an inisetting.

ezinteger:
Returns and accepts integer value.

ezisbn:
Returns and accepts ISBN number as string

ezkeyword:
Returns and accepts comma separated list of keywords.

ezmatrix:
Identical to ezauthor datatype. The columns are sparated with '|' and rows are separated with '&'

ezmedia:
toString function of this datatype return string of format:
filepath|original_filename
filepath is to a file in filesystem so you can make copy of the file.
original_filename is the original filename of uploaded file as string.
To import binary file to the attribute you need to supply it with full path
to the source file, which will be copied into system.

ezmultioption:
The first '&' separated value is the name of multioption set, then each '&' separated string represents
each option in multioption set. This string it self is '|' separated value, that consist of, in this order:
_name_ of the option and the _id_ of option item which should be selected by default. After these two
values we have option_value and additional price for the option item.

ezmultiprice:
The structure of a data handled by this data type is
currency_name_1|value_1|type_of_price_1|currency_name_2|value_2|type_of_price_2|......currency_name_n|value_n|type_of_price_n|
Where currency_name is thre char currency name like EUR,USD and so on,
value is the price in this currency,
and type can be AUTO or CUSTOM dependin on if the price in this currency
has been inserted by user or calculated automaticaly.

ezobjectrelation:
Returns and accepts ID of related object.

ezobjectrelationlist:
'-' separated list of related object ID's.

ezoption:
'|' separated list of name of the option and then | sparated list of option_item|additional item price values.

ezprice:
'|' separated list of price, VAT id, and flag wether VAT is included to the price or not.

ezproductcategory:
Returns '|' separated string with product category name and category id. Accepts just category
name as a papameter.

ezrangeoption:
'|' separated string contains name of the option, start,stop and step values for the option.

ezselection:
'|' separated list of selected item names.

ezstring:
Returns and accepts the string value.

eztext:
Returns and accepts the string value of eztext field.

eztime:
String with the time of the day in HH:MM , 24h format

ezurl:
string containing the url or a url|text

ezuser:
'|' separated string with user login, email, password hash, and password hash type.

ezxmltext:
Returns valid ez publish xml, and expects the same as input.