<?PHP

  require_once ('twIf/i18n.php');
  require_once ('twIf/object.php');
  require_once ('twIf/generic/basic.php');
  
  /**
   * Generic Listing
   * ---------------
   * Output a nice listing by using listItems() on a given class
   * 
   * @class twIf_Generic_Listing
   * @extends twIf_Generic_Basic
   * @package twIf
   * @revision 01
   * @author Bernd Holzmueller <bernd@tiggerswelt.net>
   **/
  class twIf_Generic_Listbox extends twIf_Generic_Basic {
    // Some descriptive texts
    const CAPTION = 'Select an item';
    const INTRODUCTION = 'Please select one of the following items for editing';
    
    // Allow listing to be separated into pages
    const ALLOW_PAGING = true;
    
    // Sort by this fields
    const SORT_FIELD = null;
    const SORT_ORDER = null;
    
    // Cached values for items on this widget
    protected $Counter = null;
    protected $Items = null;
    
    // Handle of any assinged filter
    protected $Filter = null;
    
    // {{{ addFilter
    /**
     * Append a filter to this widget
     * 
     * @param stirng $Caption
     * @param string $Field
     * @param enum $Type
     * @param mixed $Default (optional)
     * @param mixed $Data (optional)
     * 
     * @access public
     * @return void
     **/
    public function addFilter ($Caption, $Field, $Type, $Default = null, $Data = null) {
      if (!is_object ($this->Filter)) {
        // Load the filter-widget
        require_once ('twIf/widget/filter.php');
        
        // Create new filter-widget
        $this->Filter = new twIf_Widget_Filter ($this->getClass (), $this->getPageUUID ());
      }
      
      // Append the filter
      $this->Filter->addFilter ($Caption, $Field, $Type, $Default, $Data);
    }
    // }}}
    
    // {{{ setFilter
    /**
     * Set Value for a field on our filter
     * 
     * @param string $Field
     * @param mixed $Value
     * 
     * @access public
     * @return bool
     **/
    public function setFilter ($Field, $Value) {
      if (is_object ($this->Filter))
        return $this->Filter->setFilter ($Field, $Value);
      
      trigger_error (twIf_i18n::getText ('No filter assigned'));
      
      return false;
    }
    // }}}
    
    // {{{ getFields
    /**
     * Get Field-Definition for listing
     * 
     * @access protected
     * @return array
     */
    protected function getFields () {
      return array ();
    }
    // }}}
    
    // {{{ getSortParams
    /**
     * Retrive parameters for sorting
     * 
     * @access protected
     * @return array
     */
    protected function getSortParams () {
      return array (
        self::findConstant ('SORT_FIELD', null),
        self::findConstant ('SORT_ORDER', null),
      );
    }
    // }}}
    
    // {{{ getDefintion
    /**
     * Retrive Page-Definition from this object
     * 
     * @access public
     * @return array
     */
    public function getDefinition () {
      // Load definition from our parent
      $Base = parent::getDefinition ();
      
      // Append any filters
      if (is_object ($this->Filter))  
        $Base [] = array (
          'Type' => 'Box',
          'Content' => $this->Filter->generateFilter (),
        );
      
      // Listing
      $Base [] = array (
        'Type' => 'Listbox',
        'Source' => array ($this, 'listItems'),
        'Counter' => array ($this, 'countItems'),
        'Fields' => array ($this, 'getFields'),
        'Paging' => $this->getEnablePaging (),
        'Link' => $this->getLinkFormat (),
      );
      
      return $Base;
    }
    // }}}
    
    // {{{ generateListParams
    /**
     * Merge getListParams () and Filter-Definition into a single one
     * 
     * @access private
     * @return array
     **/
    private function generateListParams () {
      // Just return list-params
      if (!is_object ($this->Filter))
        return $this->getListParams ();
      
      // Just return filter-definition
      if (!is_array ($Params = $this->getListParams ()) || (count ($Params) == 0))
        return $this->Filter->getFilter ();
      
      // Merge Filter and List-Params
      $Filter = $this->Filter->getFilter ();
      
      foreach ($Filter as $Field=>$Value)
        if (!isset ($Params [$Field]))
          $Params [$Field] = $Value;
        else
          # TODO!
          trigger_error (twIf_i18n::getText ('Could not merge'));
      
      return $Params;
    }
    // }}}
    
    // {{{ countItems
    /**
     * Count all available Items
     * 
     * @access public
     * @return int
     */
    public function countItems () {
      // Check wheter to initialize counter-cache
      if ($this->Counter === null) {
        // Validate the callback first
        if (!is_callable (array ($this->getClass (), 'countItems')))
          return false;
        
        // Count items
        $this->Counter = call_user_func (array ($this->getClass (), 'countItems'), null, $this->generateListParams ());
      }
      
      // Return the counter
      return $this->Counter;
    }
    // }}}
    
    // {{{ listItems
    /**
     * Retrive a fresh list of Items
     * 
     * @param array $FilterDef
     * 
     * @access public
     * @return array
     */
    public function listItems ($s) {
      // Load sorting-parameters
      if (!is_array ($sP = $this->getSortParams ()) || (count ($sP) != 2))
        $sP = array (null, null);
      
      // Check if we have a valid callback
      if (!is_callable (array ($this->getClass (), 'listItems'))) {
        trigger_error (twIf_i18n::getText ('Class %s does not have listItems-interface', $this->getClass ()));
        return array ();
      }
      
      // Load the items
      return call_user_func (array ($this->getClass (), 'listItems'), null, $this->generateListParams (), $s [0], $s [1], $sP [0], $sP [1]);
    }
    // }}}
    
    // {{{ getListParams
    /**
     * Get Parameters for listItems
     * 
     * @access protected
     * @return array
     */
    protected function getListParams () {
      return null;
    }
    // }}}
    
    // {{{ getHighlight
    /**
     * Get rules for element-highlightning
     * 
     * @access protected
     * @return array
     */
    protected function getHighlight () {
      return array ();
    }
    // }}}
    
    //{{{ getEnablePaging
    /**
     * Check wheter to enable paging
     * 
     * @access protected
     * @return bool 
     */
    protected function getEnablePaging () {
      return (self::findConstant ('ALLOW_PAGING', 0) == 1);
    }
    // }}}
    
    // {{{ getLinkFormat
    /**
     * Link each element on the listbox using this link
     * 
     * @access protected
     * @return string
     **/
    protected function getLinkFormat () {
      return null;
    }
    // }}}
  }

?>