File Source for Item.php

<?php
/**
* Formagic
*
* LICENCE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at
* http://formagic.weasle.de/licence.txt
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to licence@weasle.de so we can send you a copy immediately.
*
* @category Formagic
* @package Item
* @author Florian Sonnenburg
* @copyright Copyright (c) 2007 Florian Sonnenburg
* @license http://formagic.weasle.de/licence.txt New BSD License
* @revision $Revision: 14 $
*/
/**
* Abstract superclass for Formagic items
*
* @category Formagic
* @package Item
* @author Florian Sonnenburg
* @copyright Copyright (c) 2007 Florian Sonnenburg
* @version $Id: Item.php 14 2007-08-13 20:33:26Z meweasle $
***/
abstract class Formagic_Item
{
/**
* Type of form item
* @var string
*/
public $type;
/**
* Form item name
* @var string
*/
public $name;
/**
* Form item ID
* @var string
*/
public $id;
/**
* Form item label
* @var boolean
*/
protected $_label = 'undefined';
/**
* Additional attributes for item
* @var array
*/
public $attributes = array();
/**
* Formagic object that called and contains item
* @var object
*/
protected $_caller = null;
/**
* Array of rule object that are applied for this item
* @var object
*/
protected $_rules = array();
/**
* Flag that defines if item content can be edited.
* @var boolean
*/
protected $_isBlocked = false;
/**
* Flag that defines if item will be displayed
* @var boolean
*/
protected $_isHidden = false;
/**
* Flag that defines if item is removed from Formagic
* @var boolean
*/
protected $_isDisabled = false;
/**
* Flag that defines if item content will be posted on submit
* @var boolean
*/
public $isPostItem = true;
/**
* Pointer to submitted value for this item, stored in calling Formagic object
* @see Formagic_Item::setCaller()
* @var string
*/
protected $submittedValue = null;
/**
* Values that are not changed by submitted values
* @var array
***/
protected $_constantValue = null;
/**
* Pointer to default value for this item, stored in calling Formagic object
* @see FormagicItem::setCaller()
* @var string
*/
protected $defaultValue = null;
/**
* Pointer to mulitpage value for this item, stored in calling Formagic object
* @var string
*/
protected $savedValue = null;
/**
* Flag that tells if this Formagic item has been submitted
* @var boolean
*/
public $isSubmitted = false;
/**
* Error message string
* @var string
*/
private $_errorMessage = null;
/**
* Defines if template takes full width
* @var boolean
*/
public $isWide = false;
/**
* Constructor
*
* @param string $type Type of item
* @param string $name Name of item
* @param array $args Additional attributes
* @param object $caller containing Formagic object
* @throws Formagic_Exception
* @return void
***/
public function __construct($type, $name, &$args=null, &$caller=null)
{
$this->type = $type;
$this->name = $name;
$this->id = str_replace(array('[',']'), array('_',''), $this->name);
$this->setCaller($caller);
if (is_array($args)) {
foreach($args as $key => $arg) {
switch($key) {
case 'label':
$this->_label = $arg;
break;
case 'constant':
if (!$this->_caller) {
throw new Formagic_Exception("Can't set constant value: " .
"Calling Formagic object not found");
}
$this->_constantValue = $arg;
break;
case 'default':
if (!$this->_caller) {
throw new Formagic_Exception("Can't set default value: " .
"Calling Formagic object not found");
}
$this->defaultValue = $arg;
break;
case 'mulitpage':
if (!$this->_caller) {
throw new Formagic_Exception("Can't add to multipage items: " .
"Calling Formagic object not found");
}
$this->_caller->addMultipageItem($this->name);
break;
case 'attributes':
$this->setAttributes($arg);
break;
case 'hidden':
$this->setHidden($arg);
break;
case 'blocked':
$this->block();
break;
case 'rule':
$arg = (array)$arg;
foreach($arg as $rule) {
$this->addRule($rule);
}
break;
default:
// Argument handler for unknown arguments. Defined in
// item classes
$this->_handleArg($key, $arg);
} // switch
}
}
}
/**
* Handler for additional item arguments
*
* @param string $key Argument name
* @param mixed $arg Argument value
* @return boolean
*/
protected function _handleArg($key, $arg)
{
return true;
}
/**
* Can be called to set caller object if not passed to constructor
*
* @param object $caller
* @return boolean
***/
public function setCaller(&$caller)
{
if (!$caller) {
return false;
}
$this->_caller =& $caller;
if (isset($this->_caller->submitValues[$this->name])) {
$this->isSubmitted = true;
$this->submittedValue =& $this->_caller->submitValues[$this->name];
}
$this->_constantValue =& $this->_caller->constantValues[$this->name];
$this->defaultValue =& $this->_caller->defaultValues[$this->name];
$this->savedValue =& $this->_caller->savedValues[$this->name];
return true;
}
/**
* Returns parent Formagic object
*
* @return Formagic
*/
public function getCaller()
{
return $this->_caller;
}
/**
* Returns string representation of formItem object
*
* @return string
***/
public function __toString()
{
$callerPresent = isset($this->_caller);
$str = "FormagicItem [type: {$this->type}][name: {$this->name}]" .
"[submitted value: '{$this->submittedValue}']" .
"[default value: '{$this->defaultValue}']" .
"[saved value: '{$this->savedValue}']" .
"[flags: hidden '{$this->_isHidden}', blocked '{$this->_isBlocked}', disabled '{$this->_isDisabled}']" .
"<br />";
return $str;
}
/**
* Returns current value for this item
*
* Calls Formagic::getValue() as all value storages are held there.
*
* @return mixed
*/
public function &getValue()
{
$value = &$this->_caller->getValue($this->name);
return $value;
}
/**
* Returns label for this item.
*
* @return string
*/
public function getLabel()
{
return $this->_label;
}
/**
* HTML template for renderers that use HTML-Code
*
* @return string
**/
public function getHtml()
{
return "";
}
/**
* Sets additional attributes for this item
*
* Mainly used for additional HTML attributes other than "name", "id" or
* "value", such as "style", "class", javascript-handlers etc. Attributes
* are added corresponding to key->value-pairs in $attArray.
*
* @param array $attArray
* @return array
*/
public function setAttributes($attArray)
{
return $this->attributes = $attArray;
}
/**
* Returns attribute string for HTML tag
*
* @return string
*/
protected function _getAttributeStr()
{
if (!count($this->attributes)) {
return "";
}
$res = "";
foreach($this->attributes as $key => $att) {
$res .= " $key=\"$att\"";
}
return $res;
}
/**
* Adds rule object to Formagic item
*
* Formagic items can have multiple rules, which are saved in
* FormagicItem::rules.
* First parameter $rule can either be a string or a FormagicRule object.
* String value is assumed to be the type of rule to be added.
*
* This method throws an exception if no valid role object can be identified.
*
* @param mixed $rule Rule type or FormagicRule object.
* @param string $errorMessage Message returned if rule is violated
* @param array $args Optional.
* @throws Formagic_Exception
* @return integer
**/
public function addRule($rule, $errorMessage=null, $args=null)
{
// argument is assumed rule type if string.
if (is_string($rule)) {
$class = 'Formagic_Rule_' . ucFirst($rule);
$this->_caller->loadClass($class);
$this->_rules[$rule] = new $class($rule,$errorMessage,$args);
} elseif($rule instanceof Formagic_Rule) {
$type = $rule->getType();
$this->_rules[$type] = $rule;
} else {
throw new Formagic_Exception('Invalid rule type or rule object');
}
return true;
}
/**
* Tells if rule exists for this item
*
* @param string $rule
* @return boolean
*/
public function hasRule($rule)
{
return isset($this->_rules[$rule]);
}
/**
* Performs rule checks
*
* Iterates through all defined rules of Formagic item. Returns true if all
* rules apply or violated Formagic_Rule object
*
* @throws Formagic_Rule_Exception
* @return mixed Rule object or boolean
*/
public function validate()
{
if (!$this->_onPreValidate()) {
return false;
}
foreach($this->_rules as $ruleObj) {
if (!$ruleObj->check($this)) {
$this->_errorMessage = $ruleObj->getMessage();
return $ruleObj;
}
}
if (!$this->_onPostValidate()) {
return false;
}
return true;
}
/**
* Returns item error message
*
* Returns error message if item check failed or empty string if not
*
* @return string
*/
public function getErrorMessage()
{
return $this->_errorMessage;
}
/**
* Sets blocked flag
*
* @return boolean
*/
public function block()
{
return $this->_isBlocked = true;
}
/**
* Sets hidden flag for item
*
* @return boolean
*/
public function setHidden($flag)
{
return $this->_isHidden = $flag;
}
/**
* Returns hidden status of item
*
* @return boolean
*/
public function isHidden()
{
return $this->_isHidden;
}
/**
* Sets disabled flag for item and thus removes it from form
*
* @return boolean
*/
public function disable()
{
return $this->_isDisabled = true;
}
/**
* Returns disabled status of item
*
* @return boolean
*/
public function isDisabled()
{
return $this->_isDisabled;
}
/**
* Event dispatcher
*
* @param string $event
* @throws Formagic_Exception
* @return boolean
**/
public function _execEvent($event)
{
switch($event) {
case 'onCreate':
return $this->_onCreate();
case 'onFetch':
$this->_onFetch();
break;
default:
throw new Formagic_Exception('Event "' . $event . '" not supported');
} // switch
return true;
}
/**
* Executed before item validation
*
* Can be overwritten. Must return true if successful. If not,
* can either return false or throw exception
*
* @return boolean
*/
protected function _onPreValidate()
{
return true;
}
/**
* Executed after item validation is done
*
* @return boolean
*/
protected function _onPostValidate()
{
return true;
}
/**
* Executed when object is created
*
* @return boolean
*/
protected function _onCreate()
{
return true;
}
/**
* Executed when Formagic::fetch() is called
*
* @return void
*/
protected function _onFetch()
{
}

Source for file Item.php