widgets/data_list/DataListSource.inc

<?php

/**
 * This file contains the Base DataListSource
 * class which abstracts the data fetching/sorting
 * from the DataList.
 *
 *
 * $Id: DataListSource.inc,v 1.11 2004/01/28 18:49:54 hemna Exp $
 *
 * @author Walter A. Boring IV <waboring@buildabetterweb.com>
 * @package phpHtmlLib
 */


/**
 *
 *  This is the base class for managing data for
 * the DataList class.  This abstracts away the
 * underlying data layer from the DataList, so
 * the data can come from multiple sources.
 * Most of the time the data will come from a
 * data base such as Mysql or Oracle.  This
 * abstraction enables the data to also come from
 * a tab delimited file, xml, php array
 *
 * @author Walter A. Boring IV <waboring@buildabetterweb.com>
 * @package phpHtmlLib
 */
class DataListSource {

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

    /**
     * This is the message displayed when no data
     * was retrieved from the database
     */
    var $_not_found_message = "No data was found";


    /**
     * This holds various parameters relating
     * to the query of the data
     *
     */
    var $_query_params = array("num_total_rows" => 0,
                               "offset" => 0,
                               "limit" => -1,
                               "orderby" => '',
                               "secondaryorderby" => array(),
                               "reverseorder" => '',
                               "searchby" => '',
                               "searchvalue" => '',
                               "searchmodifier" => '',
                               "searchtype" => 'simple');

    /**
     * Holds the index into the array of data
     * so we can keep track of where we are
     * when we are walking the array
     * (only usefull for non DB children)
     *
     */
    var $_data_index = 0;

    /**
     * A placeholder for data that is read/built
     * and stored locally.  Not all data sources
     * have to use this.
     * Each entry in the array corresponds to 1 row
     * of data.
     */
    var $_data = array();

    /**
     *
     * The constructor
     */
    function DataListSource() {

    }

    /**
     * The main external API methods
     * that are used by the DataList
     * Class
     *
     */

    /**
     * Add a column of data to manage
     *
     * @param string - the title of the column
     * @param string - the data value name
     * @param boolean - is the column sortable?
     *                  default: FALSE
     * @param boolean - is the column searchable
     *                  default: FALSE
     * @param string - the sort order (ASC, DESC)
     *                 default: ASC
     */
    function add_column( $title, $data_name, $sortable=FALSE,
                          $searchable=FALSE, $sortorder="ASC") {
        $col = array();
        $col["data_name"] = $data_name;
        $col["sortable"] = $sortable;
        $col["searchable"] = $searchable;
        $col["sortorder"] = $sortorder;
        $col["reverseorder"] = false;

        $this->_columns[$title] = $col;
    }


    /**
     * The main Query function.
     * This function is responsible for doing
     * any data prefetching from a db,file
     * and doing any sorting and searching
     * on it depending on the values passed
     * in from the DataList object
     *
     * @param int - the offset into the data set
     * @param int - the # of rows to get
     * @param string - the column to order the data by
     * @param string - order in asc or reverse?
     * @param string - the column in the dataset
     *                 to search by
     * @param string - the value to look for
     * @param string - the simple search modifier.
     *
     */
    function query($offset, $limit, $orderby, $reverseorder,
                   $searchby, $searchby_value,
                   $simplesearch_modifier, $search_type ) {
        $this->set_offset($offset);
        $this->set_limit($limit);
        $this->set_orderby($orderby);
        $this->set_reverseorder($reverseorder);
        $this->set_searchby($searchby);
        $this->set_searchby_value($searchby_value);
        $this->set_simplesearch_modifier( $simplesearch_modifier );
        $this->set_search_type( $search_type );

        //now call child methods

        //do any pre query setup
        //This depends on the source of the data
        //but an example would be to build a
        //sql query string if the source is a database
        //or to validate/open a file from disk if the
        //source is a file.
        //or to do any checks on a memory cache
        //if the data source is a sysvshm segment.
        $this->do_prequery();

        //do the actual data fetching/sorting
        return $this->do_query();
    }

    /**
     * This function gets the next data row
     * from the query()
     *
     * @return array()
     */
    function get_next_data_row() {
       user_error("DataListSource::get_next_data_row() - Child must override");
    }

    /**
     * This is called by the DataList object to allow
     * us a chance to run the next row through a filter
     *
     * @param array - the row to run through the filter
     * @return boolean - TRUE = allow the row. FALSE = drop it.
     */
    function row_filter(&$row_data) {
        return TRUE;
    }


    /**
     * This is a method that should be defined by the
     * child class to do any pre-query type of things.
     * Such as building a sql query string for a DB,
     * or checking to make sure the file on disk exists
     * if the source is a file on disk.
     *
     */
    function do_prequery() {
        user_error("DataListSource::do_prequery() - Child must override");
    }


    /**
     * This is the function that does the data fetching,
     * and sorting if needed.
     * If the source is a sql database, this is where the
     * query gets called.  This function doesn't actually read the
     * data from the DB yet.  That is what get_next_data_row()
     * does.
     *
     * @return boolean - the query passed/failed.
     */
    function do_query() {
        user_error("DataListSource::do_query() - Child must override");
        return false;
    }

    /**
     * A generic method API that can be used at the bottom
     * half of the do_query() method to sort data that is
     * stored locally.  This is only needed when the source
     * is a non database.
     *
     * It should operate on the $this->_data array
     */
    function sort() {
    }


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

    /**
     * This function is used to get the
     * message displayed when no data is found
     *
     * @return string
     */
    function get_not_found_message() {
        return $this->_not_found_message;
    }

    /**
     * This returns the total number of rows
     * in our entire data set
     *
     * @return int
     */
    function get_total_rows() {
        return $this->_query_params["num_total_rows"];
    }

    /**
     * This is used to set the total # of
     * rows we have in our data set
     *
     * @param int
     */
    function set_total_rows($num) {
        $this->_query_params["num_total_rows"] = $num;
    }


    /**
     * This sets the offset value
     * and resets the index into the data
     * array (in non DB children)
     *
     * @param int offset
     */
    function set_offset($offset) {
        $this->_query_params["offset"] = $offset;
        $this->_data_index = $offset;
    }

    /**
     * This function returns the value of the
     * offset
     *
     * @return int
     */
    function get_offset() {
        return $this->_query_params["offset"];
    }

    /**
     * This sets the orderby column name.
     * This corresponds to the column
     * that wants to be sorted/ordered, but
     * not the actual direction (asc, desc)
     *
     * @param int offset
     */
    function set_orderby($orderby) {
        $this->_query_params["orderby"] = $orderby;
    }

    /**
     * This function returns the value of the
     * orderby
     *
     * @return int
     */
    function get_orderby() {
        return $this->_query_params["orderby"];
    }

    /**
     * This sets the flag that tells us the
     * direction in which to order the orderby
     * column.
     *
     * @param int offset
     */
    function set_reverseorder($order) {
        $this->_query_params["reverseorder"] = $order;
    }

    /**
     * This function returns the value of the
     * reverseorder
     *
     * @return int
     */
    function get_reverseorder() {
        return $this->_query_params["reverseorder"];
    }

    /**
     * This sets the column that we want to search
     * from.
     *
     * @param int offset
     */
    function set_searchby($search_col) {
        $this->_query_params["searchby"] = $search_col;
    }

    /**
     * This function returns the value of the
     * searchby
     *
     * @return int
     */
    function get_searchby() {
        return $this->_query_params["searchby"];
    }

    /**
     * This sets the data that we want to search
     * for.
     *
     * @param int offset
     */
    function set_searchby_value($search_value) {
        $this->_query_params["searchvalue"] = $search_value;
    }

    /**
     * This function returns the value of the
     * search value
     *
     * @return int
     */
    function get_searchby_value() {
        return $this->_query_params["searchvalue"];
    }

    /**
     * This sets the simple search modifier
     *
     *
     * @param int offset
     */
    function set_simplesearch_modifier($search_modifier) {
        $this->_query_params["searchmodifier"] = $search_modifier;
    }

    /**
     * This function returns the value of the
     * search value
     *
     * @return int
     */
    function get_simplesearch_modifier() {
        return $this->_query_params["searchmodifier"];
    }

    /**
     * This function is used to set
     * the limit value, which limits
     * the # of rows of data to allow
     * to return
     */
    function set_limit( $limit ) {
        $this->_query_params["limit"] = $limit;
    }

    /**
     * This function gets the current
     * value of the limit value
     *
     * @return int
     */
    function get_limit() {
        return $this->_query_params["limit"];
    }


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

    /**
     * this function returns the current search type
     * for the DataList query
     *
     * @return string
     */
    function get_search_type() {
        return $this->_query_params["searchtype"];
    }

    /**
     * This method is used to set a secondary
     * list of columns to order/sort by.
     *
     * @param mixed - n numbers of column names
     *                to order by
     */
    function set_secondary_orderby() {
        $this->_query_params["secondaryorderby"] = func_get_args();
    }

    /**
     * This gets the list of secondary order by
     * columns.
     *
     * @return array
     */
    function get_secondary_orderby() {
        return $this->_query_params["secondaryorderby"];
    }

    /**
     * This function returns the
     * data_index value and increments it
     *
     * @return int
     */
    function get_data_index() {
        $this->_data_index++;
        return $this->_data_index-1;
    }

    /**
     * This function determines if the column
     * associated w/ a data_name is sortable
     * or not
     *
     * @param string - the data_name filed in the
     *                 _columns array to look for
     * @return boolean - is that column sortable?
     */
    function _is_column_sortable( $data_name ) {
        foreach( $this->_columns as $name => $data ) {
            if ($data["data_name"] == $data_name &&
                ($data["sortable"] == SORTABLE ||
                 $data["sortable"] == SORTABLE_ICASE ||
                 $data["sortable"] == SORTABLE_NUMERIC)) {
                return TRUE;
            }
        }
        return FALSE;
    }
}
?>
1	jonen	1.1	<?php
2
3			/**
4			* This file contains the Base DataListSource
5			* class which abstracts the data fetching/sorting
6	jonen	1.4	* from the DataList.
7	jonen	1.1	*
8			*
9	jonen	1.4	* $Id: DataListSource.inc,v 1.11 2004/01/28 18:49:54 hemna Exp $
10	jonen	1.1	*
11			* @author Walter A. Boring IV <waboring@buildabetterweb.com>
12			* @package phpHtmlLib
13			*/
14
15
16
17			/**
18	jonen	1.4	*
19	jonen	1.1	* This is the base class for managing data for
20			* the DataList class. This abstracts away the
21	jonen	1.4	* underlying data layer from the DataList, so
22			* the data can come from multiple sources.
23	jonen	1.1	* Most of the time the data will come from a
24	jonen	1.4	* data base such as Mysql or Oracle. This
25	jonen	1.1	* abstraction enables the data to also come from
26			* a tab delimited file, xml, php array
27			*
28			* @author Walter A. Boring IV <waboring@buildabetterweb.com>
29	jonen	1.4	* @package phpHtmlLib
30	jonen	1.1	*/
31			class DataListSource {
32
33	jonen	1.4	/**
34			* The column descriptions
35			* for the data we are working on
36			*
37			* @var array
38			*/
39			var $_columns = array();
40	jonen	1.1
41			/**
42			* This is the message displayed when no data
43			* was retrieved from the database
44			*/
45			var $_not_found_message = "No data was found";
46
47
48	jonen	1.4	/**
49			* This holds various parameters relating
50			* to the query of the data
51			*
52			*/
53			var $_query_params = array("num_total_rows" => 0,
54			"offset" => 0,
55			"limit" => -1,
56			"orderby" => '',
57			"secondaryorderby" => array(),
58			"reverseorder" => '',
59			"searchby" => '',
60			"searchvalue" => '',
61			"searchmodifier" => '',
62			"searchtype" => 'simple');
63
64			/**
65			* Holds the index into the array of data
66			* so we can keep track of where we are
67			* when we are walking the array
68			* (only usefull for non DB children)
69			*
70			*/
71			var $_data_index = 0;
72
73			/**
74			* A placeholder for data that is read/built
75			* and stored locally. Not all data sources
76			* have to use this.
77			* Each entry in the array corresponds to 1 row
78			* of data.
79			*/
80			var $_data = array();
81
82			/**
83			*
84			* The constructor
85			*/
86			function DataListSource() {
87
88			}
89
90			/**
91			* The main external API methods
92			* that are used by the DataList
93			* Class
94			*
95			*/
96
97			/**
98			* Add a column of data to manage
99			*
100			* @param string - the title of the column
101			* @param string - the data value name
102			* @param boolean - is the column sortable?
103			* default: FALSE
104			* @param boolean - is the column searchable
105			* default: FALSE
106			* @param string - the sort order (ASC, DESC)
107			* default: ASC
108			*/
109			function add_column( $title, $data_name, $sortable=FALSE,
110			$searchable=FALSE, $sortorder="ASC") {
111			$col = array();
112			$col["data_name"] = $data_name;
113			$col["sortable"] = $sortable;
114			$col["searchable"] = $searchable;
115			$col["sortorder"] = $sortorder;
116			$col["reverseorder"] = false;
117
118			$this->_columns[$title] = $col;
119			}
120
121
122			/**
123			* The main Query function.
124			* This function is responsible for doing
125			* any data prefetching from a db,file
126			* and doing any sorting and searching
127			* on it depending on the values passed
128			* in from the DataList object
129			*
130			* @param int - the offset into the data set
131			* @param int - the # of rows to get
132			* @param string - the column to order the data by
133			* @param string - order in asc or reverse?
134			* @param string - the column in the dataset
135			* to search by
136			* @param string - the value to look for
137			* @param string - the simple search modifier.
138			*
139			*/
140			function query($offset, $limit, $orderby, $reverseorder,
141			$searchby, $searchby_value,
142			$simplesearch_modifier, $search_type ) {
143			$this->set_offset($offset);
144			$this->set_limit($limit);
145			$this->set_orderby($orderby);
146			$this->set_reverseorder($reverseorder);
147			$this->set_searchby($searchby);
148			$this->set_searchby_value($searchby_value);
149			$this->set_simplesearch_modifier( $simplesearch_modifier );
150			$this->set_search_type( $search_type );
151
152			//now call child methods
153
154			//do any pre query setup
155			//This depends on the source of the data
156			//but an example would be to build a
157			//sql query string if the source is a database
158			//or to validate/open a file from disk if the
159			//source is a file.
160			//or to do any checks on a memory cache
161			//if the data source is a sysvshm segment.
162			$this->do_prequery();
163
164			//do the actual data fetching/sorting
165			return $this->do_query();
166			}
167
168			/**
169			* This function gets the next data row
170			* from the query()
171			*
172			* @return array()
173			*/
174			function get_next_data_row() {
175			user_error("DataListSource::get_next_data_row() - Child must override");
176			}
177
178			/**
179			* This is called by the DataList object to allow
180			* us a chance to run the next row through a filter
181			*
182			* @param array - the row to run through the filter
183			* @return boolean - TRUE = allow the row. FALSE = drop it.
184			*/
185			function row_filter(&$row_data) {
186			return TRUE;
187			}
188
189
190			/**
191			* This is a method that should be defined by the
192			* child class to do any pre-query type of things.
193			* Such as building a sql query string for a DB,
194			* or checking to make sure the file on disk exists
195			* if the source is a file on disk.
196			*
197			*/
198			function do_prequery() {
199			user_error("DataListSource::do_prequery() - Child must override");
200			}
201
202
203			/**
204			* This is the function that does the data fetching,
205			* and sorting if needed.
206			* If the source is a sql database, this is where the
207			* query gets called. This function doesn't actually read the
208			* data from the DB yet. That is what get_next_data_row()
209			* does.
210			*
211			* @return boolean - the query passed/failed.
212			*/
213			function do_query() {
214			user_error("DataListSource::do_query() - Child must override");
215			return false;
216			}
217
218			/**
219			* A generic method API that can be used at the bottom
220			* half of the do_query() method to sort data that is
221			* stored locally. This is only needed when the source
222			* is a non database.
223			*
224			* It should operate on the $this->_data array
225			*/
226			function sort() {
227			}
228
229
230			/**
231			* This function is used to set the
232			* message displayed when no data is found
233			*
234			* @param string
235			*/
236	jonen	1.1	function set_not_found_message( $mesg ) {
237			$this->_not_found_message = $mesg;
238			}
239
240			/**
241			* This function is used to get the
242			* message displayed when no data is found
243			*
244			* @return string
245			*/
246			function get_not_found_message() {
247	jonen	1.4	return $this->_not_found_message;
248			}
249
250			/**
251			* This returns the total number of rows
252			* in our entire data set
253			*
254			* @return int
255			*/
256			function get_total_rows() {
257			return $this->_query_params["num_total_rows"];
258			}
259
260			/**
261			* This is used to set the total # of
262			* rows we have in our data set
263			*
264			* @param int
265			*/
266			function set_total_rows($num) {
267			$this->_query_params["num_total_rows"] = $num;
268			}
269
270
271			/**
272			* This sets the offset value
273			* and resets the index into the data
274			* array (in non DB children)
275			*
276			* @param int offset
277			*/
278			function set_offset($offset) {
279			$this->_query_params["offset"] = $offset;
280			$this->_data_index = $offset;
281			}
282
283			/**
284			* This function returns the value of the
285			* offset
286			*
287			* @return int
288			*/
289			function get_offset() {
290			return $this->_query_params["offset"];
291			}
292
293			/**
294			* This sets the orderby column name.
295			* This corresponds to the column
296			* that wants to be sorted/ordered, but
297			* not the actual direction (asc, desc)
298			*
299			* @param int offset
300			*/
301			function set_orderby($orderby) {
302			$this->_query_params["orderby"] = $orderby;
303			}
304
305			/**
306			* This function returns the value of the
307			* orderby
308			*
309			* @return int
310			*/
311			function get_orderby() {
312			return $this->_query_params["orderby"];
313			}
314
315			/**
316			* This sets the flag that tells us the
317			* direction in which to order the orderby
318			* column.
319			*
320			* @param int offset
321			*/
322			function set_reverseorder($order) {
323			$this->_query_params["reverseorder"] = $order;
324			}
325
326			/**
327			* This function returns the value of the
328			* reverseorder
329			*
330			* @return int
331			*/
332			function get_reverseorder() {
333			return $this->_query_params["reverseorder"];
334			}
335
336			/**
337			* This sets the column that we want to search
338			* from.
339			*
340			* @param int offset
341			*/
342			function set_searchby($search_col) {
343			$this->_query_params["searchby"] = $search_col;
344			}
345
346			/**
347			* This function returns the value of the
348			* searchby
349			*
350			* @return int
351			*/
352			function get_searchby() {
353			return $this->_query_params["searchby"];
354			}
355
356			/**
357			* This sets the data that we want to search
358			* for.
359			*
360			* @param int offset
361			*/
362			function set_searchby_value($search_value) {
363			$this->_query_params["searchvalue"] = $search_value;
364			}
365
366			/**
367			* This function returns the value of the
368			* search value
369			*
370			* @return int
371			*/
372			function get_searchby_value() {
373			return $this->_query_params["searchvalue"];
374			}
375
376			/**
377			* This sets the simple search modifier
378			*
379			*
380			* @param int offset
381			*/
382			function set_simplesearch_modifier($search_modifier) {
383			$this->_query_params["searchmodifier"] = $search_modifier;
384			}
385
386			/**
387			* This function returns the value of the
388			* search value
389			*
390			* @return int
391			*/
392			function get_simplesearch_modifier() {
393			return $this->_query_params["searchmodifier"];
394	jonen	1.1	}
395
396	jonen	1.4	/**
397			* This function is used to set
398			* the limit value, which limits
399			* the # of rows of data to allow
400			* to return
401			*/
402			function set_limit( $limit ) {
403	jonen	1.1	$this->_query_params["limit"] = $limit;
404	jonen	1.4	}
405
406			/**
407			* This function gets the current
408			* value of the limit value
409			*
410			* @return int
411			*/
412			function get_limit() {
413			return $this->_query_params["limit"];
414			}
415
416
417			/**
418			* This function sets the search type
419			* (simple or advanced)
420			*
421			* @param string
422			*/
423			function set_search_type( $search_type ) {
424			$this->_query_params["searchtype"] = $search_type;
425			}
426
427			/**
428			* this function returns the current search type
429			* for the DataList query
430			*
431			* @return string
432			*/
433			function get_search_type() {
434			return $this->_query_params["searchtype"];
435			}
436
437			/**
438			* This method is used to set a secondary
439			* list of columns to order/sort by.
440			*
441			* @param mixed - n numbers of column names
442			* to order by
443			*/
444			function set_secondary_orderby() {
445			$this->_query_params["secondaryorderby"] = func_get_args();
446			}
447
448			/**
449			* This gets the list of secondary order by
450			* columns.
451			*
452			* @return array
453			*/
454			function get_secondary_orderby() {
455			return $this->_query_params["secondaryorderby"];
456			}
457
458			/**
459			* This function returns the
460			* data_index value and increments it
461			*
462			* @return int
463			*/
464			function get_data_index() {
465			$this->_data_index++;
466			return $this->_data_index-1;
467			}
468
469			/**
470			* This function determines if the column
471			* associated w/ a data_name is sortable
472			* or not
473			*
474			* @param string - the data_name filed in the
475			* _columns array to look for
476			* @return boolean - is that column sortable?
477			*/
478			function _is_column_sortable( $data_name ) {
479			foreach( $this->_columns as $name => $data ) {
480			if ($data["data_name"] == $data_name &&
481			($data["sortable"] == SORTABLE \|\|
482			$data["sortable"] == SORTABLE_ICASE \|\|
483			$data["sortable"] == SORTABLE_NUMERIC)) {
484			return TRUE;
485			}
486			}
487			return FALSE;
488			}
489	jonen	1.1	}
490			?>
MailToCvsAdmin">MailToCvsAdmin	ViewVC Help
Powered by ViewVC 1.1.26