From 0ee2a6333a8b987fd85c6bd6018fdd95906277ac Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 18:55:38 +0300 Subject: [ci skip] Update the Table library docs --- user_guide_src/source/libraries/table.rst | 272 ++++++++++++++++-------------- 1 file changed, 143 insertions(+), 129 deletions(-) diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index 6a808abc2..25927800e 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -5,48 +5,60 @@ HTML Table Class The Table Class provides functions that enable you to auto-generate HTML tables from arrays or database result sets. +.. content:: + :local: + +.. raw:: html + +
+ +********************* +Using the Table Class +********************* + Initializing the Class ====================== Like most other classes in CodeIgniter, the Table class is initialized -in your controller using the $this->load->library function:: +in your controller using the ``$this->load->library()`` method:: $this->load->library('table'); -Once loaded, the Table library object will be available using: -$this->table +Once loaded, the Table library object will be available using:: + + $this->table Examples ======== Here is an example showing how you can create a table from a multi-dimensional array. Note that the first array index will become the -table heading (or you can set your own headings using the set_heading() -function described in the function reference below). +table heading (or you can set your own headings using the ``set_heading()`` +method described in the function reference below). :: $this->load->library('table'); $data = array( - array('Name', 'Color', 'Size'), - array('Fred', 'Blue', 'Small'), - array('Mary', 'Red', 'Large'), - array('John', 'Green', 'Medium') - ); + array('Name', 'Color', 'Size'), + array('Fred', 'Blue', 'Small'), + array('Mary', 'Red', 'Large'), + array('John', 'Green', 'Medium') + ); echo $this->table->generate($data); Here is an example of a table created from a database query result. The table class will automatically generate the headings based on the table -names (or you can set your own headings using the set_heading() -function described in the function reference below). +names (or you can set your own headings using the ``set_heading()`` +method described in the class reference below). :: $this->load->library('table'); - $query = $this->db->query("SELECT * FROM my_table"); + $query = $this->db->query('SELECT * FROM my_table'); echo $this->table->generate($query); @@ -82,28 +94,28 @@ Changing the Look of Your Table The Table Class permits you to set a table template with which you can specify the design of your layout. Here is the template prototype:: - $tmpl = array ( - 'table_open' => '', + $template = array( + 'table_open' => '
', - 'heading_row_start' => '', - 'heading_row_end' => '', - 'heading_cell_start' => '', + 'heading_row_start' => '', + 'heading_row_end' => '', + 'heading_cell_start' => '', - 'row_start' => '', - 'row_end' => '', - 'cell_start' => '', + 'row_start' => '', + 'row_end' => '', + 'cell_start' => '', - 'row_alt_start' => '', - 'row_alt_end' => '', - 'cell_alt_start' => '', + 'row_alt_start' => '', + 'row_alt_end' => '', + 'cell_alt_start' => '', - 'table_close' => '
', - 'heading_cell_end' => '
', + 'heading_cell_end' => '
', - 'cell_end' => '
', + 'cell_end' => '
', - 'cell_alt_end' => '
', + 'cell_alt_end' => '
' - ); + 'table_close' => '' + ); - $this->table->set_template($tmpl); + $this->table->set_template($template); .. note:: You'll notice there are two sets of "row" blocks in the template. These permit you to create alternating row colors or design @@ -113,157 +125,159 @@ You are NOT required to submit a complete template. If you only need to change parts of the layout you can simply submit those elements. In this example, only the table opening tag is being changed:: - $tmpl = array ( 'table_open' => '' ); + $template = array( + 'table_open' => '
' + ); - $this->table->set_template($tmpl); + $this->table->set_template($template); You can also set defaults for these in a config file. -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->table->generate() -======================== +.. class:: CI_Table -Returns a string containing the generated table. Accepts an optional -parameter which can be an array or a database result object. + .. attribute:: $function = FALSE -$this->table->set_caption() -============================ + Allows you to specify a native PHP function or a valid function array object to be applied to all cell data. + :: -Permits you to add a caption to the table. + $this->load->library('table'); -:: + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', 'Blue', 'Small'); - $this->table->set_caption('Colors'); + $this->table->function = 'htmlspecialchars'; + echo $this->table->generate(); -$this->table->set_heading() -============================ + In the above example, all cell data would be ran through PHP's :php:func:`htmlspecialchars()` function, resulting in:: -Permits you to set the table heading. You can submit an array or -discrete params:: + - $this->table->set_heading('Name', 'Color', 'Size'); + .. method:: generate([$table_data = NULL]) -:: + :param mixed $table_data: data to populate the table rows with + :returns: string - $this->table->set_heading(array('Name', 'Color', 'Size')); + Returns a string containing the generated table. Accepts an optional parameter which can be an array or a database result object. -$this->table->add_row() -======================== + .. method:: set_caption($caption) -Permits you to add a row to your table. You can submit an array or -discrete params:: + :param string $caption: table caption + :returns: void - $this->table->add_row('Blue', 'Red', 'Green'); + Permits you to add a caption to the table. + :: -:: + $this->table->set_caption('Colors'); - $this->table->add_row(array('Blue', 'Red', 'Green')); + .. method:: set_heading([$args = array()[, ...]]) -If you would like to set an individual cell's tag attributes, you can -use an associative array for that cell. The associative key 'data' -defines the cell's data. Any other key => val pairs are added as -key='val' attributes to the tag:: + :param mixed $args: an array or multiple strings containing the table column titles + :returns: void - $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); - $this->table->add_row($cell, 'Red', 'Green'); + Permits you to set the table heading. You can submit an array or discrete params:: - // generates - // + $this->table->set_heading('Name', 'Color', 'Size'); -$this->table->make_columns() -============================= + $this->table->set_heading(array('Name', 'Color', 'Size')); -This function takes a one-dimensional array as input and creates a -multi-dimensional array with a depth equal to the number of columns -desired. This allows a single array with many elements to be displayed -in a table that has a fixed column count. Consider this example:: + .. method:: add_row([$args = array()[, ...]]) - $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); + :param mixed $args: an array or multiple strings containing the row values + :returns: void - $new_list = $this->table->make_columns($list, 3); + Permits you to add a row to your table. You can submit an array or discrete params:: - $this->table->generate($new_list); + $this->table->add_row('Blue', 'Red', 'Green'); - // Generates a table with this prototype + $this->table->add_row(array('Blue', 'Red', 'Green')); -
Fred<strong>Blue</strong>SmallBlueRedGreen
- - - - - - - - -
onetwothree
fourfivesix
seveneightnine
teneleventwelve
+ If you would like to set an individual cell's tag attributes, you can use an associative array for that cell. + The associative key **data** defines the cell's data. Any other key => val pairs are added as key='val' attributes to the tag:: -$this->table->set_template() -============================= + $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); + $this->table->add_row($cell, 'Red', 'Green'); -Permits you to set your template. You can submit a full or partial -template. + // generates + // BlueRedGreen -:: + .. method:: make_columns([$array = array()[, $col_limit = 0]]) - $tmpl = array ( 'table_open' => '' ); + :param array $array: an array containing multiple rows' data + :param int $col_limit: count of columns in the table + :returns: array - $this->table->set_template($tmpl); + This method takes a one-dimensional array as input and creates a multi-dimensional array with a depth equal to the number of columns desired. + This allows a single array with many elements to be displayed in a table that has a fixed column count. Consider this example:: -$this->table->set_empty() -========================== + $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); -Let's you set a default value for use in any table cells that are empty. -You might, for example, set a non-breaking space:: + $new_list = $this->table->make_columns($list, 3); - $this->table->set_empty(" "); + $this->table->generate($new_list); -$this->table->clear() -===================== + // Generates a table with this prototype -Lets you clear the table heading and row data. If you need to show -multiple tables with different data you should to call this function -after each table has been generated to empty the previous table -information. Example:: +
+ + + + + + + + +
onetwothree
fourfivesix
seveneightnine
teneleventwelve
- $this->load->library('table'); - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', 'Blue', 'Small'); - $this->table->add_row('Mary', 'Red', 'Large'); - $this->table->add_row('John', 'Green', 'Medium'); + .. method:: set_template($template) - echo $this->table->generate(); + :param array $template: associative array containing template values + :returns: bool - $this->table->clear(); + Permits you to set your template. You can submit a full or partial template. + :: - $this->table->set_heading('Name', 'Day', 'Delivery'); - $this->table->add_row('Fred', 'Wednesday', 'Express'); - $this->table->add_row('Mary', 'Monday', 'Air'); - $this->table->add_row('John', 'Saturday', 'Overnight'); + $template = array( + 'table_open' => '' + ); - echo $this->table->generate(); + $this->table->set_template($template); -$this->table->function -====================== + .. method:: set_empty($value) -Allows you to specify a native PHP function or a valid function array -object to be applied to all cell data. + :param mixed $value: value to put in empty cells + :returns: void -:: + Lets you set a default value for use in any table cells that are empty. + You might, for example, set a non-breaking space:: - $this->load->library('table'); + $this->table->set_empty(" "); - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', 'Blue', 'Small'); + .. method:: clear() - $this->table->function = 'htmlspecialchars'; - echo $this->table->generate(); + :returns: void + + Lets you clear the table heading and row data. If you need to show multiple tables with different data you should to call this method + after each table has been generated to clear the previous table information. Example:: + + $this->load->library('table'); + + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', 'Blue', 'Small'); + $this->table->add_row('Mary', 'Red', 'Large'); + $this->table->add_row('John', 'Green', 'Medium'); + + echo $this->table->generate(); -In the above example, all cell data would be ran through PHP's -htmlspecialchars() function, resulting in:: + $this->table->clear(); - + $this->table->set_heading('Name', 'Day', 'Delivery'); + $this->table->add_row('Fred', 'Wednesday', 'Express'); + $this->table->add_row('Mary', 'Monday', 'Air'); + $this->table->add_row('John', 'Saturday', 'Overnight'); + echo $this->table->generate(); -- cgit v1.2.3-24-g4f1b
Fred<strong>Blue</strong>Small