<?PHP

  /**
   * tiggerXMPP
   * ----------
   * An XMPP-Implementation in PHP 5
   * 
   * This work is distributed within the terms of
   * creative commons attribution-share alike 3.0 germany
   * 
   * See http://creativecommons.org/licenses/by-sa/3.0/ for more information
   * 
   * @author Bernd Holzmueller <bernd@tiggerswelt.net>
   * @revision 01
   * @license http://creativecommons.org/licenses/by-sa/3.0/de/ Creative Commons Attribution-Share Alike 3.0 Germany
   * @homepage http://oss.tiggerswelt.net/xmpp
   * @copyright Copyright &copy; 2010 tiggersWelt.net 
   **/
  
  require_once ('tiggerXMPP/xml/tag.php');
  
  /**
   * Abstract class to handle XEP-0004 Fields
   * 
   * @package tiggerXMPP
   * @class tiggerXMPP_XEP_0004_Form
   **/
  class tiggerXMPP_XEP_0004_Field extends tiggerXMPP_XML_Tag {
    // General informations about this tag
    const TAG_NAME = 'field';
    const TAG_NAMESPACE = 'jabber:x:data';
    
    // Field-Types as of XEP-0004
    const TYPE_BOOLEAN = 'boolean';
    const TYPE_FIXED = 'fixed';
    const TYPE_HIDDEN = 'hidden';
    const TYPE_JID_MULTI = 'jid-multi';
    const TYPE_JID_SINGLE = 'jid-single';
    const TYPE_LIST_MULTI = 'list-multi';
    const TYPE_LIST_SINGLE = 'list-single';
    const TYPE_TEXT_MULTI = 'text-multi';
    const TYPE_TEXT_SINGLE = 'text-single';
    const TYPE_TEXT_PRIVATE = 'text-private';
    
    // Our attributes
    private $Label = null;
    private $Variable = null;
    private $Type = tiggerXMPP_XEP_0004_Field::TYPE_TEXT_SINGLE;
    
    // {{{ __construct
    /**
     * Create a new XML-Tag
     * 
     * @param string $Name (optional)
     * @param object $Parent (optional)
     * @param string $Value (optional)
     * @param enum $Type (optional)
     * @param string $Var (optional)
     * @param string $Label (optional)
     * 
     * @access friendly
     * @return void
     **/
    function __construct ($Name = '', $Parent = null, $Value = null, $Type = null, $Var = null, $Label = null) {
      $this->setName (self::TAG_NAME);
      $this->setParent ($Parent);
      
      if ($Value !== null)
        $this->setValue ($Value);
      
      if ($Type !== null)
        $this->setType ($Type);
      
      if ($Var !== null)
        $this->setVariable ($Var);
      
      if ($Label !== null)
        $this->setLabel ($Label);
    }
    // }}}
    
    // {{{ getAttributes
    /**
     * Retrive a list of attributes for this tag
     * 
     * @access protected
     * @return array
     **/
    protected function getAttributes () {
      $Attribs = array ();
      
      if ($this->Type !== self::TYPE_TEXT_SINGLE)
        $Attribs ['type'] = $this->Type;
      
      if (($this->Label !== null) && (strlen ($this->Label) > 0))
        $Attribs ['label'] = $this->Label;
      
      if (($this->Variable !== null) && (strlen ($this->Variable) > 0))
        $Attribs ['var'] = $this->Variable;
      
      return $Attribs;
    }   
    // }}}
    
    // {{{ setAttribute
    /**
     * Set an attribute of this tag
     * 
     * @param string $Name
     * @param mixed $Value
     * 
     * @access public
     * @return void
     **/
    public function setAttribute ($Name, $Value) {
      if ($Name == 'label')
        return $this->setLabel ($Value);    
      
      if ($Name == 'var')
        return $this->setVariable ($Value);
      
      if ($Name == 'type')
        return $this->setType ($Value);
          
      return parent::setAttribute ($Name, $Value);
    }   
    // }}}
    
    // {{{ addSubtag
    /**   
     * Append a tag to our collection
     * 
     * @param object $Tag
     * 
     * @access public   
     * @return void
     **/
    public function addSubtag ($Tag) {
      // Retrive the name of the new subtag
      switch ($Tag->getName ()) {
        case 'required':
        case 'desc':
          $this->removeSubtagsByName ($N);
      
          break;
        
        case 'option':
          if (!$this->isOption ())
            return false;
          
        case 'value':
          break;  
       
        default:
          return false;
      }
      
      // Let our parent do the rest
      return parent::addSubtag ($Tag);
    }
    // }}}
    
    // {{{ isRequired
    /**
     * Set or determine if this field is required
     * 
     * @param bool $Set (optional)
     * 
     * @access public
     * @return bool
     **/
    public function isRequired ($Set = null) {
      // Just return the status
      if ($Set === null)
        return $this->haveSubtags ('required');
      
      // Remove any tag just to be sure
      $this->removeSubtagsByName ('required');
      
      // Make this field required
      if ($Set === true)
        new tiggerXMPP_XML_Tag ('required', $this);
      
      return true;
    }
    // }}}
    
    // {{{ getLabel
    /**
     * Retrive the label of this field
     * 
     * @access public
     * @return string
     **/
    public function getLabel () {
      return $this->Label;
    }
    // }}}
    
    // {{{ setLabel
    /**
     * Set the label of this field
     * 
     * @param string $Label
     * 
     * @access public
     * @return bool
     **/
    public function setLabel ($Label) {
      $this->Label = $Label;
      
      return true;
    }
    // }}}
    
    // {{{ getVariable
    /**
     * Retrive the name of the assigned variable
     * 
     * @access public
     * @return string
     **/
    public function getVariable () {
      return $this->Variable;
    }
    // }}}
    
    // {{{ setVariable
    /**
     * Set name of the variable
     * 
     * @param string $Name
     * 
     * @access public
     * @return bool
     **/
    public function setVariable ($Name) {
      $this->Variable = $Name;
      
      return true;
    }
    // }}}
    
    // {{{ getDescription
    /**
     * Retrive description from this field
     * 
     * @access public
     * @return string
     **/
    public function getDescription () {
      if (!is_object ($Desc = $this->getSubtagByName ('desc')))
        return false;
        
      return $Desc->getValue ();
    }
    // }}}
      
    // {{{ setDescription
    /**
     * Set description for this field
     * 
     * @param string $Desc
     * 
     * @access public
     * @return bool
     **/
    public function setDescriptiong ($Desc) {
      // Remove any existing descriptions
      $this->removeSubtagsByName ('desc');
        
      new tiggerXMPP_XML_Tag ('desc', $this, $Desc);
      
      return true;
    } 
    // }}}
    
    // {{{ getType
    /**
     * Retrive the type of this field
     * 
     * @access public
     * @return enum
     **/
    public function getType () {
      return $this->Type;
    }
    // }}}
    
    // {{{ setType
    /**
     * Set the type of this field
     * 
     * @param enum $Type
     * 
     * @access public
     * @return bool
     **/
    public function setType ($Type) {
      if (!in_array ($Type, array (self::TYPE_BOOLEAN, self::TYPE_FIXED, self::TYPE_HIDDEN, self::TYPE_JID_MULTI, self::TYPE_JID_SINGLE, self::TYPE_LIST_MULTI, self::TYPE_LIST_SINGLE, self::TYPE_TEXT_MULTI, self::TYPE_TEXT_SINGLE, self::TYPE_TEXT_PRIVATE)))
        return false;
      
      $this->Type = $Type;
      
      return true;
    }
    // }}}
    
    // {{{ setValue
    /**
     * Set a single value for this field
     * 
     * @param string $Value
     * 
     * @access public
     * @return bool
     **/
    public function setValue ($Value) {
      $this->removeSubtagsByName ('value');
      
      new tiggerXMPP_XML_Tag ('value', $this, $Value);
      
      return true;
    }
    // }}}
    
    // {{{ addValue
    /**
     * Append (or set) a value for this field
     * 
     * @access public
     * @return bool
     **/
    public function addValue ($Value) {
      if (!$this->isMulti ())
        $this->removeSubtagsByName ('value');
      
      new tiggerXMPP_XML_Tag ('value', $this, $Value);
      
      return true;
    }
    // }}}
    
    // {{{ getValue
    /**
     * Retrive the value of this field
     * 
     * @access public
     * @return mixed
     **/
    public function getValue () {
      if (!$this->isMulti ()) {
        if (!is_object ($Tag = $this->getSubtagByName ('value')))
          return false;
        
        return $Tag->getValue ();
      }
      
      $Tags = $this->getSubtagsByName ('value');
      $out = array ();
      
      foreach ($Tags as $Tag)
        if (($v = $Tag->getValue ()) !== null)
          $out [] = $v;
        
      return $out;
    }
    // }}}
    
    // {{{ getOptions
    /**
     * Retrive all options on this field
     * 
     * @access public
     * @return array
     **/
    public function getOptions () {
      if (!$this->isOption ())
        return false;
      
      $out = array ();
      $Tags = $this->getSubtagsByName ('option');
      
      foreach ($Tags as $Tag)
        if ((($l = $Tag->getAttribute ('label')) !== null) && is_object ($V = $Tag->getSubtagByName ('value')) && (($v = $V->getValue ()) !== null))
          $out [$v] = $l;
      
      return $out;
    }
    // }}}
    
    // {{{ addOption
    /**
     * Add an option to this field
     * 
     * @param string $Value
     * @param string $Label
     * 
     * @access public
     * @return bool
     **/
    public function addOption ($Value, $Label = null) {
      if (!$this->isOption ())
        return false;
      
      if ($Label === null)
        $Label = $Value;
      
      $Tag = new tiggerXMPP_XML_Tag ('option', $this);
      $Tag->setAttribute ('label', $Label);
      
      new tiggerXMPP_XML_Tag ('value', $Tag, $Value);
      
      return true;
    }
    // }}}
    
    // {{{ setOptions
    /**
     * Set options on this field
     * 
     * @param array $Options
     * 
     * @access public
     * @return bool
     **/
    public function setOptions ($Options) {
      if (!$this->isOption ())
        return false;
      
      $this->removeSubtagsByName ('option');
      
      foreach ($Options as $Value=>$Label)
        $this->addOption ($Value, $Label);
      
      return true;
    }
    // }}}
    
    // {{{ isMulti
    /**
     * Check if this field may have more than one value
     * 
     * @access public
     * @return boolean
     **/
    public function isMulti () {
      return in_array ($this->Type, array (self::TYPE_JID_MULTI, self::TYPE_LIST_MULTI, self::TYPE_TEXT_MULTI));
    }
    // }}}
    
    // {{{ isOption
    /**
     * Check if this field is an option-field
     * 
     * @access public
     * @return bool
     **/
    public function isOption () {
      return in_array ($this->Type, array (self::TYPE_LIST_MULTI, self::TYPE_LIST_SINGLE));
    }
    // }}}
  }

?>