ClassDescription

CLASS: cTableEntity

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>';

Properties:

• $entity Stores the entity name ('table', 'tr', 'th' or 'td')
• $attr 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.
• $attrtemp Idem for dynamic formatting

Methods:

• AddAttr() Allows adding one attribute and his value. If the attribute is already defined, this method overwrite previous value.
  • Arguments AddAttr($key='',$value='')
  • $key is the attribute name
  • $value is the attribute value, without double-quotes (will be quoted automatically)
  • Exampe: $this->AddAttr('title','Click this column name to change the sort order');
• AddAttrValue() Allows changing the value of one attribute already in the stack. 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.
  • Arguments AddAttrValue($key='',$value='')
  • $key is the attribute name
  • $value is the attribute value to add/merge. A space is added automatically between thevalues. Example: $this->AddAttrValue('class','warning');
• Method: GetAttr() Returns all the attributes (and their values) as one formatted string. The attribute name in lowercase, and the attribute value quoted.
  • Example: id="table1" class="users" summary="Registered users"
  • Important note: 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.
• Method: Start() Returns the html entity with the attributes. Example: <table id="table1" class="users" summary="Registered users">
• Method: End() Just returns the end tag entity. Example: </table>

Notes:

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.
Example: $t = new cTable('table1','users');
This creates a cTable object and will show <table id="table1" class="users"> when using the Start() method.

---

CLASS: cTableRow (extends cTableEntity)

An instance of cTableRow is row object (i.e. a cTableEntity representing a <tr> entity).
See cTableEntity for the description of the properties and methods.

---

CLASS: cTableHead (extends cTableEntity)

An instance of cTableHead is a column header object (i.e. a cTableEntity representing a <th> entity).

Properties:

• $content Stores the column header content.
• $link Stores the column header pattern that must be applied to the content (when there are several rows in the dataset). Example: $this->link = '<a href="page.php?order=col1">%s</a>'; When the row is displayed, this column content will show a link allowing to click this column header (to change the sort order).

---

CLASS: cTableData (extends cTableEntity)

An instance of cTableData is a column cell object (i.e. a cTableEntity representing a <td> entity).
This class also allows defining a list of attribute values that must be applied to certain cells content.
For example, in a column, we want a background color for some specific values:
Here after, we show how to get a green background for positive value, and a red background when the cell content is negative.

Properties:

• $content Stores the column content.
• $dynamicValues Defines a list of cell values and the corresponding attribute-values.
  Example: $t->arrTD['col3']->dynamicValues = array('positive'=>'background-color:green', 'negative'=>'background-color:red');

Methods:

• AddDynamicAttr($attr,$value) This searches in $dynamicValues the corresponding attribute-value, and apply it to the attribute $attr.
  Example: $t->arrTD['col1']->AddDynamicAttr('style',($this->content<0 ? 'negative' : 'positive'));

---

CLASS: cTable (extends cTableEntity)

$t = new cTable('table1','class1');

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.
This principle is also applicable for all other objects (like a <tr>, <td>, or <th>).

Properties:

• $row Stores the default table row definition. It's a cTableRow object.
  It is not mandatory to instantiated the cTableRow object. If missing, it will be instantiated automatically by the methods GetTHrow() and GetTDrow().
• $rowcount, $rowcountmin Stores the number of rows in this table and the minimum number of rows to apply a link in the column headers.
  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).
• $activecol The current active column header. This column header will use the content pattern $activelink instead of his own $link. This active column is identified by the array key of $arrTH. It can be a number or a name (see $arrTH description).
• $activelink The content pattern to apply to the active column header (if $rowcount>$rowcountmin)
• $arrTH Iss a stack designed to store the column headers definitions. It's an array of cTableHead objects.
• $arrTD Is a stack designed to store the column cells definitions. It's an array of cTableData objects.

Examples of column headers:

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)

$t->arrTH[0] = new cTableHead('Name','hd0','head');
$t->arrTH[1] = new cTableHead('Given names','hd1','head');
$t->arrTH[2] = new cTableHead('Address','hd2','head');

Here we store the column headers with a numerical key (the column order: 0,1,2...).
When working with a database, it's more easy to use the database fieldname as key.
For example:

$t->arrTH['name']      = new cTableHead('Name','hd0','head');
$t->arrTH['firstname'] = new cTableHead('Given names','hd1','head');
$t->arrTH['address']   = new cTableHead('Address','hd2','head');

When displaying these column headers, $t->GetTHrow() generates:

<tr>
<th id="hd0" class="head">Name</th>
<th id="hd1" class="head">Given name</th>
<th id="hd3" class="head">Address</th>
</tr>

Examples of column data:

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)

$t->arrTD[0] = new cTableData('Smith','','cell');
$t->arrTD[1] = new cTableData('John','','cell');
$t->arrTD[2] = new cTableData('Wallstreet','','cell');

When displaying these columns, this generates:

<tr>
<th class="cell">Name</th>
<th class="cell">Given name</th>
<th class="cell">Address</th>
</tr>

Note:
When working with database, we will not use these simple declarations.
We will rather used advanced methods allowing to automate columns creation or to fill the contents of several cells.

• End($bUnsetData,$bUnsetHead,$bUnsetRow) overrides cTableEntity::End(). This method closes the table entity (i.e. returns the </table> tag). The options allow removing the columns, column headers or default row:
  • $bUnsetData true allows removing the data column definitions (cTableData objects <td> stored in $this->arrTD)
  • $bUnsetHead true allows removing the header column definitions (cTableHead objects <th> stored in $this->arrTH)
  • $bUnsetRow true allows removing the default row definition (cTableRow object <tr> stored in $this->row)
  • When you want to re-use the same table several times, these options allow cleaning the data cells (or header, row) definitions. If you want reset the entire table, just create a new instance instead of using these options.

Methods:

• AddAttr($attr,$value) See description in cTableEntity base class.

• GetTHrow($id,$class) This method returns the formatted column headers as one string. (e.g. <tr><th>...</th><th>...</th></tr>) If the $row property is not defined, this method creates the cTableRow object (with attributes $id and $class). If the $row property is already defined, this method will use the existing cTableRow object (arguments $id and $class are useless)

• GetTDrow($id,$class) This method returns the formatted column row as one string. (e.g. <tr><td>...</td><td>...</td></tr>) If the $row property is not defined, this method creates the cTableRow object (with attributes $id and $class). If the $row property is already definied, this method will use the existing cTableRow object (arguments $id and $class are useless)

• GetTHnames() 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).

The advanced methods:

The following advanced methods allows changing all columns at once (you can change the entity, the content or an attribute).

• 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.
• ChangeTDentity($arr,$bCreateColumn,$bNamedColumn(): Idem for the column cells.
  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)
• ChangeTDcontent($arr,$bCreateColumn,$bNamedColumn): Idem for the column cells.
• ChangeTHattr($arr,$bCreateColumn,$bNamedColumn): Allows changing one attribute value in each column headers (or add one attribute and his value)

• ChangeTDattr($arr,$bCreateColumn,$bNamedColumn): Idem for the column cells.

• About these advanced methods They will apply the values provided by $arr, but two options are available:

  • $bCreateColumn, when true, will create the missing column objects.
  • $bNamedColumn, when true, will identify the column by the array-key. When false, the method applies the values of $arr in the sequential order.