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	<?php
2
3	/**
4	* This file contains the Base DataListSource
5	* class which abstracts the data fetching/sorting
6	* from the DataList.
7	*
8	*
9	* $Id: DataListSource.inc,v 1.11 2004/01/28 18:49:54 hemna Exp $
10	*
11	* @author Walter A. Boring IV <waboring@buildabetterweb.com>
12	* @package phpHtmlLib
13	*/
14
15
16
17	/**
18	*
19	* This is the base class for managing data for
20	* the DataList class. This abstracts away the
21	* underlying data layer from the DataList, so
22	* the data can come from multiple sources.
23	* Most of the time the data will come from a
24	* data base such as Mysql or Oracle. This
25	* 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	* @package phpHtmlLib
30	*/
31	class DataListSource {
32
33	/**
34	* The column descriptions
35	* for the data we are working on
36	*
37	* @var array
38	*/
39	var $_columns = array();
40
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	/**
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	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	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	}
395
396	/**
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	$this->_query_params["limit"] = $limit;
404	}
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	}
490	?>
MailToCvsAdmin">MailToCvsAdmin	ViewVC Help
Powered by ViewVC 1.1.26