Joomla Platform  13.1
Documentation des API du framework Joomla Platform
 Tout Classes Espaces de nommage Fichiers Fonctions Variables Pages
grid.php
Aller à la documentation de ce fichier.
1 <?php
2 /**
3  * JGrid class to dynamically generate HTML tables
4  *
5  * @package Joomla.Platform
6  * @subpackage Grid
7  *
8  * @copyright Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
9  * @license GNU General Public License version 2 or later; see LICENSE
10  */
11 
12 defined('JPATH_PLATFORM') or die;
13 
14 /**
15  * JGrid class to dynamically generate HTML tables
16  *
17  * @package Joomla.Platform
18  * @subpackage Grid
19  * @since 11.3
20  */
21 class JGrid
22 {
23  /**
24  * Array of columns
25  * @var array
26  * @since 11.3
27  */
28  protected $columns = array();
29 
30  /**
31  * Current active row
32  * @var int
33  * @since 11.3
34  */
35  protected $activeRow = 0;
36 
37  /**
38  * Rows of the table (including header and footer rows)
39  * @var array
40  * @since 11.3
41  */
42  protected $rows = array();
43 
44  /**
45  * Header and Footer row-IDs
46  * @var array
47  * @since 11.3
48  */
49  protected $specialRows = array('header' => array(), 'footer' => array());
50 
51  /**
52  * Associative array of attributes for the table-tag
53  * @var array
54  * @since 11.3
55  */
56  protected $options;
57 
58  /**
59  * Constructor for a JGrid object
60  *
61  * @param array $options Associative array of attributes for the table-tag
62  *
63  * @since 11.3
64  */
65  public function __construct($options = array())
66  {
67  $this->setTableOptions($options, true);
68  }
69 
70  /**
71  * Magic function to render this object as a table.
72  *
73  * @return string
74  *
75  * @since 11.3
76  */
77  public function __toString()
78  {
79  return $this->toString();
80  }
81 
82  /**
83  * Method to set the attributes for a table-tag
84  *
85  * @param array $options Associative array of attributes for the table-tag
86  * @param bool $replace Replace possibly existing attributes
87  *
88  * @return JGrid This object for chaining
89  *
90  * @since 11.3
91  */
92  public function setTableOptions($options = array(), $replace = false)
93  {
94  if ($replace)
95  {
96  $this->options = $options;
97  }
98  else
99  {
100  $this->options = array_merge($this->options, $options);
101  }
102  return $this;
103  }
104 
105  /**
106  * Get the Attributes of the current table
107  *
108  * @return array Associative array of attributes
109  *
110  * @since 11.3
111  */
112  public function getTableOptions()
113  {
114  return $this->options;
115  }
116 
117  /**
118  * Add new column name to process
119  *
120  * @param string $name Internal column name
121  *
122  * @return JGrid This object for chaining
123  *
124  * @since 11.3
125  */
126  public function addColumn($name)
127  {
128  $this->columns[] = $name;
129 
130  return $this;
131  }
132 
133  /**
134  * Returns the list of internal columns
135  *
136  * @return array List of internal columns
137  *
138  * @since 11.3
139  */
140  public function getColumns()
141  {
142  return $this->columns;
143  }
144 
145  /**
146  * Delete column by name
147  *
148  * @param string $name Name of the column to be deleted
149  *
150  * @return JGrid This object for chaining
151  *
152  * @since 11.3
153  */
154  public function deleteColumn($name)
155  {
156  $index = array_search($name, $this->columns);
157  if ($index !== false)
158  {
159  unset($this->columns[$index]);
160  $this->columns = array_values($this->columns);
161  }
162 
163  return $this;
164  }
165 
166  /**
167  * Method to set a whole range of columns at once
168  * This can be used to re-order the columns, too
169  *
170  * @param array $columns List of internal column names
171  *
172  * @return JGrid This object for chaining
173  *
174  * @since 11.3
175  */
176  public function setColumns($columns)
177  {
178  $this->columns = array_values($columns);
179 
180  return $this;
181  }
182 
183  /**
184  * Adds a row to the table and sets the currently
185  * active row to the new row
186  *
187  * @param array $options Associative array of attributes for the row
188  * @param int $special 1 for a new row in the header, 2 for a new row in the footer
189  *
190  * @return JGrid This object for chaining
191  *
192  * @since 11.3
193  */
194  public function addRow($options = array(), $special = false)
195  {
196  $this->rows[]['_row'] = $options;
197  $this->activeRow = count($this->rows) - 1;
198  if ($special)
199  {
200  if ($special === 1)
201  {
202  $this->specialRows['header'][] = $this->activeRow;
203  }
204  else
205  {
206  $this->specialRows['footer'][] = $this->activeRow;
207  }
208  }
209 
210  return $this;
211  }
212 
213  /**
214  * Method to get the attributes of the currently active row
215  *
216  * @return array Associative array of attributes
217  *
218  * @since 11.3
219  */
220  public function getRowOptions()
221  {
222  return $this->rows[$this->activeRow]['_row'];
223  }
224 
225  /**
226  * Method to set the attributes of the currently active row
227  *
228  * @param array $options Associative array of attributes
229  *
230  * @return JGrid This object for chaining
231  *
232  * @since 11.3
233  */
234  public function setRowOptions($options)
235  {
236  $this->rows[$this->activeRow]['_row'] = $options;
237 
238  return $this;
239  }
240 
241  /**
242  * Get the currently active row ID
243  *
244  * @return int ID of the currently active row
245  *
246  * @since 11.3
247  */
248  public function getActiveRow()
249  {
250  return $this->activeRow;
251  }
252 
253  /**
254  * Set the currently active row
255  *
256  * @param int $id ID of the row to be set to current
257  *
258  * @return JGrid This object for chaining
259  *
260  * @since 11.3
261  */
262  public function setActiveRow($id)
263  {
264  $this->activeRow = (int) $id;
265  return $this;
266  }
267 
268  /**
269  * Set cell content for a specific column for the
270  * currently active row
271  *
272  * @param string $name Name of the column
273  * @param string $content Content for the cell
274  * @param array $option Associative array of attributes for the td-element
275  * @param bool $replace If false, the content is appended to the current content of the cell
276  *
277  * @return JGrid This object for chaining
278  *
279  * @since 11.3
280  */
281  public function setRowCell($name, $content, $option = array(), $replace = true)
282  {
283  if ($replace || !isset($this->rows[$this->activeRow][$name]))
284  {
285  $cell = new stdClass;
286  $cell->options = $option;
287  $cell->content = $content;
288  $this->rows[$this->activeRow][$name] = $cell;
289  }
290  else
291  {
292  $this->rows[$this->activeRow][$name]->content .= $content;
293  $this->rows[$this->activeRow][$name]->options = $option;
294  }
295 
296  return $this;
297  }
298 
299  /**
300  * Get all data for a row
301  *
302  * @param int $id ID of the row to return
303  *
304  * @return array Array of columns of a table row
305  *
306  * @since 11.3
307  */
308  public function getRow($id = false)
309  {
310  if ($id === false)
311  {
312  $id = $this->activeRow;
313  }
314 
315  if (isset($this->rows[(int) $id]))
316  {
317  return $this->rows[(int) $id];
318  }
319  else
320  {
321  return false;
322  }
323  }
324 
325  /**
326  * Get the IDs of all rows in the table
327  *
328  * @param int $special false for the standard rows, 1 for the header rows, 2 for the footer rows
329  *
330  * @return array Array of IDs
331  *
332  * @since 11.3
333  */
334  public function getRows($special = false)
335  {
336  if ($special)
337  {
338  if ($special === 1)
339  {
340  return $this->specialRows['header'];
341  }
342  else
343  {
344  return $this->specialRows['footer'];
345  }
346  }
347  return array_diff(array_keys($this->rows), array_merge($this->specialRows['header'], $this->specialRows['footer']));
348  }
349 
350  /**
351  * Delete a row from the object
352  *
353  * @param int $id ID of the row to be deleted
354  *
355  * @return JGrid This object for chaining
356  *
357  * @since 11.3
358  */
359  public function deleteRow($id)
360  {
361  unset($this->rows[$id]);
362 
363  if (in_array($id, $this->specialRows['header']))
364  {
365  unset($this->specialRows['header'][array_search($id, $this->specialRows['header'])]);
366  }
367 
368  if (in_array($id, $this->specialRows['footer']))
369  {
370  unset($this->specialRows['footer'][array_search($id, $this->specialRows['footer'])]);
371  }
372 
373  if ($this->activeRow == $id)
374  {
375  end($this->rows);
376  $this->activeRow = key($this->rows);
377  }
378 
379  return $this;
380  }
381 
382  /**
383  * Render the HTML table
384  *
385  * @return string The rendered HTML table
386  *
387  * @since 11.3
388  */
389  public function toString()
390  {
391  $output = array();
392  $output[] = '<table' . $this->renderAttributes($this->getTableOptions()) . '>';
393 
394  if (count($this->specialRows['header']))
395  {
396  $output[] = $this->renderArea($this->specialRows['header'], 'thead', 'th');
397  }
398 
399  if (count($this->specialRows['footer']))
400  {
401  $output[] = $this->renderArea($this->specialRows['footer'], 'tfoot');
402  }
403 
404  $ids = array_diff(array_keys($this->rows), array_merge($this->specialRows['header'], $this->specialRows['footer']));
405  if (count($ids))
406  {
407  $output[] = $this->renderArea($ids);
408  }
409 
410  $output[] = '</table>';
411  return implode('', $output);
412  }
413 
414  /**
415  * Render an area of the table
416  *
417  * @param array $ids IDs of the rows to render
418  * @param string $area Name of the area to render. Valid: tbody, tfoot, thead
419  * @param string $cell Name of the cell to render. Valid: td, th
420  *
421  * @return string The rendered table area
422  *
423  * @since 11.3
424  */
425  protected function renderArea($ids, $area = 'tbody', $cell = 'td')
426  {
427  $output = array();
428  $output[] = '<' . $area . ">\n";
429  foreach ($ids as $id)
430  {
431  $output[] = "\t<tr" . $this->renderAttributes($this->rows[$id]['_row']) . ">\n";
432  foreach ($this->getColumns() as $name)
433  {
434  if (isset($this->rows[$id][$name]))
435  {
436  $column = $this->rows[$id][$name];
437  $output[] = "\t\t<" . $cell . $this->renderAttributes($column->options) . '>' . $column->content . '</' . $cell . ">\n";
438  }
439  }
440 
441  $output[] = "\t</tr>\n";
442  }
443  $output[] = '</' . $area . '>';
444 
445  return implode('', $output);
446  }
447 
448  /**
449  * Renders an HTML attribute from an associative array
450  *
451  * @param array $attributes Associative array of attributes
452  *
453  * @return string The HTML attribute string
454  *
455  * @since 11.3
456  */
457  protected function renderAttributes($attributes)
458  {
459  if (count((array) $attributes) == 0)
460  {
461  return '';
462  }
463  $return = array();
464  foreach ($attributes as $key => $option)
465  {
466  $return[] = $key . '="' . $option . '"';
467  }
468  return ' ' . implode(' ', $return);
469  }
470 }