From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/libraries/table.rst | 170 ++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 user_guide_src/source/libraries/table.rst (limited to 'user_guide_src/source/libraries/table.rst') diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst new file mode 100644 index 000000000..6ca6bc971 --- /dev/null +++ b/user_guide_src/source/libraries/table.rst @@ -0,0 +1,170 @@ +################ +HTML Table Class +################ + +The Table Class provides functions that enable you to auto-generate HTML +tables from arrays or database result sets. + +Initializing the Class +====================== + +Like most other classes in CodeIgniter, the Table class is initialized +in your controller using the $this->load->library function:: + + $this->load->library('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). + +:: + + $this->load->library('table'); $data = array(              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). + +:: + + $this->load->library('table'); $query = $this->db->query("SELECT * FROM my_table"); echo $this->table->generate($query); + +Here is an example showing how you might create a table using discrete +parameters:: + + $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(); + +Here is the same example, except instead of individual parameters, +arrays are used:: + + $this->load->library('table'); $this->table->set_heading(array('Name', 'Color', 'Size')); $this->table->add_row(array('Fred', 'Blue', 'Small')); $this->table->add_row(array('Mary', 'Red', 'Large')); $this->table->add_row(array('John', 'Green', 'Medium')); echo $this->table->generate(); + +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'          => '',                     'heading_row_start'   => '',                     'heading_row_end'     => '',                     'heading_cell_start'  => '',                     'row_start'           => '',                     'row_end'             => '',                     'cell_start'          => '',                     'row_alt_start'       => '',                     'row_alt_end'         => '',                     'cell_alt_start'      => '',                     'table_close'         => '
',                     'heading_cell_end'    => '
',                     'cell_end'            => '
',                     'cell_alt_end'        => '
'               ); $this->table->set_template($tmpl); + +.. note:: You'll notice there are two sets of "row" blocks in the + template. These permit you to create alternating row colors or design + elements that alternate with each iteration of the row data. + +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'  => '' ); $this->table->set_template($tmpl); + +****************** +Function Reference +****************** + +$this->table->generate() +======================== + +Returns a string containing the generated table. Accepts an optional +parameter which can be an array or a database result object. + +$this->table->set_caption() +============================ + +Permits you to add a caption to the table. + +:: + + $this->table->set_caption('Colors'); + +$this->table->set_heading() +============================ + +Permits you to set the table heading. You can submit an array or +discrete params:: + + $this->table->set_heading('Name', 'Color', 'Size'); + +:: + + $this->table->set_heading(array('Name', 'Color', 'Size')); + +$this->table->add_row() +======================== + +Permits you to add a row to your table. You can submit an array or +discrete params:: + + $this->table->add_row('Blue', 'Red', 'Green'); + +:: + + $this->table->add_row(array('Blue', 'Red', 'Green')); + +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:: + + $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); $this->table->add_row($cell, 'Red', 'Green'); // generates // + +$this->table->make_columns() +============================= + +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:: + + $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); $new_list = $this->table->make_columns($list, 3); $this->table->generate($new_list); // Generates a table with this prototype
BlueRedGreen
onetwothree
fourfivesix
seveneightnine
teneleventwelve
+ +$this->table->set_template() +============================= + +Permits you to set your template. You can submit a full or partial +template. + +:: + + $tmpl = array ( 'table_open'  => '' ); $this->table->set_template($tmpl); + +$this->table->set_empty() +========================== + +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:: + + $this->table->set_empty(" "); + +$this->table->clear() +===================== + +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:: + + $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(); $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(); + +$this->table->function +====================== + +Allows you to specify a native PHP function or a valid function array +object to be applied to all cell data. + +:: + + $this->load->library('table'); $this->table->set_heading('Name', 'Color', 'Size'); $this->table->add_row('Fred', 'Blue', 'Small'); $this->table->function = 'htmlspecialchars'; echo $this->table->generate(); + +In the above example, all cell data would be ran through PHP's +htmlspecialchars() function, resulting in:: + + + -- cgit v1.2.3-24-g4f1b From d4678626eac3740ec1f10b3a223847448a984641 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 15:40:24 -0500 Subject: fixed code block spacing in HTML Table lib --- user_guide_src/source/libraries/table.rst | 119 +++++++++++++++++++++++++++--- 1 file changed, 108 insertions(+), 11 deletions(-) (limited to 'user_guide_src/source/libraries/table.rst') diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index 6ca6bc971..9bc3f3423 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -26,7 +26,16 @@ function 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')              ); echo $this->table->generate($data); + $this->load->library('table'); + + $data = array( + 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 @@ -35,17 +44,37 @@ function described in the function reference below). :: - $this->load->library('table'); $query = $this->db->query("SELECT * FROM my_table"); echo $this->table->generate($query); + $this->load->library('table'); + + $query = $this->db->query("SELECT * FROM my_table"); + + echo $this->table->generate($query); Here is an example showing how you might create a table using discrete parameters:: - $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(); + $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(); Here is the same example, except instead of individual parameters, arrays are used:: - $this->load->library('table'); $this->table->set_heading(array('Name', 'Color', 'Size')); $this->table->add_row(array('Fred', 'Blue', 'Small')); $this->table->add_row(array('Mary', 'Red', 'Large')); $this->table->add_row(array('John', 'Green', 'Medium')); echo $this->table->generate(); + $this->load->library('table'); + + $this->table->set_heading(array('Name', 'Color', 'Size')); + + $this->table->add_row(array('Fred', 'Blue', 'Small')); + $this->table->add_row(array('Mary', 'Red', 'Large')); + $this->table->add_row(array('John', 'Green', 'Medium')); + + echo $this->table->generate(); Changing the Look of Your Table =============================== @@ -53,7 +82,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'          => '
Fred<strong>Blue</strong>Small
',                     'heading_row_start'   => '',                     'heading_row_end'     => '',                     'heading_cell_start'  => '',                     'row_start'           => '',                     'row_end'             => '',                     'cell_start'          => '',                     'row_alt_start'       => '',                     'row_alt_end'         => '',                     'cell_alt_start'      => '',                     'table_close'         => '
',                     'heading_cell_end'    => '
',                     'cell_end'            => '
',                     'cell_alt_end'        => '
'               ); $this->table->set_template($tmpl); + $tmpl = array ( + 'table_open' => '', + + 'heading_row_start' => '', + 'heading_row_end' => '', + 'heading_cell_start' => '', + + 'row_start' => '', + 'row_end' => '', + 'cell_start' => '', + + 'row_alt_start' => '', + 'row_alt_end' => '', + 'cell_alt_start' => '', + + 'table_close' => '
', + 'heading_cell_end' => '
', + 'cell_end' => '
', + 'cell_alt_end' => '
' + ); + + $this->table->set_template($tmpl); .. note:: You'll notice there are two sets of "row" blocks in the template. These permit you to create alternating row colors or design @@ -63,7 +113,9 @@ 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'  => '' ); $this->table->set_template($tmpl); + $tmpl = array ( 'table_open' => '
' ); + + $this->table->set_template($tmpl); ****************** Function Reference @@ -113,7 +165,11 @@ 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:: - $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); $this->table->add_row($cell, 'Red', 'Green'); // generates // + $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); + $this->table->add_row($cell, 'Red', 'Green'); + + // generates + // $this->table->make_columns() ============================= @@ -123,7 +179,24 @@ 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:: - $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); $new_list = $this->table->make_columns($list, 3); $this->table->generate($new_list); // Generates a table with this prototype
BlueRedGreenBlueRedGreen
onetwothree
fourfivesix
seveneightnine
teneleventwelve
+ $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); + + $new_list = $this->table->make_columns($list, 3); + + $this->table->generate($new_list); + + // Generates a table with this prototype + + + + + + + + + + +
onetwothree
fourfivesix
seveneightnine
teneleventwelve
$this->table->set_template() ============================= @@ -133,7 +206,9 @@ template. :: - $tmpl = array ( 'table_open'  => '' ); $this->table->set_template($tmpl); + $tmpl = array ( 'table_open' => '
' ); + + $this->table->set_template($tmpl); $this->table->set_empty() ========================== @@ -151,7 +226,23 @@ multiple tables with different data you should to call this function after each table has been generated to empty 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(); $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(); + $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(); + + $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(); $this->table->function ====================== @@ -161,7 +252,13 @@ object to be applied to all cell data. :: - $this->load->library('table'); $this->table->set_heading('Name', 'Color', 'Size'); $this->table->add_row('Fred', 'Blue', 'Small'); $this->table->function = 'htmlspecialchars'; echo $this->table->generate(); + $this->load->library('table'); + + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', 'Blue', 'Small'); + + $this->table->function = 'htmlspecialchars'; + echo $this->table->generate(); In the above example, all cell data would be ran through PHP's htmlspecialchars() function, resulting in:: -- cgit v1.2.3-24-g4f1b From 46e3a9a365e6bae7954f5118db1409faa5f5decd Mon Sep 17 00:00:00 2001 From: Mike Funk Date: Fri, 24 Feb 2012 09:38:35 -0500 Subject: added config check, changelog entry, and user guide update. --- user_guide_src/source/libraries/table.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'user_guide_src/source/libraries/table.rst') diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index 9bc3f3423..6a808abc2 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -116,6 +116,8 @@ example, only the table opening tag is being changed:: $tmpl = array ( 'table_open' => '
' ); $this->table->set_template($tmpl); + +You can also set defaults for these in a config file. ****************** Function Reference -- cgit v1.2.3-24-g4f1b