[Sommaire] [Imprimer]

   1  <?php
   2  
   3  
   4      /**
   5       * \defgroup Action
   6       *
   7       * Action in pLog are the classes that implement the application logic. Action classes are always
   8       * instantiated and executed by the Controller after a parameter in an incoming request
   9       * matched an action class as specified in the action class map.
  10       *
  11       * The most basic action class is Action, though API users will generally not need to create objects
  12       * of that class directly. Users wishing to extend the features of pLog via plugins will likely
  13       * use BlogAction for actions in the public interface, and AdminAction, SiteAdminAction or
  14       * BlogOwnerAdminAction depending on which user privileges are required to use the given action.      
  15       *
  16       * @see Action
  17       * @see Controller
  18       * @see ActionInfo
  19       * @see BlogAction
  20       * @see SiteAdminAction
  21       * @see BlogOwnerAdminAction
  22       */
  23  
  24      
  25  
  26      /**
  27       * \ingroup Action
  28       *
  29       * The base most basic action class is Action, which provides some common code and the Action::perform()
  30       * method which should be implemented by child classes wishing to provide some business logic. At the end
  31       * of the method, an Action class is expected to generate a valid View object (or a child class of View)
  32       * that will be used by the Controller to render some contents to be sent to the client.
  33       *
  34       * Action classes are expected to at least provide their own logic in the Action::perform() method. In previous
  35       * versions of pLog it was also necessary to provide data validation logic in the Action::validate()
  36       * method, but that is not necessary anymore (albeit possible if needed) since the introduction of the
  37       * new data validation framework (See the FormValidator class and the Validator and Validator_Rules modules)
  38       * The Action::validate() method now provides some code of its own that triggers the data validation process
  39       * if there is any data to be validated.
  40       *
  41       * There is a lot more information about the data validation framework here: http://wiki.plogworld.net/index.php/PLog_1.0/Forms_and_data_validation 
  42       *
  43       * The View object that Action classes must create can be set via the private attribute
  44       * Action::_view or te method Action::setView(), though the first one is the most widely used
  45       * throughout the core code.
  46       *
  47       * Please keep in mind that it is advisable to call the Action::setCommonData() method at the very end
  48       * of the Action::perform() method in our custom classes because it needs to perform some extra
  49       * operations right before the view is sent back to the controller.
  50       */
  51      class Action 
  52      {
  53  
  54          // this is the pointer to the view associated with this action
  55          var $_view;
  56          var $_request;
  57          var $_actionInfo;
  58          var $_fieldValidators;
  59          var $_validationErrorView;
  60          var $_previousAction;
  61          var $_isSuccess;
  62  
  63          /**
  64           * Constructor.
  65           *
  66           * @param actionInfo An ActionInfo object contaning information about the action
  67           * @param httpRequest the HTTP request.
  68           */
  69      	function Action( $actionInfo, $httpRequest )
  70          {
  71              lt_include( PLOG_CLASS_PATH."class/net/request.class.php" );
  72              lt_include( PLOG_CLASS_PATH."class/data/forms/formvalidator.class.php" );            
  73  
  74              $this->_request = new Request( $httpRequest );
  75  
  76              $this->_actionInfo = $actionInfo;
  77              
  78              $this->_fieldValidators = Array();
  79              
  80              // initialize the views to empty values
  81              $this->_view = null;
  82              $this->_validationErrorView = null;
  83              
  84              // form object, used for data validation
  85              $this->_form = new FormValidator();
  86              
  87              // no previous action
  88              $this->_previousAction = null;
  89              
  90              // by default, the action is successful
  91              $this->_isSuccess = true;
  92          }
  93          
  94          /**
  95           * @private
  96           *
  97           * @param previousAction a valid Action object
  98           * @return Always true
  99           */
 100  		function setPreviousAction( $previousAction )
 101          {
 102              $this->_previousAction = $previousAction;
 103          }
 104          
 105          /** 
 106           * returns the reference to the previous action in the process flow
 107           *
 108           * @return A valid Action object, or null if there is no previous action
 109           * @private
 110           */
 111  		function getPreviousAction()
 112          {
 113              return $this->_previousAction;
 114          }
 115          
 116          /**
 117           * Receives the HTTP request from the client as parameter, so that we can
 118           * extract the parameters and perform our business logic.
 119           *
 120           * The result of this will be a view, which will normally be the output of the
 121           * processing we just did or for example an error view showing an error message.
 122           * Once we have completed processing, the controller will call the getView() method
 123           * to get the resulting view and send it back to the customer.
 124           *
 125           * @return Returns nothing
 126           */
 127          function perform()
 128          {    
 129              // to be implemented by child classes...
 130          }
 131          
 132          /**
 133           * This method can be used for data validation and is <b>always</b> executed
 134           * before perform(). If it returns 'true', execution will continue as normal. If it 
 135           * returns 'false', the process will be stopped and the current contents of the
 136           * view will be returned. If the view is empty, an exception will be thrown.
 137           *
 138           * As of pLog 1.0, it is not necessary to implement data validation code here and it is recommended
 139           * to use the data validation framework (see methods Action::registerFieldValidator() and related) There is
 140           * more information about the data validation framework in the wiki: http://wiki.plogworld.net/index.php/PLog_1.0/Forms_and_data_validation.
 141           *
 142           * With the default code provided in the Action::validate() method, the callback method Action::validationErrorProcessing()
 143           * will be called and after that, the view set via the Action::setValidationErrorView() will be used to
 144           * generate the contents of the error message.
 145           *
 146           * @return Returns true if data is correct or false otherwise. See above for more details.
 147           */
 148          function validate()
 149          {
 150              // use the FormValidator object to validate the data
 151              $validationOk =  $this->_form->validate( $this->_request );
 152              
 153              // if something went wrong... let's do somethinga about it :)
 154              if( !$validationOk ) {
 155                  $this->validationErrorProcessing();
 156              }
 157              
 158              return $validationOk;
 159          }
 160          
 161          /**
 162           * This method will be called when a validation error happens. Child classes are
 163           * free to extend or reimplement this one and can be used as some sort of a trigger
 164           * in order to do some cleanup if needed.
 165           *
 166           *Ê@return nothing
 167           */
 168  		function validationErrorProcessing()
 169          {
 170              // if there was a validaton error, then inform the view
 171              $this->_view = $this->_validationErrorView;
 172              $this->_view->setError( true );
 173                  
 174              // and  export all the data to the view so that it can be reused in the error view
 175              $fieldValues = $this->_form->getFieldValues();
 176              foreach( $fieldValues as $fieldName => $fieldValue ) {
 177                  $this->_view->setValue( "$fieldName", $fieldValue );
 178              }
 179                  
 180              $this->_form->setFormIsValid( false );
 181              $this->setCommonData();
 182      
 183              return true;
 184          }
 185          
 186          /**
 187           * sets the view that will be shown in case there is an error during
 188           * the validation process... It makes things a bit easier for us when 
 189           * it comes to validate data. This view will only be used if validate() generates a validation
 190           * error or if we force the action to generate an error via Action::setSuccess()
 191           *
 192           * @param view A valid View object
 193           * @return Always true
 194           * @see View
 195           */
 196  		function setValidationErrorView( $view )
 197          {
 198              $this->_validationErrorView = $view;
 199              
 200              return true;
 201          }
 202          
 203          /**
 204           * registers a new validator, for validating data coming from fields
 205           * 
 206           * @param fieldName The name of the field from the form that we're going to validate
 207           * @param validator A valid class inheriting from the Validator base class and that implements
 208           * the validate() method, that will be used for validating fields.
 209           * @param onlyIfAvailable validate this field only if its value is not emtpy         
 210           * @return Always true
 211           * @see FormValidator
 212           * @see Validator
 213           */
 214  		function registerFieldValidator( $fieldName, $validator, $onlyIfAvailable = false )
 215          {
 216              $this->_form->registerFieldValidator( $fieldName, $validator, $onlyIfAvailable );
 217              
 218              return true;
 219          }
 220          
 221          /**
 222           * registers a new field whose value should be available to the view/template in case
 223           * it needs to be reshown.Those fields that haven't been registered, will *not* be shown
 224           * when rerunning the view.
 225           * 
 226           * @param fieldName The name of the field from the form that we're going to register
 227           * @see FormValidator
 228           */
 229  		function registerField( $fieldName )
 230          {
 231              $this->_form->registerField( $fieldName );
 232              
 233              return true;
 234          }
 235          
 236  
 237          /**
 238           * This function does not need to be reimplemented by the childs of this class.
 239           * It just returns the resulting view of the operation.
 240           *
 241           * @return A valid View object
 242           */
 243          function getView()
 244          {
 245              return $this->_view;
 246          }
 247          
 248          /**
 249           * we can do things here that are common to all the views. This method must be called just before
 250           * the Action::perform() method has finished its processing since most of the child Action
 251           * classes use it to do some kind of post-processing.
 252           *
 253           * @param copyFormValues Whether the values from fields that were registered via
 254           * Action::registerFieldValidator() and Action::registerField() should be passed back to the view
 255           * as variables or not. It defaults to 'false' but this parameter is useful in those cases
 256           * when we would like to force an error to happen (not a validation error) and still keep the
 257           * form values.
 258           * @return Always true
 259           */
 260  		function setCommonData( $copyFormValues = false )
 261          {
 262              $this->_view->setValue( "form", $this->_form );
 263              
 264              if( $copyFormValues ) {
 265                  // in case we'd like to copy the values from the form
 266                  $fieldValues = $this->_form->getFieldValues();
 267                  foreach( $fieldValues as $fieldName => $fieldValue ) {
 268                      $this->_view->setValue( "$fieldName", $fieldValue );
 269                  }
 270              }
 271              
 272              return true;
 273          }
 274          
 275           /**
 276            * This method can be used to trigger validation errors even if they did not really happen, or
 277            * to disable errors if they happened.
 278            *
 279            * @param success Whether to force or unforce an error
 280            */
 281  		 function setSuccess( $success )
 282           {
 283               $this->_isSuccess = $success;
 284               $this->_form->setFormIsValid( $success );
 285           }
 286          
 287           /**
 288            * This method will be executed to check whether this action can be executed or not. This means
 289            * that this method will be executed before the perform() method. If this method returns 'false',
 290            * the controller will then load the action defined via the Controller::setCannotPerformAction()
 291            *
 292            * @return True if the controller is allowed to call the Action::perform() action or not.
 293            * @see Controller
 294            */
 295  		function canPerform()
 296          {
 297              return( true );
 298          }            
 299      }
 300  ?>