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 |
?> |