Author: Raymond Bosman Date: 2006-06-12 12:49:38 +0200 (Mon, 12 Jun 2006) New Revision: 3114
Log: - DR and I made the tutorial better readable. Modified: trunk/PersistentObjectDatabaseSchemaTiein/docs/tutorial.txt Modified: trunk/PersistentObjectDatabaseSchemaTiein/docs/tutorial.txt =================================================================== --- trunk/PersistentObjectDatabaseSchemaTiein/docs/tutorial.txt 2006-06-12 08:12:00 UTC (rev 3113) +++ trunk/PersistentObjectDatabaseSchemaTiein/docs/tutorial.txt 2006-06-12 10:49:38 UTC (rev 3114) @@ -6,8 +6,8 @@ Introduction ============ -The PersistentObjectDatabaseSchemaTiein component allows you to generate the -basic PersistentObject definition files for a database structure from a +The PersistentObjectDatabaseSchemaTiein component allows you to generate +template PersistentObject definition files for a database structure from a DatabaseSchema schema file. Most likely you have to adjust the PersistentObject definitions afterwards. @@ -16,119 +16,115 @@ :: - $ php rungenerator.php -s <string> -f <string> [-h] [[--] <args>] + $ php rungenerator.php -s <string> -f <string> [-h] [--] <target_directory> -The component contains a runnable script, which can be called using the PHP -command line interpreter (CLI). You have to provide 2 options for it: +The component contains an executable script, which can be called using the PHP +command line interpreter (CLI). You have to provide two options: -s / --source <string> This option determines the source DatabaseSchema file to generate the PersistentObject definitions from. -f / --format <string> - This option determines the format of the provided source schema file. For a - list of valid formats, please refer to the `PersistentObject API`_ - documentation. + This option determines the format of the provided source schema file. + Examples are 'xml' and 'array'. For a full list of valid formats, please + refer to the `PersistentObject API`_ documentation. -.. _`PersistentObject API`: http://ez.no/doc/components/view/latest/(file)/classtrees_DatabaseSchema.html +.. _`PersistentObject API`: classtrees_DatabaseSchema.html -Additionally a help option is available, which can be accessed using -h / ---help. You can find on-the-fly usage information here. +There is also a help option available that can be accessed with -h or +--help. -As an argument to the generator you have to provide a directory where the -PersistentObject definitions will be stored. Make sure, that you have the -permission to write to this directory, before you run the script. +The 'target_directory' argument specifies the directory where the +PersistentObject definitions are stored. Make sure that script can write to +this target directory. + Usage ===== -The usage of the generator script is easy. You have to have a working eZ -components installation in place to make it work. Run the script from the main -eZ components source directory using the following command:: +Run the script from the main eZ components source directory using the following +command:: $ php PersistentObjectDatabaseSchemaTiein/rungenerator.php -By default, you will see a short help information on how to use the tool. To -automatically generate PersistentObject definitions, you need a valid -DatabaseSchema file for your database structure. You can generate this from -your database directly, using the DatabaseSchema component. For detailed +By default, you will see a short help description on how to use this tool. + +You need a valid DatabaseSchema file for your database structure to generate +PersistentObject definitions. You can generate a DatabaseSchema file from +your database with the DatabaseSchema component. For detailed information, please refer to the `PersistentObject API`_ documentation. -Once you have a valid DatabaseSchema file, you have to create a directory, -where your PersistentObject definitions shall be stored. Now you can use the -rungenerator.php script to create the basic definition files. Use the following -command to do this:: +Once you have a valid DatabaseSchema file, you should create a directory +where your PersistentObject definitions will be stored. Then you can use the +rungenerator.php script to create the template definition files. Use the following +command:: - $ php PersistentObjectDatabaseSchemaTiein/rungenerator.php -s path/to/schema.file -f array path/to/persistentobject/definition/dir/ + $ php PersistentObjectDatabaseSchemaTiein/rungenerator.php \ + -s path/to/schema.file -f array path/to/persistentobject/definition/dir/ You have to replace the paths according to the example. The -s parameter -defines, where the DatabaseSchema definition can be found. The -f option +defines where the DatabaseSchema definition file can be found. The -f option indicates the format of the schema file. In this case, it is a PHP array definition, another common format is XML. The last part of the command line -call specifies the directory to store the generated PersistentObject -definitions to. +call specifies the target directory to store the generated PersistentObject +definitions in. -Reworking -========= +Customizing Definitions +======================= -The generator script assumes, that the names of your PersistentObject classes -and their properties map exactly to the table / column names of your database -structure. For example, if you have a table called ez_persistent_objects, which -contains a column named persistent_object_id, you have to use a class with -the exactly same name as your table, that has a property called exactly like -your column. +The generator script assumes that the names of your PersistentObject classes +and their properties map exactly to the same table and column names of your database +structure. For example, a table called ez_persistent_objects with the column +persistent_object_id results in a class ez_persistent_objects and the property +persistent_object_id. -If you don't want to have a mapping like this, you have to edit the -generated PersistentObject files manually. The mapping of class <-> table names -is done through the properties of the main ezcPersistentObjectDefinition -object. The "table" property should be correct, since this one is taken from the -database definition. Adjust the "class" property according to your needs. -*Attention*: If you change the class name of a PersistentObject definition, you -have to rename the file it is contained in, accordingly. The file names for a -PersistentObject definition must be the same as the class name, completely -written in lower case! +If you want a different mapping then you can edit the generated +PersistentObject files manually. The class to table name mapping is done +through the properties of the main ezcPersistentObjectDefinition object. The +"table" property should be correct as it is taken from the database definition. +Adjust the "class" property according to your needs. +*Note*: If you change the class name of a PersistentObject definition, you have +to rename the file name accordingly. The file name for a PersistentObject +definition must be the same as the class name, completely written in lower +case. + The same procedure applies to the property definition of your -PersistentObjects. The mapping of column <-> object property is done using the -class ezcPersistentObjectProperty. The "columnName" property of the definition -objects should be correct, since this one is taken from your database schema -file. You can adjust the "propertyName" properties, according to your needs. +PersistentObjects. The column name to object property mapping is defined by the +ezcPersistentObjectProperty class. The "columnName" property of the definition +objects should be correct as it is taken from your database schema +file. You can adjust the "propertyName" properties according to your needs. -Last, the generator script will try to guess the PHP types of your -PersistentObject properties. This should most likely work correctly, since the -following mapping is used: +The generator script guesses the PHP types of your PersistentObject properties. +It uses the following mapping: -integer - ezcPersistentObjectProperty::PHP_TYPE_INT -timestamp - ezcPersistentObjectProperty::PHP_TYPE_INT +:integer: ezcPersistentObjectProperty::PHP_TYPE_INT +:timestamp: ezcPersistentObjectProperty::PHP_TYPE_INT +:float: ezcPersistentObjectProperty::PHP_TYPE_FLOAT +:decimal: ezcPersistentObjectProperty::PHP_TYPE_FLOAT +:text: ezcPersistentObjectProperty::PHP_TYPE_STRING +:time: ezcPersistentObjectProperty::PHP_TYPE_STRING +:date: ezcPersistentObjectProperty::PHP_TYPE_STRING +:blob: ezcPersistentObjectProperty::PHP_TYPE_STRING +:clob: ezcPersistentObjectProperty::PHP_TYPE_STRING -float - ezcPersistentObjectProperty::PHP_TYPE_FLOAT -decimal - ezcPersistentObjectProperty::PHP_TYPE_FLOAT +If the mappings are incorrect, you can adjust the "propertyType" properties of +your ezcPersistentObjectProperty definitions. -text - ezcPersistentObjectProperty::PHP_TYPE_STRING -time - ezcPersistentObjectProperty::PHP_TYPE_STRING -date - ezcPersistentObjectProperty::PHP_TYPE_STRING -blob - ezcPersistentObjectProperty::PHP_TYPE_STRING -clob - ezcPersistentObjectProperty::PHP_TYPE_STRING -If you have problems with these mappings, you will have to adjust the -"propertyType" properties of your ezcPersistentObjectProperty definitions -accordingly. - More Information ================ For more information, see the API documentation of -ezcPersistentObjectDefinition, ezcPersistentObjectProperty, -ezcDbSchema and ezcDbschemaPersistentWriter. +ezcPersistentObjectDefinition_, ezcPersistentObjectProperty_, +ezcDbSchema_ and ezcDbSchemaPersistentWriter_. +.. _ezcPersistentObjectDefinition: PersistentObject/ezcPersistentObjectDefinition.html +.. _ezcPersistentObjectProperty: PersistentObject/ezcPersistentObjectProperty.html +.. _ezcDbSchema: DatabaseSchema/ezcDbSchema.html +.. _ezcDbSchemaPersistentWriter: DatabaseSchema/ezcDbSchemaPersistentWriter.html + + .. Local Variables: -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
