widgets/data_list/DataList.inc

<?php

/**
 * This is the base class for managing a list
 * of data points.
 *
 * @author Walter A. Boring IV <waboring@buildabetterweb.com>
 * @package phpHtmlLib
 */

define("SORTABLE", TRUE);
define("NOT_SORTABLE", FALSE);
define("SEARCHABLE", TRUE);
define("NOT_SEARCHABLE", FALSE);

//Some defines for setting up the search
//modifier fields.
define("SEARCH_BEGINS_WITH", 1);
define("SEARCH_CONTAINS", 2);
define("SEARCH_EXACT", 4);
define("SEARCH_ENDS_WITH", 8);
define("SEARCH_ALL", 15);


/**
 * This object is the base class that can be
 * used to build a widget that shows lists of
 * data from any source via the DataListSource
 * object.  It fetches/builds/gets its data
 * from the DataListSource object, which can
 * be written to support any data source 
 * (MySQL, Oracle, comma delimited file, xml, etc.)
 *
 * This base class MUST be extended by a child to
 * actually render the list.  The job of the DataList
 * class is to provide the basic API and abstraction
 * mechanism to handling searching, showing, sorting
 * lists of data.
 *
 * Each column of data is associated with a title and a
 * name.  The title is what is shown to the user for that
 * column.  The name is the mapping between the column and
 * the DataListSource.  Each column can be marked
 * as sortable and searchable.  If a column is sortable,
 * the title is a link that can be clicked on to sort.
 * The sorting is done in the DataListSource object (
 * via the sql query, or sort() functions depending on the
 * data source itself)
 *
 * The DataList object will build the title, the search block
 * (if any), the datalist controls (the links/imges for 
 * first, prev, next, last, all).  Then the data columns/labels.
 * Then it will fetch each of the rows of data to display 
 * from the DataListSource.
 *
 * The logic of the output calls follows in the order:
 *
 * title
 * search table/block
 * datalist controls (first, prev, next, last, all)
 * data columns/labels
 * data rows x through y
 *
 *
 * REQUIREMENTS:
 *  You must use/define a DataListSource object. 
 *  You MUST override/extend the following methods:
 *
 *  * get_data_source() - used to set the DataListSource
 *                         by this class.
 *  * user_setup() - used to set the columns to show and any
 *                   options used by the DataList class and
 *                   DataListSource object.
 *
 *
 *  UI ABSTRACTION METHODS
 *  These methods allow for some level of abstraction for
 *  the layout/look/feel of the actual list of data.
 *
 *
 *  * gui_init() - the function gives the child class a chance
 *                 to do any building of the objects that will
 *                 hold the search area, column headers and the
 *                 rows of data.
 *
 *  * child_build_column_header() - This method is responsible
 *                                  for building and inserting
 *                                  the column header title into
 *                                  the UI object.
 *
 *  * child_add_row_cell() - This function is responsible for adding
 *                           the cell in the current row.  The method
 *                           is responsible for keeping track of the 
 *                           location in its UI object for the current
 *                           row.
 *
 *  * child_get_gui() - This method returns the entire UI in 1 object 
 *                      or container.  At this point the entire UI
 *                      has been constructed, the entire list of data
 *                      has been walked and inserted.  
 *
 *
 * @author Walter A. Boring IV <waboring@buildabetterweb.com>
 * @package phpHtmlLib 
 */
class DataList extends BaseWidget {

    /**
     * This value holds the number
     * of pages of data we have
     * to display.
     *
     */
    var $_num_pages=1;

    /**
     * The number of rows of data
     * to show per "page".
     * The default is 20.
     *
     */
    var $_default_rows_per_page = 10;

    /**
     * The max number of rows to
     * show when the user does the
     * "EXPAND" command.
     */
    var $_max_rows = 200;


    /**
     * Do we want to alternate the row colors?
     * This helps to see each row easier.
     */
    var $alternating_row_colors = TRUE;

    /**
     * prefix for all list variable
     * names, so we can potentially
     * have more then 1 list per page.
     */
    var $_global_prefix = '';

    /**
     * The offset variable name
     */
    var $_offsetVar = "offset";

    /**
     * The order by variable name
     */
    var $_orderbyVar = "orderby";

    /**
     * Holds the db column name that
     * we want to order by default.
     */
    var $_default_orderby = '';

    /**
     * The reverseorder variable name
     */
    var $_reverseorderVar = "reverseorder";

    /**
     * Holds a flag to let us know to
     * reverse order the column by default
     */
    var $_default_reverseorder = "false";

    /**
     * The number of rows variable name
     */
    var $_numrowsVar = "numrows";

        /**
     * This var to tell us to show all
     * data or not.
     */
    var $_showallVar = "showall";

    /**
     * The search field variable
     */
    var $_search_fieldVar  = "search_field";

    /**
     * The search value
     */
    var $_search_valueVar  = "search_value";

    /**
     * The type of search
     * advanced/simple
     */
    var $_search_typeVar = "search_type";

    /**
     * The simple search modifier
     * var name.
     *
     */
    var $_simple_search_modifierVar = "simple_search_modifier";
  

    /**
     * Flag to let us know that search
     * is enabled.
     *
     */
    var $_search_flag = FALSE;

    /**
     * Flag to let us know that
     * advanced search is enabled
     *
     */
    var $_advanced_search_flag = FALSE;

    /**
     * Flag to enable simple search modifyer.
     * IF enabled it will add a select that adds
     * the "beings with", "contains" options for
     * a simple search.
     */
    var $_simple_search_modifier = FALSE;


        /**
         * Holds the object block that is the
         * search UI
         */
        var $_search_table = NULL;

    /**
     * This holds a list of
     * name=>value vars that the
     * caller/child wants to propogate
     * automatically.
     *
     */
    var $_save_vars = array();


        /** 
         * The column descriptions
         * for the data we are working on
         * 
         * @var array
         */
        var $_columns = array();

        /**
     * Keeps track of the # of columns we have
     */
    var $_num_columns = 0;


        /**
         * This holds the form attributes
         *
         */
        var $_form_attributes = array("method" => "GET",
                                                                  "target" => "",
                                                                  "action" => "",
                                                                  "name" => "");

        /**
         * Build everything inside a form?
         *
         */
        var $_form_render_flag = FALSE;


        /**
         * flag to let us know if we want to show
         * the results or not.
         */
        var $_show_results_flag = TRUE;


        /**
         * Holds our reference/copy of the
         * DataListSource object which is used to
         * access the data that this object uses
         *
         * @var DataListSource object
         */
        var $_datasource = NULL;

        /**
         * This stores the base path to where the
         * tool link images live.  This lets you
         * specify a new path to where your images
         * live.
         */
        var $_image_path = "img/widgets";


        /**
         * The constructor
         *
         * @param string - the title of the data list
         * @param string - the overall width
         * @param string - the column to use as the default sorting order
         * @param boolean - sort the default column in reverse order?
         */
        function DataList($title, $width = "100%", $default_orderby='', 
                                          $default_reverseorder=FALSE) {
                $this->set_title( $title );
                $this->set_form_name( str_replace(' ', '_', strtolower($title)) );
                $this->set_width( $width );

        $this->_default_orderby = $default_orderby;
                if ($default_reverseorder === TRUE) {
                        $default_reverseorder = "true";
                } if ($default_reverse_order === FALSE) {
                        $default_reverseorder = "false";
                }
        $this->_default_reverseorder = $default_reverseorder;


        //Set the global prefix for our variables.
        //want to make sure we can have multiple
        //item lists per html page.
        $this->set_global_prefix('');

                //child class MUST override this
                //method to automatically set
                //the DataListSource object.
                //This class doesn't work without it.
                $this->get_data_source();

        //Call the subclass setup function.
        //This is a way to get around having
        //to override the constructor and
        //pass in the same params.
        $this->user_setup();
        }

        /**
         * This function renders the final 
         * widget
         *
         */
        function render($indent_level, $output_debug) {

                //setup the columns in their sorts
                $this->setup_columns();

                //do any data prefetch work
                //which may be child specific
                if ($this->_show_results()) {
                        $this->data_prefetch();
                }

                //This function gives the child class
                //a chance to build the tables/divs/containers
                //that will be responsible for the look/feel
                //of the DataList
                $this->gui_init();

                //see if we need to build the search area.
                if ($this->is_search_enabled() || $this->is_advanced_search_enabled()) {
                        $this->_search_table = $this->child_build_search_table();
                        if ($this->_search_table) {
                                $this->set_form_render(TRUE);
                        }
        }
                

        if ($this->get_form_render()) {
            $form =  new FORMtag( array("method" => $this->get_form_method(),
                                        "action" => $this->build_base_url(),
                                        "name" => $this->get_form_name(),
                                        "style" => "margin-top: 0px;margin-bottom:0px;") );

                        $target = $this->get_form_target();
            if ($target != NULL)
                $form->set_tag_attribute("target",$target);

                        $action = $this->get_form_action();
            if ($action != NULL)
                $form->set_tag_attribute("action",$action);

                        //now build the UI and return it
                        $form->add( $this->build_gui() );

                        //add the save vars the user wants.
                        $form->add( $this->_build_save_vars() );
        } else {
                        $form = container();

                        //now build the UI and return it
                        $form->add( $this->build_gui() );
                }

                //add any javascript required
        $container = container( $this->_javascript(), $form );
        return $container->render( $indent_level, $output_debug );
        }

        /**
         * This function is responsible for calling the child
         * class's methods for building the GUI container.
         * This function builds the search area, the 
         * title, page controls, the column headers, 
         * and walks the rows of data and adds them
         *
         * A child class can override this method to
         * move the placement of the search box
         * relative to the data list.  By default
         * the search area comes above the table
         * for the data list and page controls
         * 
         * @return Container
         */
        function build_gui() {
                $container = container();
                
                //if we have a search area to show
                //add it to the ui.
                if ($this->_search_table) {
                        $container->add( $this->_search_table );
                }

                if ($this->_show_results()) {
                        //walk the list of columns and call the child
                        //method to add it
                        $column_count = count($this->_columns);
                        foreach( $this->_columns as $name => $col ) {
                                $this->child_build_column_header( $name, $col, $column_count);
                        }
                        
                        //now walk the list of rows and build and add the
                        //cells of data 
                        $col_count = count($this->_columns);
                        while ($row = $this->_datasource->get_next_data_row()) {
                                $cnt = 1;
                                foreach( $this->_columns as $col_name => $data ) {
                                        $obj = $this->build_column_item($row, $col_name);
                                        if (!is_object($obj)) {
                                                $obj = $this->_clean_string($obj, $col_name);
                    }
                                        //
                                        $this->child_add_row_cell($obj, $col_name, ($cnt == $col_count) ? TRUE : FALSE);
                                        $cnt++;
                                }
                        }
                        $container->add( $this->child_get_gui() );
                }
                

                return $container;
        }

        /**
         * This function is called automatically by
         * the DataList constructor.  It must be
         * extended by the child class to actually
         * set the DataListSource object.
         *
         * 
         */
        function get_data_source() {
                user_error("DataList::get_data_source() - ".
                                   "child class must override this to ".
                                   "set the the DataListSource object.");
        }

    /**
     * A subclass can override this function
     * to setup the class variables after
     * the constructor.  The constructor
     * automatically calls this function.
         *
     */
    function user_setup() {
        user_error("DataList::user_setup() - ".
                                   "child class must override this method ".
                                   "to set the columns, and any options for ".
                                   "the DataListSource.");
    }

    /**
     * A subclass can override this function
     * to setup the class variables after
     * the constructor.  The constructor
     * automatically calls this function.
         *
     */
    function gui_init() {
        user_error("DataList::gui_init() - ".
                                   "child class must override this method ".
                                   "to set up the containers/objects that will ".
                                   "hold the search area, page controls, ".
                                   "column headers and the data cells");
    }

        /**
         * This method is supposed to be written by
         * the child class to build and add the column 
         * title to the UI
         * 
         * @param string - the title of the column
         * @param array - the column data ( from $this->_columns )
         * @param int - the column #
         *
         */
        function child_build_column_header($title, $col_data, $col_count) {
                user_error("DataList::child_build_column_header() - ".
                                   "child class must override this method ".
                                   "to build the object that will be the ".
                                   "individual column header/itle");
        }

        /**
         * This method is supposed to be written by
         * the child class to add the cell data to the
         * current row in the UI
         * 
         * @param mixed - the object/string/entity that
         *                should get put into the column row cell.
         * @param string - the name/title of the column that the
         *                 object will live in
         * @param boolean - flag that tells the function if this is
         *                  is the last cell for the current row.
         *
         */
        function child_add_row_cell($obj, $col_name, $last_in_row_flag) {
                user_error("DataList::child_build_column_header() - ".
                                   "child class must override this method ".
                                   "to build the object that will be the ".
                                   "individual column header/itle");
        }

        /**
         * This function is called after all of the data has 
         * been added to the UI object.  It just returns the 
         * container that is the entire UI for the DataList
         *
         * @return Container
         */
        function child_get_gui() {
                user_error("DataList::child_get_gui() - ".
                                   "child class must override this method ".
                                   "to return the wrapper that contains ".
                                   "the entire UI.");
        }

        /**
         * This function builds the search
         * block that lives above the results
         *
         * @return Container
         */
        function child_build_search_table() {
                user_error("DataList::child_build_search_table() - ".
                                   "child class must override this");
                return NULL;
        }

        /**
     * This function provides a way to automatically
     * add javascript to this object.
     * This function is meant to be extended by the
     * child class.
     *
     * @return SCRIPTtag object
     */
    function _javascript() {
        return NULL;
    }

    /**
     * This function adds a header item to the column headers
     * from a list of parameters.
     *
     * @param string - $label - the label to use for
     *                          the column header.
     * @param int    - $size - the size for the table column.
     * @param string - $dbfield - the db field associated
     *                            with this label from the query.
     * @param boolean - $sortable - flag to make this column sortable.
     * @param boolean - $searchable - flag to make this column searchable.
     * @param string - header align value.
     * @param string - the maximum # of characters to allow in the cell.
     *
     * @return array a single header array
     */
    function add_header_item( $label, $size=100, $data_name=NULL,
                              $sortable=FALSE, $searchable=FALSE,
                              $align="left", $sortorder="",
                              $max_text_length=NULL) {

        $this->_columns[$label] = array("size" => $size,
                                                                           "data_name" => $data_name,
                                                                           "sortable" => $sortable,
                                                                           "searchable" => $searchable,
                                                                           "align" => $align,
                                                                           "sortorder" => $sortorder,
                                                                           "maxtextlength" => $max_text_length);
        $this->_num_headers++;
                
                $this->_check_datasource("add_header_item");
                $this->_datasource->add_column($label, $data_name, $sortable,
                                                                                $searchable, $sortorder);
    }


    /**
     * This function sets a prefix for all
     * variables that are used in the item list
     * table on a page.  This allows you to have
     * multiple itemlists on a single html page.
     *
     * @param string $prefix - the prefix for all vars.
     */
    function set_global_prefix($prefix) {
        $this->_global_prefix           = $prefix;
        $this->_offsetVar                       = $prefix . "offset";
        $this->_orderbyVar                      = $prefix . "orderby";
        $this->_reverseorderVar         = $prefix . "reverseorder";
        $this->_numrowsVar                      = $prefix . "numrows";
        $this->_showallVar                      = $prefix . "showall";
        $this->_search_fieldVar         = $prefix . "search_field";
        $this->_search_valueVar         = $prefix . "search_value";
                $this->_search_typeVar          = $prefix . $this->_search_typeVar;
        $this->_simple_search_modifierVar = $prefix . $this->_simple_search_modifierVar;
    }

    /**
     * returns the current variable prefix
     * string being used.
     *
     * @return string - current global prefix
     */
    function get_global_prefix() {
        return $this->_global_prefix;
    }

        /**
         * This function is used to set the 
         * DataListSource object for this instance
         *
         * @param DataListSource object
         */
        function set_data_source( $datasource ) {
                $this->_datasource = &$datasource;
        }

    /**
     * Enable the search ability.
     *
     * @param boolean
     */
    function search_enable( ) {
        $this->_search_flag = TRUE;
        if (!$this->is_advanced_search_enabled()) {
            $this->set_search_type("simple");
        }
    }

    /**
     * Disable the search ability.
     *
     * @param boolean
     */
    function search_disable( ) {
        $this->_search_flag = FALSE;
    }

    /**
     * get the status of the search
     * ability.
     *
     * @return boolean
     */
    function is_search_enabled() {
        return $this->_search_flag;
    }


    /**
     * Enable the advanced search
     * capability
     * NOTE: Child class MUST
     *       extend the
     *       _build_advanced_search_table
     */
    function advanced_search_enable() {
        $this->_advanced_search_flag = TRUE;
        if (!$this->is_search_enabled()) {
            $this->set_search_type("advanced");
        }
    }

    /**
     * Disable the advanced search
     * capability
     *
     */
    function advanced_search_disable() {
        $this->_advanced_search_flag = FALSE;
    }

    /**
     * This returns the status of the
     * advanced search flag.
     *
     * @return boolean
     */
    function is_advanced_search_enabled() {
        return $this->_advanced_search_flag;
    }

    /**
     * Set the simple search modifyer
     * flag.
     * NOTE: by default all the modifiers
     *       are enabled.  You can limit the
     *       modifiers by passing in the
     *       string of defines of which ones
     *       you want enabled.
     *
     * MODIFIERS:
     *          SEARCH_BEGINS_WITH
     *          SEARCH_CONTAINS
     *          SEARCH_EXACT
     *          SEARCH_ENDS_WITH
     *
     *       ie. SEARCH_BEGINS_WITH.SEARCH_EXACT
     *           will enable ONLY the
     *           "begins with" and "exact" modifiers.
     *
     * @param string
     */
    function set_simple_search_modifier( $modifier = SEARCH_ALL ) {
        if ($modifier == 0) {
            $this->_simple_search_modifier = SEARCH_BEGINS_WITH |
                                             SEARCH_CONTAINS |
                                             SEARCH_EXACT |
                                             SEARCH_ENDS_WITH;
        } else {
            $this->_simple_search_modifier = $modifier;
        }
    }

    /**
     * gets the value of the search modifier
     * flag.
     */
    function get_simple_search_modifier() {
        return $this->_simple_search_modifier;
    }

    /**
     * This function sets the default # of rows
     * per page to display.  By default its 10.
     * This lets the user override this value.
     *
     * @param int - the # of rows to use.
     */
    function set_default_num_rows( $num_rows ) {
        $this->default_rows_per_page = $num_rows;
    }

    /**
     * This function gets the current default
     * number of rows to display setting.
     *
     * @return int
     */
    function get_default_num_rows( ) {
        return $this->_default_rows_per_page;
    }


    /**
     * This function sets the save variables
     * that the user/child wants to automatically
     * propogate
     *
     * @param array - name=>value pairs of the data
     *                that they want to propogate
     */
    function set_save_vars( $vars ) {
        $this->_save_vars = $vars;
    }

        /**
         * This returns the Maximum # of rows to 
         * display when in expand mode
         *
         * @return int
         */
        function get_max_rows() {
                return $this->_max_rows;
        }

        /**
         * This sets the maximum # of rows to
         * display when in expand mode
         *
         * @param int - new # of maximum rows
         *              to display when in 'expand' mode
         *
         */
        function set_max_rows( $max ) {
                $this->_max_rows = $max;
        }


        /**
         * This function is used to set up any
         * data that needs to be munged before the
         * data is fetched from the DataListSource
         *
         */
        function data_prefetch() {
                $this->_check_datasource("data_prefetch");

                if ($this->showall()) {
                        $this->set_default_num_rows( $this->get_max_rows() );
                        $this->set_numrows( $this->get_max_rows() );
                }

                $limit = $this->numrows();
                $this->_datasource->query($this->offset(), $limit,
                                                                   $this->orderby(), $this->reverseorder(), 
                                                                   $this->search_field(), $this->search_value(),
                                                                   $this->simple_search_modifier_value(),
                                                                   $this->search_type() );
        }


    /*
     * Takes an array of (name, sortable, db_field, alignment,
     * size), with one element corresponding to each column.
     */
    function setup_columns() {
        $temp_headers = array();

        foreach( $this->_columns as $col_name => $data ) {
            if ($data["sortorder"] == "reverse") {
                $data["reverseorder"] = "true";
            }
            else {
                $data["reverseorder"] = "false";
            }
            $temp_headers[$col_name] = $data;
        }
        $this->_columns = $temp_headers;
    }


        /**
         * general DataListSource object checker.
         *
         */
        function _check_datasource($function_name) {
                if (!is_object($this->_datasource)) {
                        user_error("DataList::".$function_name."() - DataListSource object is not set");
                        exit;
                }
        }


        /*********************************************/
        /*     REQUEST VARIABLE SECTION              */
        /*********************************************/

        /**
     * This function returns the current value
     * of the offset variable. This is an offset
     * into the query return data set.
     *
     * @return int - the current value.
     */
    function offset() {
                if (!$_REQUEST[$this->_offsetVar]) {
                        $this->set_offset(0);
                }
                return (int)$_REQUEST[$this->_offsetVar];
    }

        /**
     * This function is used to set/change
     * the offset for this list.
     *
     * @param int - the new offset.
     */
    function set_offset($new_offset) {
                $_REQUEST[$this->_offsetVar] = $new_offset;
    }

        /**
     * This function returns the value of the
     * current orderby variable.
     *
     * @return string.
     */
    function orderby() {
                if (!$_REQUEST[$this->_orderbyVar]) {
                        $_REQUEST[$this->_orderbyVar] = $this->_default_orderby;
                }

                return $_REQUEST[$this->_orderbyVar];
    }

        /**
     * This builds a query string var for the
     * orderby value.
     *
     * @return string - "orderby=(thevalue)"
     */
    function build_orderby_querystring() {
        $str = $this->_orderbyVar."=".$this->orderby();
        return $str;
    }

    /**
     * This function returns the current value of
     * the reverse order member variable.
     *
     * @return string.
     */
    function reverseorder() {
                if (!$_REQUEST[$this->_reverseorderVar]) {
                        $this->set_reverseorder($this->_default_reverseorder);
                }
                return $_REQUEST[$this->_reverseorderVar];
    }

    /**
     * This function sets the reverse order flag
     * to a new value.
     *
     * @param string - the new value.
     */
    function set_reverseorder($new_value) {
                $_REQUEST[$this->_reverseorderVar] = $new_value;
    }

        /**
     * This builds a query string var for the
     * reverseorder value.
     *
     * @return string - "orderby=(thevalue)"
     */
    function build_reverseorder_querystring() {
        $str = $this->_reverseorderVar."=".$this->reverseorder();
        return $str;
    }

    /**
     * This function returns the number of rows
     * that the query found.
     *
     * @return int - the number of rows
     */
    function numrows() {
                if (!$_REQUEST[$this->_numrowsVar]) {
                        $this->set_numrows($this->_default_rows_per_page);
                }
                return (int) $_REQUEST[$this->_numrowsVar];
    }

    /**
     * This function sets the # of rows to display
     * per page.
     *
     * @param int - the # of rows
     */
    function set_numrows($new_numrows) {
                $_REQUEST[$this->_numrowsVar] = $new_numrows;
    }

    /**
     * returns the current value of
     * the search field name
     *
     * @return string
     */
    function search_field() {
                if (!$_REQUEST[$this->_search_fieldVar]) {
                        $_REQUEST[$this->_search_fieldVar] = '';
                }
                return $_REQUEST[$this->_search_fieldVar];
    }

        /**
     * This builds a query string var for the
     * searchfield value.
     *
     * @return string - "orderby=(thevalue)"
     */
    function build_searchfield_querystring() {
        $str = $this->_search_fieldVar."=".$this->searchfield();
        return $str;
    }

    /**
     * returns the current value of
     * te search field value.
     *
     * @return string
     */
    function search_value() {
                if (!$_REQUEST[$this->_search_valueVar]) {
                        $_REQUEST[$this->_search_valueVar] = '';
                }
                return $_REQUEST[$this->_search_valueVar];
    }

        /**
     * This builds a query string var for the
     * searchfield value.
     *
     * @return string - "orderby=(thevalue)"
     */
    function build_searchvalue_querystring() {
        $str = $this->_search_valueVar."=".$this->search_value();
        return $str;
    }

    /**
     * returns the current value of the
     * simple search modifier
     *
     * @return string
     */
    function simple_search_modifier_value() {
                if (!$_REQUEST[$this->_simple_search_modifierVar]) {
                        $_REQUEST[$this->_simple_search_modifierVar] = '';
                }
                return $_REQUEST[$this->_simple_search_modifierVar];
    }


    /**
     * returns the type of search being used
     *
     * @return string
     */
    function search_type() {
                if (!$_REQUEST[$this->_search_typeVar]) {
                        $_REQUEST[$this->_search_typeVar] = "simple";
                }
                return $_REQUEST[$this->_search_typeVar];
    }

    /**
     * This function sets the search type
     *
     * @param string - the search type
     *                 "simple" or "advanced"
     */
    function set_search_type($type) {
                $_REQUEST[$this->_search_typeVar] = $type;
    }


    /**
     * returns the current value of the showall
     * flag.  This tells us if they want the entire
     * list of data back from the DB.
     *
     * @return string - the current value
     */
    function showall() {
                if (!$_REQUEST[$this->_showallVar]) {
                        $_REQUEST[$this->_showallVar] = 0;
                }
                return (int) $_REQUEST[$this->_showallVar];
    }

    /**
     * This is the basic function for letting us
     * do a mapping between the column name in
     * the header, to the value found in the DB.
     *
     * NOTE: this function is meant to be overridden
     *       so that you can push whatever you want.
     *
     * @param array - $row_data - the entire data for the row
     * @param string - $col_name - the name of the column header
     *                             for this row to render.
     * @return  mixed - either a HTMLTag object, or raw text.
     */
    function build_column_item($row_data, $col_name) {
        $key = $this->_columns[$col_name]["data_name"];

        if ($row_data[$key] == '') {
            return "&nbsp;";
        } else {
            return $this->_filter_column_string($row_data[$key]);
        }
    }


    /**
     * This does some magic filtering on the data
     * that we display in a column.  This helps
     * to prevent nast data that may have html
     * tags in it.
     *
     * @param string - the column data u want to filter
     * @return string the cleaned/filtered data
     */
    function _filter_column_string($data) {
        return htmlspecialchars(trim($data));
    }


        /*******************************************/
        /*         FORM VARIABLES SECTION          */
        /*******************************************/

        /**
     * This function is used to set the
     * form name
     *
     * @param string
     */
    function set_form_name($name) {
        $this->_form_attributes["name"] = $name;
    }

    /**
     * This function is used to get
     * the form name
     *
     * @return string
     */
    function get_form_name() {
        return $this->_form_attributes["name"];
    }

    /**
     * This function is used to set the
     * form target
     *
     * @param string
     */
    function set_form_target($target) {
        $this->_form_attributes["target"] = $target;
    }

    /**
     * This function is used to get
     * the form target
     *
     * @return string
     */
    function get_form_target() {
        return $this->_form_attributes["target"];
    }
    
    /**
     * This function is used to set the
     * form method
     *
     * @param string (POST or GET)
     */
    function set_form_method($method) {
                if ($method != "GET" && $method != "POST") {
                        user_error("DataList::set_form_method() - INVALID Form method ".$method);
                } else {
                        $this->_form_attributes["method"] = $method;
                }
    }

    /**
     * This function is used to get
     * the form method
     *
     * @return string (POST or GET)
     */
    function get_form_method() {
        return $this->_form_attributes["method"];
    }

   /**
    * Sets the form action
    *
    * @param string
    */
    function set_form_action($action) {
        $this->_form_attributes["action"] = $action;
    }

        /**
     * This function is used to get
     * the form action
     *
     * @return string (POST or GET)
     */
    function get_form_action() {
        return $this->_form_attributes["action"];
    }

    /**
    * Sets whether to the output into a form
    *
    * @param bool
    */
    function set_form_render($flag) {
        $this->_form_render_flag = $flag;
    }

    /**
    * Return the state of the form render
    *
    * @return bool
    */
    function get_form_render() {
        return $this->_form_render_flag;
    }

    /**
         * This function is used to set the
         * message displayed when no data is found
         *
         * @param string
         */
    function set_not_found_message($mesg) {
                $this->_check_datasource("set_not_found_message");
        $this->_datasource->set_not_found_message($mesg);
    }


        /**
         * This function is used to set the value
         * of the _show_results_flag
         *
         * @param boolean - TRUE to show the results
         */
        function set_show_results( $flag=TRUE ) {
                $this->_show_results_flag = $flag;
        }
         

        /**
         * This function is used to let render() know
         * that we should show the results or not.
         * 
         * @return boolean
         */
        function _show_results() {
                return $this->_show_results_flag;
        }

        /**
     * this method builds some hidden
     * form fields to automatically
     * be placed inside the form.
     *
     * @return ContainerWidget object.
     */
    function _build_save_vars() {
        $container = container();
        foreach($this->_save_vars as $name => $value) {
            $container->add(form_hidden($name, $value));
        }
        return $container;
    }

        /**
     * This function sets the save variables
     * that the user/child wants to automatically
     * propogate
     *
     * @param array - name=>value pairs of the data
     *                that they want to propogate
     */
    function set_save_vars($vars) {
        $this->_save_vars = $vars;
    }

    /**
     * This builds the base url used
     * by the column headers as well
     * as the page tool links.
     *
     * it basically builds:
     * $_SELF?$_GET
     *
     * @return string
     */
    function build_base_url() {

        $url = $_SERVER["PHP_SELF"]."?";

        if ($this->get_form_method() == "POST") {
            return $url;
        }

                $vars = array_merge($_POST, $_GET);
        //request method independant access to
        //browser variables
        if (count($vars)) {
            //walk through all of the get vars
            //and add them to the url to save them.
            foreach($vars as $name => $value) {

                if ($name != $this->_offsetVar &&
                    $name != $this->_orderbyVar &&
                    $name != $this->_reverseorderVar &&
                    $name != $this->_search_valueVar
                   ) {
                    if (is_array($value)) {
                        $url .= $name."[]=".implode("&".$name."[]=",$value)."&";
                    } else {
                                                $url .= $name."=".urlencode(stripslashes($value))."&";
                                        }
                }
            }
        }

        return $url;
    }

        /**
         * This function builds the 'tool' images that
         * allow  you to walk through the data list itself.
         * It provides image links for 
         * first - go to the first page in the data list
         * prev - go to the previous page in the data list
         * next - go to the next page in the data list
         * last - go to the last page in the data list
         * all - show the rest of the list from the current offset
         *
         * @param string - which tool image to build
         * @return Object
         */
        function build_tool_link( $which ) {
                $num_pages = $this->get_num_pages();
        $cur_page = $this->get_current_page();
        $last_page = $this->get_last_page();

                $image_path = $this->get_image_path();
                switch ($which) {
                
                case "first":
                        $rows_string = "First ".$this->get_default_num_rows()." Rows";
                        if ($this->offset() <= 0) {
                                $obj = html_img($image_path."/first_group_button_inactive.gif",
                                                                '','',0,$rows_string, NULL, $rows_string);
                        } else {
                $url = $this->_build_tool_url(0);
                                $obj = html_img_href($url, $image_path."/first_group_button.gif",
                                                                         '','',0, $rows_string, NULL, NULL, $rows_string);
            }
                        break;

                case "prev":
                        $rows_string = "Previous ".$this->get_default_num_rows()." Rows";
                        if ($this->offset() <= 0) {
                                $obj = html_img($image_path."/prev_group_button_inactive.gif",
                                                                '','',0,$rows_string, NULL, $rows_string);
                        } else {
                                $offset = $this->offset() - $this->numrows();
                                if ($offset < 0) {
                                        $offset = 0;
                                }
                                $url = $this->_build_tool_url($offset);
                                $obj = html_img_href($url, $image_path."/prev_group_button.gif",
                                                                         '','',0, $rows_string, NULL, NULL, $rows_string);
                        }
                        break;

                case "next":
                        $rows_string = "Next ".$this->get_default_num_rows()." Rows";
                        if (($num_pages == 1) || ($cur_page == $last_page)) {
                                $obj = html_img($image_path."/next_group_button_inactive.gif",
                                                                '','',0, $rows_string, NULL, $rows_string);
                        } else {
                                $offset = $this->offset() + $this->numrows();
                                $url = $this->_build_tool_url($offset);
                                $obj = html_img_href($url, $image_path."/next_group_button.gif",
                                                                         '','',0, $rows_string, NULL, NULL, $rows_string);
                        }
                        break;

                case "last":
                        $rows_string = "Last ".$this->get_default_num_rows()." Rows";
                        if (($num_pages == 1) || ($cur_page == $last_page)) {
                                $obj = html_img($image_path."/last_group_button_inactive.gif",
                                                                '','',0, $rows_string, NULL, $rows_string);
                        } else {
                                $offset = (int)(($num_pages - 1) * $this->numrows());
                                $url = $this->_build_tool_url($offset);
                                $obj = html_img_href($url, $image_path."/last_group_button.gif",
                                                                         '','',0, $rows_string, NULL, NULL, $rows_string);
                        }
                        break;

                case "all":
                        $offset = $this->offset();
                        if ($this->showall()) {
                                $url = $this->_build_tool_url($offset, TRUE, 0);
                                $obj = html_img_href($url, $image_path."/close_group_button.gif",
                                                                         '','',0,"Collapse Rows", NULL, NULL, "Collapse Rows");
                        } else {
                                if (($num_pages == 1)) {
                                        $obj = html_img($image_path."/expand_group_button_inactive.gif",
                                                                        '','',0, "Expand Rows", NULL, "Expand Rows");
                                } else {
                                        $url = $this->_build_tool_url($offset, TRUE, 1);
                                        $obj = html_img_href($url, $image_path."/expand_group_button.gif",
                                                                                 '','',0,"Expand Rows", NULL, NULL, "Expand Rows");
                                }
                        }
                        //so we don't save it into the mozilla navigation bar links
                        unset($url);
                        break;
                }

                if ($url) {
                        $this->_save_mozilla_nav_link($which, $url);
                }
                
                return $obj;
        }

        /**
         * This function is used to build the url
         * for a tool link.  
         * (first, prev, next, last, all)
         *
         * @param int - the offset for the link
         * @param boolean - add the showall value to the url
         * @param int - the showall value to use if the flag is on
         *
         * @return string
         */
        function _build_tool_url($offset, $showall_flag=FALSE, $showall_value=0) {
                if ($this->get_form_method() == "POST") {
                        $form_name = $this->get_form_name();
                        $url = "javascript: document.".$form_name;
                        $url .= ".".$this->_offsetVar.".value='".$offset."';";

                        //add the showall variable to the post
                        if ($showall_flag) {
                                $form_field = $this->_showallVar;
                $url .= "document.".$form_name.".";
                                $url .= $form_field.".value='".$showall_value."';";
                        }

                        $url .= "document.".$form_name.".submit();";
                } else {
                        $url = $this->build_base_url();
                        $url .= $this->build_state_vars_query_string($offset, $showall_flag,
                                                                                                                 $showall_value);
                }
                return $url;
        }

    /**
     * this function is used to build a sub query string
     * of all of the query string vars to save the
     * state of the DBItemList.  This is used for pages
     * that want to come back to the list at the same state
     *
     * @return string - name=value& pairs
     */
    function build_state_vars_query_string($offset, $showall_flag=FALSE,
                                                                                   $showall_value=0) {
        $str = "";

        $str .= $this->_offsetVar."=".urlencode($offset);
        $str .= "&".$this->_orderbyVar."=".urlencode($this->orderby());
        $str .= "&".$this->_reverseorderVar."=".urlencode($this->reverseorder());
        $str .= "&".$this->_search_fieldVar."=".urlencode($this->search_field());
        $str .= "&".$this->_search_valueVar."=".urlencode($this->search_value());
        $str .= "&".$this->_simple_search_modifierVar."=".urlencode($this->simple_search_modifier_value());
        $str .= "&".$this->_search_typeVar."=".urlencode($this->search_type());
                if ($showall_flag) {
                        $str .= "&".$this->_showallVar."=".urlencode($showall_value);
                }

        return $str;
    }

        /**
         * This function stores the url for each of the tool
         * urls, so we can push these out for mozilla.
         * Mozilla has a nice navigation bar feature that
         * lets you program first, prev, next, last links
         *
         * @param string - which tool link
         * @param string - the url for that link
         */
        function _save_mozilla_nav_link($which, $url) {
                $this->_mozilla_nav_links[$which] = $url;
        }


        /**
         * This function returns the path to the
         * images used in this class
         *
         * @return string
         */
        function get_image_path() {
                return $this->_image_path;
        }

        /**
         * This function returns the path to the
         * images used in this class
         *
         * @return string
         */
        function set_image_path($path) {
                return $this->_image_path = $path;
        }

    /**
     * This function returns the current
     * page that the item list is on.
     *
     * @return int
     */
    function get_current_page() {
        return((int) ($this->offset() / $this->numrows())) + 1;
    }

    /**
     * This function returns the #
     * of pages that are available
     * for this list of items.
     *
     * @return int
     */
    function get_num_pages() {
                $this->_check_datasource("get_num_pages");
                $total_rows = $this->_datasource->get_total_rows();

        $cnt = (int)($total_rows / $this->numrows());
        if ((($total_rows % $this->numrows()) != 0) || ($total_rows == 0)) {
            $cnt++;
        }
        return $cnt;
    }

    /**
     * This calculates the last page #
     * for this list of items
     *
     * @return int
     */
    function get_last_page() {
        return $this->get_num_pages();
    }

    /**
     * This function builds the string
     * that describes the current page
     * out of n pages the list is showing
     *
     * @return string (ie. 1 to 10 of 25)
     */
    function get_page_info() {
        $cur_page = $this->get_current_page();
        $low_range = $this->offset() + 1;
        $num_pages = $this->get_num_pages();
        $num_rows_per_page = $this->numrows();

                $this->_check_datasource("get_page_info");
                $total_rows = $this->_datasource->get_total_rows();

        $high_range = $low_range + ($num_rows_per_page - 1);
        if ($high_range > $total_rows) {
            $high_range = $total_rows;
        }

        if ($total_rows == 0) {
            $str = "0 of 0";
        } else {
            $str  = $low_range . " to ". $high_range;
            $str .= " of ".$total_rows;
        }

        return $str;
    }


    /**
     * This builds a url for a particular
     * column header.
     *
     * @param string - $col_name
     * @return Atag object;
     */
    function build_column_url($col_name) {
        $orderby = $this->orderby();
        $reverseorder = $this->reverseorder();
        $search_value = $this->search_value();

        $order_value = $this->_columns[$col_name]["data_name"];
        $reverse_value = "false";
        if (!$reverseorder) {
            $reverseorder = 'false';
        }

        if ($orderby == $order_value && $reverseorder === 'false') {
            $reverse_value = "true";
        }

        if ($this->form_method == "POST") {
            //we have to construct this url
            //specially.
            $form_name = $this->get_form_name();

            $url = "javascript: ";
            //set the offset correctly
            $url .= "document.".$form_name.".".$this->_offsetVar.".value='".$this->offset()."';";
            //set the orderby correctly.
            $url .= "document.".$form_name.".".$this->_orderbyVar.".value='".$order_value."';";
            //set the reverseorder
            $url .= "document.".$form_name.".".$this->_reverseorderVar.".value='".$reverse_value."';";

            $url .= "document.".$form_name.".submit();";
        } else {
            //handle the normal get.
            $url = $this->build_base_url();
            //Now add the orderby, reverseorder and offset vars
            $url .= $this->_offsetVar ."=0&";
            //set the orderbyvar
            $url .= $this->_orderbyVar ."=".$order_value."&";
            //set the reverseorder
            $url .= $this->_reverseorderVar ."=".$reverse_value."&";
            //set the search value
            $url .= $this->_search_valueVar ."=".$search_value;
        }

        return $url;
    }

    /**
     * This is the basic function for letting us
     * do a mapping between the column name in
     * the header, to the value found in the DB.
     *
     * NOTE: this function is meant to be overridden
     *       so that you can push whatever you want.
     *
     * @param array - $row_data - the entire data for the row
     * @param string - $col_name - the name of the column header
     *                             for this row to render.
     * @return  mixed - either a HTMLTag object, or raw text.
     */
    function build_column_item($row_data, $col_name) {
        $key = $this->_columns[$col_name]["data_name"];

        if ($row_data[$key] == '') {
            return "&nbsp;";
        } else {
            return $this->filter_column_string($row_data[$key]);
        }
    }


    /**
     * This does some magic filtering on the data
     * that we display in a column.  This helps
     * to prevent nast data that may have html
     * tags in it.
     *
     * @param string - the column data u want to filter
     * @return string the cleaned/filtered data
     */
    function filter_column_string($data) {
        return htmlspecialchars(trim($data));
    }
         

        /**
         * This function is used to make sure that the string we are
         * placing in a cell has been "cleaned"
         *
         * @param mixed - the cell object.  It can be a string.
         * @param string - the name of the column this object/string 
         *                 will live
         *
         * @return mixed - the cleaned string or object
         */
        function _clean_string($obj, $col_name){
                if (is_string($obj)) {
                        if ($this->_columns[$col_name]["maxtextlength"]) {
                                //looks like we need to make sure we
                                //truncate the string to a max length
                                if (strlen($obj) > $this->_columns[$col_name]["maxtextlength"]) {
                                        //we need to truncate it.
                                        $obj = substr($obj, 0, $this->_columns[$col_name]["maxtextlength"]);
                                        $obj .= "...";
                                }
                        }
                }
                return $obj;
        }

        /********************************/
        /*      SEARCH RELATED          */
        /********************************/

    /**
     * This method gets the array of
     * searchable header fields (columns)
     *
     * @return array
     */
    function _get_searchable_fields() {
        $fields = array();
        foreach($this->_columns as $name => $header) {
            if ($header["searchable"] == TRUE) {
                $fields[$name] = $header["data_name"];
            }
        }
        return $fields;
    }

    /**
     * This builds the simple search modifier
     * select box.
     *
     * @return INPUTtag object.
     */
    function _build_simple_search_modifier() {

        $options = array();

        $modifier = $this->get_simple_search_modifier();

        if ($modifier & SEARCH_BEGINS_WITH) {
            $options["beginning with"] = "BEGINS";
        }
        if ($modifier & SEARCH_CONTAINS) {
            $options["containing"] = "CONTAINS";
        }
        if ($modifier & SEARCH_EXACT) {
            $options["matching"] = "EXACT";
        }
        if ($modifier & SEARCH_ENDS_WITH) {
            $options["ending with"] = "ENDS";
        }

        $selected = $this->simple_search_modifier_value();
        //make the default Begins with
        if (!$selected) {
            $selected = "BEGINS";
        }

        return form_select($this->_simple_search_modifierVar, $options, $selected);
    }

        /**
     * This function is used to make safe
     * any query string value that is used
     *
     * @param string
     * @return string
     */
    function search_value_filter( $value ) {
        return stripslashes( trim($value) );
    }
}
?>
MailToCvsAdmin">MailToCvsAdmin	ViewVC Help
Powered by ViewVC 1.1.26