howto.doxy

Go to the documentation of this file.

/** @page howto
 *
 * @section howto HowTos
 *
 * - @ref howtotype
 * - @ref howtonode
 * - @ref howtocontroller
 * - @ref howtoviews
 * - @ref howtoapplication
 * - @ref howtorights
 * - @ref howtoconcurrency
 * - @ref howtoi18n
 * - @ref howtologdebug
 * - @ref howtoerror
 *
 * @subsection howtotype Definition of the data model
 *
 * The data model defines the domain classes. In principle the following steps are necessary
 * to to make the domain classes available in the application:
 * 
 * -# Definition and creation of the database tables.@n
 * -# Implementation of the PersistenceMapper classes, which map the domain classes to the tables.@n
 * -# Creation of special domain classes, if the Node class is not sufficient.@n
 * 
 * Basically it doesn't matter, in which format the application data is stored. To load and store
 * data application developers solely have to communicate with the PersistenceFacade.
 * The PersistenceMapper classes have the actual knowledge of how to access the data.
 * This abstraction makes it for instance possible to easily migrate the data storage from file based
 * to databased. Only the mappers have to be exchanged. On the other hand it's also possible - an
 * adequate implementation of the mappers assumed - to access arbitrary database schemes, which
 * eases the connection of the wCMF to existing data sources.
 * 
 * In practice it has been proved as advantageous to use a database as storage medium, because it has
 * a better performance and can handle bigger amounts of data much better than XML files can.@n
 * It is recommended to define one table for each domain class in the database scheme (e.g. @em author, @em article).
 * On one hand it makes the import and export from and to other applications easier and on the other
 * hand the access to the data is optimized compared to storing all data in one table, because then
 * additional joins would be required to determine data types and other meta information. In addition the
 * table columns can be more easily adjusted to the needs of the domain classes (in an extreme case all data
 * must be stored as BLOB in an universal data table). NodeToSingleTableMapper implements the storage of all
 * data in one table, which - for the said reasons - isn't recommended.
 * 
 * Proceeding on these assumptions the creation of the data model becomes a lot simpler.
 * 
 * @subsubsection howtotables Definition of the database tables
 *
 * We start with step 1. Assuming we're in the fortunate situation of defining the database tables
 * ourselves. Then we proceed as follows.
 * 
 * - For each domain class we create one table.
 * - For each attribute of a domain class we define a row with the appropriate datatype.
 *
 * Further attributes follow a scheme, which is predefined by the NodeUnifiedRDBMapper. This
 * makes the creation of the mappers easier:
 * 
 * - Each table gets a primary key named @em id (int(11))
 * - If one table depends on another, it gets a foreign key @em fk_table_id (int(11)), where
 *   @em table stands for the name of the parent table.
 * 
 * If an N to M relation should be established between two domain classes (tables), a connection
 * table must be defined. This table contains two primary keys, which point to the two connected
 * tables.
 * 
 * As an example serves a domain class @em Article, which is related to an @em Author:
 * @verbatim
 CREATE TABLE `Article ` (
 `id` int(11) NOT NULL default '0',
 `fk_author_id` int(11) default NULL,
 `headline` VARCHAR(255),
 `text` TEXT,
 `sortkey` INT(3),
 PRIMARY KEY (`id`)
 ) TYPE=MyISAM; @endverbatim
 *
 * If the database tables already exist, this step is skipped. This however means, that more work
 * must be put into the implementation of the PersistenceMapper.
 *
 * @subsubsection howtomapper Implementation of the PersistenceMapper
 *
 * Of course it's always possible to write own mappers. These must inherit from PersistenceMapper
 * and implement the abstract methods given there.
 * Since the framework already provides mappers, it's easier to use these as base classes. In case of a relational
 * database it's possible to derive custom mappers from NodeRDBMapper. Then the methods for defining
 * the SQL statements must be implemented.
 * 
 * Assuming the database tables are created by the scheme above, we can proceed to the next step
 * and use NodeUnifiedRDBMapper as baseclass for our mappers. After that we have to implement the
 * methods RDBMapper::getType, NodeRDBMapper::createObject, NodeUnifiedRDBMapper::getTableName,
 * PersistenceMapper::getPkNames, NodeUnifiedRDBMapper::getMyFKColumnNameImpl and
 * NodeUnifiedRDBMapper::getObjectDefinitionImpl. These methods merely ask for properties of
 * the domain class. The example shows the mapper for the table @em Article mentioned above:
 * @verbatim
 class ArticleRDBMapper extends NodeUnifiedRDBMapper
 {
   /**
    * @see RDBMapper::getType()
    */
   function getType()
   {
     return 'Article';
   }
   /**
    * @see NodeRDBMapper::createObject()
    */
   function &createObject($oid=null)
   {
     return new Article($oid);
   }
   /**
    * @see NodeUnifiedRDBMapper::getTableName()
    */
   function getTableName()
   {
     return 'Article';
   }
   /**
    * @see PersistenceMapper::getPkNames()
    */
   function getPkNames()
   {
     return array('id' => DATATYPE_IGNORE);
   }
   /**
    * @see NodeUnifiedRDBMapper::getMyFKColumnNameImpl()
    */
   function getMyFKColumnNameImpl($parentType)
   {
     // start from the most specific
     if ($this->getType() == 'Article' && $parentType == 'Author') return 'fk_author_id';
     if ($parentType == 'Author') return 'fk_author_id';
     return '';
   }
   /**
    * @see NodeUnifiedRDBMapper::getOrderBy()
    */
   function getOrderBy()
   {
     return array();
   }
   /**
    * @see NodeUnifiedRDBMapper::getObjectDefinitionImpl()
    */
   function getObjectDefinitionImpl()
   {
     $nodeDef = array();
     $nodeDef['_properties'] = array
     (
       array('name' => 'is_searchable', 'value' => false),
     );
     $nodeDef['_datadef'] = array
     (
      /* 
       * Value description: 
       */
       array('name' => 'id', 'app_data_type' => DATATYPE_IGNORE, 'column_name' => 'id', 
       'db_data_type' => 'INT(11) NOT NULL', 'default' => '', 'restrictions_match' => '', 'restrictions_not_match' => '', 
       'restrictions_description' => '', 'is_editable' => false, 'input_type' => 'text', 'display_type' => 'text'),
      /* 
       * Value description: 
       */
       array('name' => 'fk_author_id', 'app_data_type' => DATATYPE_IGNORE, 'column_name' => 'fk_author_id', 
       'db_data_type' => 'INT(11)', 'default' => '', 'restrictions_match' => '', 'restrictions_not_match' => '', 
       'restrictions_description' => '', 'is_editable' => false, 'input_type' => 'text', 'display_type' => 'text'),
     /* 
      * Value description: 
      */
      array('name' => 'headline', 'app_data_type' => DATATYPE_ATTRIBUTE, 'column_name' => 'headline', 
      'db_data_type' => 'VARCHAR(255)', 'default' => '', 'restrictions_match' => '', 'restrictions_not_match' => '', 
      'restrictions_description' => '', 'is_editable' => false, 'input_type' => 'text', 'display_type' => 'text'),
      
      ...
     );
     $nodeDef['_ref'] = array
     (
      /* 
       * Value description:  
       */
       array('name' => 'author_name', 'ref_type' => 'Author', 'ref_value' => 'name', 'ref_table' => 'Author', 
       'id_column' => 'id', 'fk_columns' => 'fk_article_id', 'ref_column' => 'name')
     );
     $nodeDef['_parents'] = array
     (
       array('type' => 'Author', 'is_navigable' => false, 'table_name' => 'Author', 'pk_columns' => array('id'), 
       'fk_columns' => 'fk_author_id')
     );
     $nodeDef['_children'] = array
     (
       array('type' => 'Image', 'minOccurs' => 0, 'maxOccurs' => 'unbounded', 'aggregation' => false, 'composition' => true,
       'is_navigable' => false, 'table_name' => 'Image', 'pk_columns' => array('id'), 'fk_columns' => 'fk_article_id', 
       'order_by' => array())
     );
     return $nodeDef;
   }
 } @endverbatim
 *
 * The method NodeUnifiedRDBMapper::getObjectDefinitionImpl is the most important method. It supplies an
 * associative array, in which the attributes of the domain class (@em _datadef) the parent and the child
 * domain classes (@em _children) are defined. In addition the Article contains a reference to
 * the name of the Author (@em _ref), which allows to access the Author without loading it.@n
 * Detailed information on the implemetation can be found under NodeUnifiedRDBMapper::getObjectDefinitionImpl.
 *
 * For configuring the domain classes in the configuration file see @ref sectypemapping.
 * 
 * @subsubsection howtodomainclass Creating the domain classes
 *
 * The framework's PersistenceMapper work with the class Node, a subclass of PersistentObject.
 * Different domain classes are created by specifying the type attribute (Node::getType) and
 * a set of attributes (Node::getValueNames).
 * So the class Node is a generic data container, into which data can be put by the method
 * Node::setValue and retrieved by the method Node::getValue. For most applications this will
 * do.
 *
 * If however more specialized domain classes are required for the application, they must
 * be created by the PersistenceMapper. In this case subclasses of NodeRDBMapper must
 * override the method NodeRDBMapper::createObject, which in turn creates instances of the
 * special domain class.
 *
 * @subsection howtonode Working with the class Node
 *
 * @subsubsection howtoload Loading a data structure
 *
 * @code
   $persistenceFacade = &PersistenceFacade::getInstance();
   
   // load model
   $oid = PersistenceFacade::composeOID(array('type' => 'section', 'id' => array('1')));
   $node = &$persistenceFacade->load($oid, BUILDDEPTH_INFINITE);
   if ($node == null)
     Message::error("A Node with object id ".$oid." does not exist.";
   @endcode
 *
 * The example loads the section node with id 1 and all children nodes. If the oid of the
 * requested node is not known either use the appropriate methods of PersistenceFacade 
 * (e.g. PersistenceFacade::getOID) or in more complex cases do an ObjectQuery.
 *
 * @subsubsection howtoiter Traversing a data structure
 *
 * @code
   $iterator = new NodeIterator($node);
   while(!($iterator->isEnd()))
   {
     $currentObject = &$iterator->getCurrentObject();
     Message::trace($currentObject->getOID());
     $iterator->proceed();
   }
   @endcode
 *
 * The example outputs the object ids of all nodes that are descendents of $node.
 *
 * @subsubsection howtooutput Output a data structure into different formats
 *
 * @code
   $iterator = new NodeIterator($node);

   // Output into dot format
   $filename = "graph.dot";
   $dotOS = new DotOutputStrategy($filename);
   $ov = new OutputVisitor($dotOS);
   $ov->startIterator($iterator);

   iterator->reset($node);
   
   // Output into XML format
   $filename = "graph.xml";
   $xmlOS = new XMLOutputStrategy($filename);
   $ov->setOutputStrategy($xmlOS);
   $ov->startIterator($iterator);
   @endcode
 *
 * @subsubsection howtomodify Modifying a data structure
 *
 * @code
   $node->setValue('text', 'hello world!', DATATYPE_ATTRIBUTE);

   // Saving changes
   // If one node has been modified
   $node->save();
   
   // If several connected nodes have been modified
   $iterator = new NodeIterator($node);
   $cv = new CommitVisitor();
   $cv->startIterator($iterator);
   @endcode
 *
 * @subsection howtoviews Programming the views
 *
 * Views are implemented as HTML pages (defined in the view templates), which typically contain a form,
 * which displays the data to be modified. For programming dynamic parts and to access
 * application data the <a href="http://smarty.php.net/" target="_blank">Smarty</a> template
 * language is used.@n
 * By default the views are stored as .tpl files in the directory /application/inlcude/views
 * (see @ref secsmarty). In the directory /wcmf/application/views those views are stored, which
 * the framework uses for its standard application. These are the basis for the programming of
 * custom views.@n
 * 
 * In the view templates all data, which was passed to the view instance is accessible (see
 * @ref howtocontroller). In the simplest case these can be displayed via @em {$variable}. In
 * addition object data can be accessed by using @em {$object->getValue(...)}. By setting
 * @em debugView = 1 (see @ref seccms) in the configuration file Smarty will display the data,
 * which is available in the template, in an external window.@n
 * 
 * The data displayed in the view's form is available to the following controller. Some
 * (hidden) input fields should always exist. They are defined in the file
 * /wcmf/application/views/formheader.tpl, which - to simplify matters - should be reused.@n
 * For handling the form data some JavaScript functions are provided (and documented) in
 * the file /wcmf/blank/script/common.js.
 *
 * In the directory /wcmf/lib/presentation/smarty_plugins the framework defines extensions
 * of the Smarty template language:
 * 
 * - Function @em translate for localization of strings@n
 *   e.g.: {translate text="Logged in as %1% since %2%" r0="$login" r1="$logindate"}
 * - Function @em sessionvalue to get a session variable@n
 *   e.g.: {sessionvalue name="platform"}
 * - Resource @em lib to integrate templates with a relative path to the framework's
 *   root directory (/wcmf)@n
 *   e.g.: {include file="lib:application/views/formheader.tpl"}@n
 *   ...
 *
 * @subsection howtocontroller Programming the controllers
 *
 * Controllers execute the user-defined actions. In order to implement custom controllers
 * a class must be derived from the baseclass Controller, which implements the methods
 * Controller::hasView and Controller::executeKernel.
 * 
 * The Request instance passed to the Controller::initialize method provides all data of the 
 * preceeding view's input fields to the controller. The names of the input fields are the names 
 * of the request values. The controller in turn can pass data to the view by setting them on
 * the Response instance.
 * 
 * The method Controller::hasView returns @em true or @em false, whether a view is displayed
 * or not (the return value can differ depending on the context or action, for an example see LoginController).@n
 * The method Controller::executeKernel executes the actual action. In this method application
 * data is loaded, modified, created, deleted and where required passed to the view for display
 * or to the next controller to proceed.
 * The method either returns @em false, which means, that the ActionMapper should call no further
 * controller or true. In the latter case the ActionMapper determines the next controller
 * from the context and action values of the response (see @ref actionkey).
 * This means if a view should be displayed, the method must return @em false.
 * 
 * While programming custom controllers often the methods Controller::initialize and
 * Controller::validate are overridden in order to carry out initializations or to
 * validate provided data.
 * 
 * The framework's controllers are located in the directory /wcmf/application/controller.
 * 
 * @subsection howtoapplication Programming the application
 *
 * A web application typically consists of several input masks (views), which
 * are used to create, modify and delete data. The application is defined by the actions
 * executable in the individual input masks. Thereby the framework makes no difference
 * between actions used for data handling and those used to navigate or e.g. initiate the
 * export of data.
 * 
 * The definition of an action requires the following steps:
 * 
 * -# @ref howtoapplication1
 * -# @ref howtoapplication2
 * -# @ref howtoapplication3
 * -# @ref howtoapplication4
 * -# @ref howtoapplication5
 * 
 * As an example we use the action for displaying an @em article node in order to
 * edit it. Let's look at the individual steps:
 * 
 * @subsubsection howtoapplication1 Definition of the action name
 * We name the action @em editArticle. This name need not to be unique in the whole
 * application. The ActionMapper only requires the name (and the @ref actionkey defined
 * by the action) to find the next appropriate controller.
 * 
 * @subsubsection howtoapplication2 Creating the button to trigger the action
 * In order to display the data the application must know which article is selected.
 * This is exactly defined by it's @ref oid. The data transfer between the input
 * masks is achieved by the HTTP POST mechanism, i.e. a (hidden) input field must exist,
 * which contains the oid of the article to be displayed. Since for most applications it's often
 * necessary to transfer an oid, the framework defines a standard field @em oid in each
 * view (see file /wcmf/application/views/formheader.tpl), which can easily be set
 * by the JavaScript function @em doDisplay (/wcmf/blank/script/common.js).
 * 
 * The action is triggered upon submission of the input form. Another JavaScript function
 * (@em submitAction) simplifies the execution. The form data is passed to the main.php
 * script, which delegates the further execution to the ActionMapper. The link to execute
 * the action could look like this:
 * @verbatim <a href="javascript:setContext('article'); doDisplay('{$article->getOID()}'); 
                 submitAction('editArticle');">{translate text="edit"}</a> @endverbatim
 * For details on programming the views see @ref howtoviews.
 * 
 * @subsubsection howtoapplication3 Customizing the configuration file
 * To determine the controller, which carries out the action, the ActionMapper requires
 * an appropriate entry in the configuration file (see @ref secactionmapping). If
 * the controllers name is @em ArticleController, the entry could look like this:
 * @verbatim 
 [actionmapping]
 ??editArticle = ArticleController @endverbatim
 * Don't forget to introduce the ArticleController in the configuration section @ref secclassmapping.
 *
 * Additionally the ArticleController should display a view for editing the article. If we
 * name this view @em article.tpl, the configuration entry would look like the following (see
 * @ref secviews):
 * @verbatim 
 [views]
  ArticleController?? = article.tpl @endverbatim

 * @subsubsection howtoapplication4 Implementing the action as a controller
 * The action is executed in the controller - in this example in the @em ArticleController class.
 * Since the controller should display a view with the article's data, we first must specify that
 * the controller has a view and second the data of the article must be passed to the view.@n
 * At first however it must be assured, that the controller receives an oid. This happens in
 * the method Controller::validate, which searches for the entry in the passed data:
 * @verbatim
 function validate()
 {
   if ($this->_request->getValue('oid') == '')
   {
     $this->setErrorMsg("No 'oid' given in data.");
     return false;
   }
   return true;
 } @endverbatim
 * 
 * We declare the existence of a view in the method Controller::hasView:
 * @verbatim
 function hasView()
 {
   return true;
 } @endverbatim
 * 
 * Finally the action is executed in the method @em Controller::executeKernel. Here the
 * controller loads the data and provides it to the view for display by setting it on the
 * response instance:
 * @verbatim
 function executeKernel()
 {
   $persistenceFacade = &PersistenceFacade::getInstance();
   
   // load model
   $article = &$persistenceFacade->load($this->_request->getValue('oid'), BUILDDEPTH_INFINITE);
 
   // assign model to view
   $this->_response->setValue('article', $article);
 
   // stop processing chain
   return false;
 } @endverbatim
 *
 * It's important that the method returns false, since this causes the ActionMapper
 * to end the execution and wait for user input. The display of the view is done by
 * the framework.
 *
 * @subsubsection howtoapplication5 Displaying data in the view
 * After the controller has provided the view with the data, the view can display the data.
 * In our case after the ArticleController has been executed a variable @em article is
 * known to the view, which matches the article node.@n
 * The programming of the views is done in HTML together with the Smarty template language.
 * The file @em article.tpl could contain the following line:
 * @verbatim article name: {$nodeUtil->getInputControl($article, "name")} @endverbatim
 * 
 * In the curly brackets you can find Smarty code, which calls the method NodeUtil::getInputControl.
 * This method displays the input control (in our case a textfield), which corresponds to the
 * article's @em name attribute, in the HTML page. In the same manner the other attributes can be handled.
 *
 * @subsection howtorights Rights management
 *
 * Rights can be assigned to the execution of actions in the user interface or to the editing
 * of domain classes and individual objects (instances of domain classes). For editing content the framework
 * defines the rights @em read, @em modify, @em delete and @em create.@n
 * The authorization for actions in the user interface is handled by the ActionMapper, for actions
 * concerning the data the PersistenceMapper checks the permissions (and sets objects, for which
 * the right @em modify is not set, to non-editable (@em is_editable = false) ).
 * Both classes use the method RightsManager::authorize and generate a fatal error message,
 * if authorization fails (see @ref howtoerror).
 * To prevent this the rights can be retrieved directly in order to take appropriate messures:
 * @verbatim
 $rightsManager = &RightsManager::getInstance();
 if ($rightsManager->authorize($this->_request->getValue('oid'), '', ACTION_READ))
 {
   $object = &$persistenceFacade->load($this->_request->getValue('oid'), BUILDDEPTH_INFINITE);
 }
 else
 {
   // do something else if the user cannot read the object
 } @endverbatim
 *
 * In the example the object is only loaded, if it's permitted. For the definition of rights
 * see @ref secauthorization.
 * @note If @em anonymous is set to one in the configuration file, the rights management
 * is disabled (see @ref seccms).
 *
 * @subsection howtoconcurrency Concurrency
 *
 * If more than one user works with the application at the same time, conflicts can occur, if two
 * users want to edit the same object concurrently. In this case the first user can request
 * a lock on that object, which only allows reading access to succeeding users. This lock will 
 * be transfered to all instances loaded in the future as long until the user unlocks the object, 
 * which happens automatically upon execution of an action (call to main.php).
 * In the sourcecode this looks as follows:
 * @verbatim
 $lockManager = &LockManager::getInstance();
 $object = &$persistenceFacade->load($this->_request->getValue('oid'), BUILDDEPTH_INFINITE);
 
 // if the object is locked by another user we retrieve the lock to show a message
 $lock = $object->getLock();
 if ($lock != null)
 {
   $lockMsg .= $lockManager->getLockMessage($lock, $recipe->getName());
 }
 else
 {
   // try to lock object
   $lockManager->aquireLock($this->_request->getValue('oid'));
 } @endverbatim
 * 
 * The functionality described above is imlemented in the method LockManager::handleLocking,
 * with the only difference that this method only acquires a lock in cases in which the
 * user is allowed to modify the object.@n
 * An object, which is loaded by another user is set to non-editable (@em is_editable = false)
 * automatically upon loading.
 *
 * @subsection howtoi18n Multilanguage Support
 *
 * For localization of the application the method Message::get is provided. For a given (english)
 * string this method searches for the required language's version. The language version can
 * either be passed directly with the method call or can be set application wide (see documentation
 * of Message::get).@n
 * How the translation is retrieved depends on the parameter @em usegettext (see @ref seccms).
 * If it is set to 1, the method uses the PHP function @em gettext. This in turn makes use of
 * *.mo files in the directory /localeDir/language/LC_MESSAGES - e.g. /locale/de_DE/LC_MESSAGES/main.mo
 * (see documentation of gettext).@n
 * If gettext doesn't exist, the language version can also be taken from an associative array named
 * messages_language (e.g. messages_de_DE).
 * This must be defined in a file /localeDir/language/LC_MESSAGES/messages_language.php (e.g.
 * /locale/de_DE/LC_MESSAGES/messages_de_DE.php). The keys of the array are the strings, which are
 * passed to the method Message::get, the values are the corresponding translations.@n
 * @note If a translation for a text doesn't exist, the string, which was passed to the method
 * Message::get, will be used.
 *
 * For making the localization more comfortable some tools are provided in the directory /wcmf/tools/i18n:
 * - @em locale.php extracts all strings to be localized (where the method Message::get is used) from the
 *   application (views, controllers) and creates a *.po file for use with gettext.
 * - @em po2array.php generates the array definition described above from a *.po file.
 *
 * For localizing the view templates a Smarty plugin is provided, which is to be used as follows:
 * @verbatim {translate text="Logged in as %1%" r0=$authUser->getLogin()} @endverbatim 
 *
 * The @em parameters of the method Message::get are defined by the values of @em r0, @em r1, ...
 *
 * @subsection howtologdebug Debugging/Logging
 *
 * For debugging und logging output the <a href="http://logging.apache.org/log4php/" target="_blank">log4php</a>
 * framework is used. For convenient usage wCMF defines a thin wrapper class called Log. To log a debug message 
 * in the category of the current class, just call:
 *
 * @verbatim Log::debug($message, __CLASS__); @endverbatim 
 *
 * @subsection howtoerror Error handling
 *
 * In the application two types of errors are distinguished:
 * - @em Fatal: Errors, which are so critical, that it's not possible to proceed with the current action
 *   (e.g. the missing of a controller).
 * - @em Non-fatal: Errors, which merely demand a notification to the user (e.g. invalid input)
 *
 * These errors can be produced in the following ways:
 *
 * - @em Fatal: The use of WCMFException::throwEx calls a global error handling routine:
 *   @code onError($message, $file='', $line='') @endcode
 * - @em Non-fatal: adding a message by calling Controller::appendErrorMsg makes this message - together with
 *   all accumulated messages before and those to follow - available in the next view's @em $errorMsg variable.@n
 *   In order to delete old messages the method Controller::setErrorMsg class must be called with an empty string
 *   parameter.
 * 
 *  Many classes define a method @em getErrorMsg, which provides more detailed information on the cause of an error.
 *
 * Back to the @ref intro | Previous section @ref dbschema | Next section @ref howtostart
 *
 */