Menu
▾
▴
Tree [132fdd] master / History
| File | Date | Author | Commit |
|---|---|---|---|
| cTable.php | 2012-03-10 |
qcode
|
[6b9cb8] Fixes issue when % exists in the url link |
| readme.html | 2012-03-10 |
qcode
|
[132fdd] Fixes issue when % exists in the url link |
| readme.txt | 2012-03-10 |
qcode
|
[132fdd] Fixes issue when % exists in the url link |
Read Me
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>qt_class_table.php</title>
<style type="text/css">
div.property {margin:10px 0 10px 20px;}
a,p,h1,h2 {font-family:Verdana, Arial, sans-serif;}
a {font-size:10pt; font-weight:bold; text-decoration: none; color: #009999;}
a:hover {font-size:9pt; font-weight:bold; text-decoration: underline; color:#005555;}
h1 {margin:15px 0 5px 0; font-size:16pt; font-weight:bold; color:#009999;}
h2 {margin:15px 0 5px 0; font-size:12pt; font-weight:bold; color:#009999;}
p {margin:5px 0; font-size:10pt;}
p.bold {font-weight:bold;}
span.ex {font-family:"Lucida Console"; font-size:9pt; color:#3135AA;}
</style>
</head>
<body>
<h1>cTable version 1</h1>
<p>cTable allows creating html table and populating cells and cells headers in an easy way.<br/>
It supports header hyperlinks allowing changing rows order <br/>
It also makes possible to have dynamic html attributes (i.e. depending on dataset values).<br/>
cTable is a package of 5 classes.<br/>
<br/>
Content:<br/>
- Class cTableEntity<br/>
- Class cTableRow<br/>
- Class cTable<br/>
- Class cTableTH<br/>
- Class cTableTD<br/>
- Quick start examples<br/>
</p>
<h2>CLASS: cTableEntity</h2>
<p>
cTableEntity is a base class included in all other classes.
It provides basic methods to design the html entities (only table, tr, th and td) and their attributes. Other entities can be inserted with conventional statement like echo '<caption>Registered users</caption>';
</p>
<div class="property">
<p class="bold">Property: $entity</p>
<p>Stores the entity name ('table', 'tr', 'th' or 'td')</p>
<p class="bold">Property: $attr, $attrtemp</p>
<p>Is a stack that stores the attributes: it is an array where the array-key is the attribute name and the array-value is the attribute value.
</p>
<p class="bold">Method: AddAttr()</p>
<p>Allows adding one attribute and his value. If the attribute is already defined, this method overwrite previous value.<br/>
Ex: <span class="ex">$this->AddAttr('title','Click this column name to change the sort order');</span>
</p>
<p class="bold">Method: AddAttrValue()</p>
<p>Allows changing the value of one attribute already in the stack.<br/>
In most cases, the entities are created in the initialisation part of the code while some attribute values must be left empty; because the attributes values may be related to the row or the column content.
With the AddAttrValue() method, it's possible to set/change an attribute value when looping inside the dataset.
</p>
<p class="bold">Method: GetAttr()</p>
<p>Returns all the attributes (and their values) as one formatted string. The attribute name in lowercase, and the attribute value quoted.<br/>
Ex: <span class="ex">' id="table1" class="users" summary="Registered users"'</span><br/>
Important note:<br/>
When an attribute is in the stack but the value is empty (string ''), this method will not include the attribute.
As you will see in following classes, all objects are always instantiated with two attributes ('id' and 'class') but if they are left empty, they will not be included.
</p>
<p class="bold">Method: Start() </p>
<p>Returns the html entity with the attributes.<br/>
Ex: <span class="ex">'<table id="table1" class="users" summary="Registered users">'</span>
</p>
<p class="bold">Method: End() </p>
<p>Just returns the end tag entity<br/>
Ex: <span class="ex">'</table>';</span>
</p>
<p class="bold">Notes:</p>
<p>The cTableEntity is not instantiated directly. The code will rather instantiate other classes that extend this class (see classes documentation here after).
When creating a new entity (for example a <table> entity) you can insert directly the 'id' and 'class' attribute values. To add other attributes, use AddAttr() method.
<br/>
Ex: <span class="ex">$t = new cTable('table1','users');</span><br/>
This creates a cTable object and will show <span class="ex"><table id="table1" class="users"></span> when using the Start() method.
</p>
</div>
<h2>CLASS: cTableRow (extends cTableEntity)</h2>
<p>An instance of cTableRow is row object (i.e. a cTableEntity representing a <tr> entity).<br/>
See cTableEntity for the description of the properties and methods.</p>
<h2>CLASS: cTableHead (extends cTableEntity)</h2>
<p>An instance of cTableHead is a column header object (i.e. a cTableEntity representing a <th> entity).</p>
<div class="property">
<p class="bold">Property: $content</p>
<p>Stores the column header content.</p>
<p class="bold">Property: $link</p>
<p>Stores the column header pattern that must be applied to the content (when there are several rows in the dataset).<br/>
Ex: <span class="ex">$this->link = '<a href="page.php?order=col1">%s</a>';</span><br/>
When the row is displayed, this column content will show a link allowing to click this column header (to change the sort order).</p>
</div>
<h2>CLASS: cTableData (extends cTableEntity)</h2>
<p>An instance of cTableData is a column cell object (i.e. a cTableEntity representing a <td> entity).<br/>
This class also allows defining a list of attribute values that must be applied to certain cells content.<br/>
For example, in a column, we want a background color for some specific values:<br/>
Here after, we show how to get a green background for positive value, and a red background when the cell content is negative.</p>
<div class="property">
<p class="bold">Property: $content</p>
<p>Stores the column content.</p>
<p class="bold">Property: $dynamicValues</p>
<p> Defines a list of cell values and the corresponding attributes values.<br/>
Ex: <span class="ex">$t->$arrTD['col1']->dynamicValues = array('positive'=>'background-color:green','negative'=>'background-color:red').</span></p>
<p class="bold">Method: AddDynamicAttr($attr,$value)</p>
<p>This searches in $dynamicValues the corresponding value, and apply this new value to the attribute $attr.<br/>
Ex: <span class="ex">$t->arrTD['col1']->AddDynamicAttr('style',($this->content<0 ? 'negative' : 'positive'));</span></p>
</div>
<h2>CLASS: cTable (extends cTableEntity)</h2>
<p>$t = new cTable('table1','class1');</p>
<p>When creating an instance of cTable we can assign directly two basic html attributes, the 'id' and the 'class'.
Other attributes can be inserted with the AddAttr() method.<br/>
This principle is also applicable for all other objects (like a <tr>, <td>, or <th>).</p>
<div class="property">
<p class="bold">Property: $row</p>
<p>Stores the default table row definition. It's a cTableRow object.<br/>
It is not mandatory to instantiated the cTableRow object. If missing, it will be instantiated automatically by the methods GetTHrow() and GetTDrow().</p>
<p class="bold">Property: $rowcount, $rowcountmin</p>
<p>Stores the number of rows in this table and the minimum number of rows to apply a link in the column headers.<br/>
For example, when the dataset is empty or when there is only one row in the dataset, the header column cell will not be clickable (no need to sort).</p>
<p class="bold">Property: $activecol</p>
<p>The current active column header. This column header will use the content pattern $activelink instead of his own $link.<br/>
This active column is identified by the array key of $arrTH. It can be a number or a name (see $arrTH description).</p>
<p class="bold">Property: $activelink</p>
<p>The content pattern to apply to the active column header (if $rowcount>$rowcountmin)</p>
<p class="bold">Property: $arrTH</p>
<p>$arrTH is a stack designed to store the column headers definitions. It's an array of cTableHead objects.<br/>
The cTableHead object (described here after) has 3 basic properties: a content, an id attribute and a class attribute (other html attributes can be added with the AddAttr method)</p>
<p>
<span class="ex">$t->arrTH[0] = new cTableHead('Name','hd0','hd');<br/>
$t->arrTH[1] = new cTableHead('Given names','hd1','hd');<br/>
$t->arrTH[2] = new cTableHead('Address','hd2','hd');</span></p>
<p>Here we store the column headers with a numerical key (the column order: 0,1,...).<br/>
When working with a database, it's more easy to use the database fieldname as key. For example:</p>
<p>
<span class="ex">$t->arrTH['name'] = new cTableHead('Name','hd0','head');<br/>
$t->arrTH['firstname'] = new cTableHead('Given names','hd1','head');<br/>
$t->arrTH['address'] = new cTableHead('Address','hd2','head');<br/></span></p>
<p>When displaying these column headers, $t->GetTHrow() generates:</p>
<p><span class="ex"> <tr><th id="hd0" class="head">Name</th><th id="hd1" class="head">Given name</th><th id="hd3" class="head">Address</th></tr></span></p>
<p class="bold">Property: $arrTD</p>
<p>$arrTD is a stack designed to store the column cells definitions. It's an array of cTableData objects.<br/>
The cTableData object (described here after) has 3 basic properties: a content, an id attribute and a class attribute (other html attributes can be added with the AddAttr method)</p>
<p><span class="ex">$t->arrTD[0] = new cTableData('Smith','','cell');<br/>
$t->arrTD[1] = new cTableData('John','','cell');<br/>
$t->arrTD[2] = new cTableData('Wallstreet','','cell');<br/></span></p>
<p>When displaying these columns, this generates:</p>
<p><span class="ex"><tr><th class="cell">Name</th><th class="cell">Given name</th><th class="cell">Address</th></tr></span></p>
<p>Note:</p>
<p>When working with database, we will not use these simple declarations.<br/>
We will rather used advanced methods allowing to automate columns creation or to fill the contents of several cells.</p>
<p class="bold">Method: End($bUnsetData,$bUnsetHead,$bUnsetRow) [overrides cTableEntity::End()]</p>
<p>This method closes the table entity (i.e. returns </table> tag).<br/>
The options allow removing the columns, column headers or default row:<br/>
$bUnsetData true allows removing the data column definitions (cTableData objects <td> stored in $this->arrTD)<br/>
$bUnsetHead true allows removing the header column definitions (cTableHead objects <th> stored in $this->arrTH)<br/>
$bUnsetRow true allows removing the default row definition (cTableRow object <tr> stored in $this->row)<br/>
When you want to re-use the same table several times, these options allow cleaning the only data cells (or header, row) definitions.<br/>
If you want reset the entire table, just create a new instance instead of using these options.</p>
<p class="bold">Method: GetEmptyTable($content='No data...',$bShowHeaders=false,$id='',$class='')</p>
<p>This method return an empty table showing a message (with or without column headers).</p>
<p class="bold">Method: AddAttr($attr,$value)</p>
<p>See description in cTableEntity base class.</p>
<p class="bold">Method: GetTHrow($id,$class)</p>
<p>This method returns the formatted column headers as one string. (e.g. <tr><th>...</th><th>...</th></tr>)<br/>
If the $row property is not defined, this method creates the cTableRow object (with attributes $id and $class).<br/>
If the $row property is already defined, this method will use the existing cTableRow object (arguments $id and $class are useless)</p>
<p class="bold">Method: GetTDrow($id,$class)</p>
<p>This method returns the formatted column row as one string. (e.g. <tr><td>...</td><td>...</td></tr>)<br/>
If the $row property is not defined, this method creates the cTableRow object (with attributes $id and $class).<br/>
If the $row property is already definied, this method will use the existing cTableRow object (arguments $id and $class are useless)</p>
<p class="bold">Method: GetTHnames()</p>
<p>This returns the column header names in an array, where the array-key is the column key (i.e. the $arrTH key) and the array-value is the column header name (i.e. the <th> content).</p>
<p class="bold">The advanced methods:</p>
<p>The following advanced methods allows changing all columns at once (you can change the entity, the content or an attribute).<br/>
ChangeTHentity($arr,$bCreateColumn,$bNamedColumn): Allows changing the entity in all column header. For example to use the tag <td> instead of the default <th> as column headers.<br/>
ChangeTDentity($arr,$bCreateColumn,$bNamedColumn): Idem for the column cells.<br/>
ChangeTHcontent($arr,$bCreateColumn,$bNamedColumn): Allows changing the content of all the column headers at once. It also make possible to create the column headers (if not yet defined)<br/>
ChangeTDcontent($arr,$bCreateColumn,$bNamedColumn): Idem for the column cells.<br/>
ChangeTHattr($arr,$bCreateColumn,$bNamedColumn): Allows changing one attribute value in each column headers (or add one attribute and his value)<br/>
ChangeTDattr($arr,$bCreateColumn,$bNamedColumn): Idem for the column cells.<br/>
These methods will apply the values provided by $arr, but two options:<br/>
- $bCreateColumn, when true, will create the missing column objects.<br/>
- $bNamedColumn, when true, will identify the column by the array-key. When false, the method applies the values of $arr in the sequential order.</p>
</div>
<h2>QUICK START EXAMPLE #1:</h2>
<div class="property">
<p>
<span class="ex">
$t = new cTable('table1','users');<br/>
$t->AddAttr('summary','Registered users');<br/>
echo $t->Start();</span></p>
<p>Output:</p>
<p><span class="ex"><table id="table1" class="users" summary="Registered users"><br/></span></p>
</div>
<h2>QUICK START EXAMPLE #2:</h2>
<div class="property">
<p>
<span class="ex">
$t = new cTable('table1','users');<br/>
$t->arrTH[0] = new cTableHead('Name', 'th0', 'head bold');<br/>
$t->arrTH[1] = new cTableHead('Given names','th1', 'head' );<br/>
$t->arrTH[2] = new cTableHead('Address', 'th2', 'head' );<br/>
echo $t->GetTHrow(); </span></p>
<p>Output:</p>
<p><span class="ex"><tr><th id="th0" class="head bold">Name</th><th id="th1" class="head">Given names</th><th id="th2" class="head">Name</th></tr></span></p>
</div>
<h2>QUICK START EXAMPLE #3:</h2>
<p>This is identical to the example #2, but using advanced methods to automate the creation of the columns and to change all attributes at once</p>
<div class="property">
<p>
<span class="ex">
$t = new cTable('table1','users');<br/>
$t->ChangeTHcontent(array(0=>'Name',1=>'Given names',2=>'Address')); // Here the column headers does not exist, nevertheless this method creates the missing columns (thus columns [0],[1] and [2] are created and the contents are added).<br/>
$t->ChangeTHattr('id', array(0=>'th0',1=>'th1',2=>'th2')); // Here the html 'id' attributes exist (columns are created in previous line) but values are empty. This populates the 'id' attributes with distinct values.<br/>
$t->ChangeTHattr('class', 'head'); // Here is the same as in previous line, but only one value is provided. In this case, this attribute value will be used in all column headers. <br/>
$t->arrTH[0]->AddAttrValue('class',' bold'); // Here we just add the ' bold' value into the existing html class attribute, only in the first column.<br/>
echo $t->GetTHrow(); </span></p>
<p>Output:</p>
<p><span class="ex"><tr><th id="th0" class="head bold">Name</th><th id="th1" class="head">Given names</th><th id="th2" class="head">Name</th></tr></span></p>
</div>
<h2>QUICK START EXAMPLE #4:</h2>
<p>With clickable column header to change sorting order</p>
<div class="property">
<p><span class="ex">
$t = new cTable('table1','users');<br/>
$t->rowcount = 5;<br/>
$t->activecol = $_GET['order'];<br/>
$t->activelink = '';<br/>
$t->arrTH['name'] = new cTableHead('Name', 'th0', 'head', '<a href="thispage.php?order=name">%s</a>');<br/>
$t->arrTH['firstname'] = new cTableHead('Given names','th1', 'head', '<a href="thispage.php?order=firstname">%s</a>');<br/>
$t->arrTH['address'] = new cTableHead('Address', 'th2', 'head', '<a href="thispage.php?order=address">%s</a>');<br/>
echo $t->GetTHrow(); </span></p>
<p>Here the column headers have link property. These patterns are applied to the column headers, except for the active column.<br/>
When the active column is 'name', the output is:</p>
<p><span class="ex">
<tr><br/>
<th id="th0" class="head">Name</th><br/>
<th id="th1" class="head"><a href="thispage.php?order=firstname">Given names</a></th><br/>
<th id="th2" class="head"><a href="thispage.php?order=address">Address</a></th><br/>
</tr></span></p>
<p>Note:<br/>If rowcount is 0 or 1 (i.e. the dataset is empty or contains only 1 row), the link property is not added in the column headers and the output will be the same as in example #3.</p>
</div>
<h2> QUICK START EXAMPLE #5:</h2>
<p>With clickable column headers to change sorting order AND sorting direction (can be switched ascending/descending)</p>
<div class="property">
<p><span class="ex">
$t = new cTable('table1','users');<br/>
$t->rowcount = 5;<br/>
$t->activecol = $_GET['order'];<br/>
$t->activelink = '<a href="thispage.php?order='.$_GET['order'].'&direction='.($_GET['direction']=='asc' ? 'desc' : 'asc').'">%s</a>';<br/>
$t->arrTH['name'] = new cTableHead('Name', 'th0', 'head', '<a href="thispage.php?order=name&direction=asc">%s</a>');<br/>
$t->arrTH['firstname'] = new cTableHead('Given names','th1', 'head', '<a href="thispage.php?order=firstname&direction=asc">%s</a>');<br/>
$t->arrTH['address'] = new cTableHead('Address', 'th2', 'head', '<a href="thispage.php?order=address&direction=asc">%s</a>');<br/>
echo $t->GetTHrow();</span></p>
<p>Here the column headers have a link property. These patterns are applied to the column headers.<br/>
For the active column header an other url link is used: an url link with a reversed direction (from 'asc' to 'desc')<br/>
When the active column is 'name', the output is:</p>
<p><span class="ex">
<tr><br/>
<th id="th0" class="head"><a href="thispage.php?order=name&direction=desc">Name</a></th><br/>
<th id="th1" class="head"><a href="thispage.php?order=firstname&direction=asc">Given names</a></th><br/>
<th id="th2" class="head"><a href="thispage.php?order=address&direction=asc">Address</a></th><br/>
</tr></span></p>
<p>Note:<br/>If rowcount is 0 or 1 (i.e. the dataset is empty or contains only 1 row), the link property is not added in the column headers and the output will be the same as in example #3.</p>
</div>
<h2>QUICK START EXAMPLE #6:</h2>
<p>Show how to have a specific a style added in the dataset row.</p>
<div class="property">
<p>
<span class="ex">
$t = new cTable('table1','users');<br/>
$t->arrTH['name'] = new cTableHead('Name');<br/>
$t->arrTH['bill'] = new cTableHead('Dollars');<br/>
$t->arrTD['name'] = new cTableData(); // We create an empty <td> object. It will be filled when looping in the dataset<br/>
$t->arrTD['bill'] = new cTableData();<br/>
$t->arrTD['bill']->dynamicValues = array('positive'=>'background-color:green','negative'=>'background-color:red');<br/>
echo $t->Start();<br/>
echo $t->GetTHrow();<br/>
// We loop in the dataset (e.g. a row fetched from a sql query)<br/>
while($row = mysql_fetch_assoc($result))<br/>
{<br/>
$t->arrTD['name']->content = $row['name'];<br/>
$t->arrTD['bill']->content = $row['bill']; <br/>
$t->arrTD['bill']->AddDynamicAttr('style', ($row['bill']<0 ? 'negative' : 'positive'));<br/>
echo $t->GetTDrow();<br/>
}<br/>
echo $t->End();</span></p>
<p>Note, if the arrTD are designed with the same key as the database fieldname,<br/>
instead of adding the row content cell by cell,<br/>
we can populate all cells of the row with the method $t->ChangeTDcontent($row);</p>
</div>
<h2>QUICK START EXAMPLE #7</h2>
<p>Using advanced methods. Here we create columns without instantiating each column object.</p>
<div class="property">
<p>
<span class="ex">
$t = new cTable('table1','users');<br/>
$t->ChangeTHcontent(array('Name','Given name','Address')); // create column headers (because not yet existing) and fill content<br/>
$t->ChangeTHattr('class','head'); // add a 'class' attribute with value 'head' to each column<br/>
<br/>
echo $t->Start();<br/>
echo $t->GetTHrow();<br/>
$t->ChangeTDcontent(array('Smith','John','Wallstreet')); echo $t->GetTDrow();<br/>
$t->ChangeTDcontent(array('White','Bob','Downstreet')); echo $t->GetTDrow();<br/>
$t->ChangeTDcontent(array('Brown','Bill','Mainstreet')); echo $t->GetTDrow();<br/>
echo $t->End();<br/>
<br/>
// Output:<br/>
<br/>
<table id="table1" class="users"><br/>
<tr><th class="head">Name</th><th class="head">Given name</th><th class="head">Address</th></tr><br/>
<tr><td>Smith</td><td>John</td><td<Wallstreet</td></tr><br/>
<tr><td>White</td><td>Bob</td><td<Downstreet</td></tr><br/>
<tr><td>Brown</td><td>Bill</td><td<Mainstreet</td></tr><br/>
</table><br/>
</span>
</p>
</div>
</body>
</html>