1: <?php
  2: 
  3: /**
  4:  *
  5:  * @package Plugin
  6:  * @subpackage FormAssistant
  7:  * @version SVN Revision $Rev:$
  8:  * @author marcus.gnass
  9:  * @copyright four for business AG
 10:  * @link http://www.4fb.de
 11:  */
 12: 
 13: // assert CONTENIDO framework
 14: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
 15: 
 16: /**
 17:  * This form post helper should simplify the implementation of typical form
 18:  * processing.
 19:  * Its main method process() wraps the steps read data from request,
 20:  * validate data and persist data in database. In order to make this approach
 21:  * more customizable three protected "event handler" were defined that can be
 22:  * implemented by a concrete implementation of this class. These allow to
 23:  * preprocess the data read from the request before it's going to be validated
 24:  * and to be postprocessed after it's been persisted into the database.
 25:  *
 26:  * @author marcus.gnass
 27:  */
 28: abstract class PifaAbstractFormProcessor {
 29: 
 30:     /**
 31:      *
 32:      * @var PifaAbstractFormModule
 33:      */
 34:     private $_module = NULL;
 35: 
 36:     /**
 37:      *
 38:      * @todo should be private as it can be accessed via getForm()
 39:      * @var PifaForm
 40:      */
 41:     protected $_form = NULL;
 42: 
 43:     /**
 44:      * Instantiates the processor.
 45:      * The processor aggregates the form module and the form.
 46:      * The idform is read from the given modules settings.
 47:      *
 48:      * In former implementations of the processor the modules had no settings
 49:      * and thus no idform. Thats why optionally the idfrm gan be given
 50:      * explicitly. This shoud be removed when all processors are refactored.
 51:      *
 52:      * @param int $idform
 53:      * @throws ModuleException
 54:      */
 55:     public function __construct(PifaAbstractFormModule $module = NULL, $idform = NULL) {
 56:         $this->_module = $module;
 57: 
 58:         // for backward compatibility
 59:         if (NULL !== $this->_module) {
 60:             $idform = $this->_module->getSetting('pifaform_idform');
 61:         }
 62: 
 63:         // assure $idform to be an integer
 64:         $idform = cSecurity::toInteger($idform);
 65:         if (0 === $idform) {
 66:             $msg = Pifa::i18n('MISSING_IDFORM');
 67:             throw new PifaException($msg);
 68:         }
 69: 
 70:         // load form
 71:         $this->_form = new PifaForm($idform);
 72:         if (false === $this->_form->isLoaded()) {
 73:             $msg = Pifa::i18n('FORM_LOAD_ERROR');
 74:             throw new PifaException($msg);
 75:         }
 76:     }
 77: 
 78:     /**
 79:      *
 80:      * @return PifaAbstractFormModule
 81:      */
 82:     public function getModule() {
 83:         return $this->_module;
 84:     }
 85: 
 86:     /**
 87:      *
 88:      * @param PifaAbstractFormModule $_module
 89:      */
 90:     public function setModule($_module) {
 91:         $this->_module = $_module;
 92:     }
 93: 
 94:     /**
 95:      *
 96:      * @return PifaForm
 97:      */
 98:     public function getForm() {
 99:         return $this->_form;
100:     }
101: 
102:     /**
103:      *
104:      * @param PifaForm $_form
105:      */
106:     public function setForm($_form) {
107:         $this->_form = $_form;
108:     }
109: 
110:     /**
111:      * Template method to postprocess data that has just been read from request.
112:      * This can be usefull e.g. to remove default values for certain form
113:      * fields.
114:      */
115:     abstract protected function _processReadData();
116: 
117:     /**
118:      * Template method to postprocess data that has just been validated.
119:      * I cannot yet imagine a situatio where this could be useful but added
120:      * this method for completeness' sake.
121:      */
122:     abstract protected function _processValidatedData();
123: 
124:     /**
125:      * Template method to postprocess data that has just been stored to
126:      * database.
127:      * This can be usefull e.g. to send form values via email or process them
128:      * in another way.
129:      */
130:     abstract protected function _processStoredData();
131: 
132:     /**
133:      * Processes a form.
134:      * Therefor the forms values are read from the appropriate request,
135:      * validated and written to database.
136:      * After each step a method is called that allows to postprocess the forms
137:      * data or even the form itself. This postprocessing is optional and can be
138:      * implemented in concrete implementations of this abstratc class
139:      *
140:      * @throws ModuleException if there is no form to process
141:      * @throws PifaValidationException if data is invalid
142:      * @throws PifaDatabaseException if data could not be stored
143:      */
144:     public function process() {
145: 
146:         // assert there is a form to process
147:         if (NULL === $this->_form) {
148:             $msg = Pifa::i18n('MISSING_IDFORM');
149:             throw new PifaException($msg);
150:         }
151: 
152:         // perform steps as described in documentation
153: 
154:         $this->_form->fromForm();
155:         $this->_processReadData();
156: 
157:         $this->_form->validate();
158:         $this->_processValidatedData();
159: 
160:         $this->_form->storeData();
161:         $this->_processStoredData();
162:     }
163: }
164: