Data Grid

Implementation Guide
Created by John Paul de Guzman <jpdguzman@gmail.com>
Data Grid v0.1

Description:
Data Grid component is a simple reusable component for displaying data in tabular format. This component can be extended to create more complex and reusable DataGrid Controls. The Grid's basic implementation was to displays a group of data feed in to it in tabular form.
There are two parts:

DataGrid Header:

The DataGridHeader has two main purpose, to map the data fed into the grid, and to provide textual support for the user.

DataGrid Header is composed of two parts:
The DataGridHeader class and the DataGridHeaderContainer class.
DataGridHeader is a simple DataGrid Header element displayed on top of the page.
A Collection of DataGridHeader is handled by the DataGridHeaderContainer. For multiple column display, DataGridHeaderContainer is needed.

Example

$dgHead1 = new DataGridHeader("item1");
$dgHead2 = new DataGridHeader("item2");

This basic implementation of DataGridHeader simply means that the dgHead1 would be use to point to the all the data with a key name of "item1", this concept applies to "item2"

DataGridHeader with Label

For user to understand the data, DataGridHeader can be set to add texutal support for data being displayed to the user.

Example

$dgHead1 = new DataGridHeader("item1", "Item Id");
$dgHead2 = new DataGridHeader("item2", "Item Description");

The header would display "Item Id" for column "item1" as output on the grid, as well as "Item Description" for item2

DataGridHeader with additional Header Attributes and Controls

DataGridHeader is a subclass of Html class there for the object can facilitate additional html attributes for displaying, controls, additional customize display.
The attribute array follows the same attributes used in Html.

Note:
Upon instantiation, the DataGridHeader class uses "dg_header" as default ID for the DataGridHeader object. One can use this default Id in defining style information or controls
or customize the field by using attributes array or setting a different ID or class

Tip:
For reusable controls and style, its either use stylesheet to control display or create a reusable array of attributes and then use on other HTML elements.

Example

$attributes = array("width" => "200",
                    "height" => "30",
                    "bgcolor" => "red");

$dgHead1 = new DataGridHeader("item1", "Item Id", $attributes);
$dgHead2 = new DataGridHeader("item2", "Item Description", $attributes);

This example shows how attribute array can be used in creating reusable html attributes for the DataGridHeader object.
The output would be:

Output:

<td id="dg_header" width="200" height="30" bgcolor="red">Item Id</td>
<td id="dg_header" width="200" height="30" bgcolor="red">Item Description</td>

DataGirdHeader using different ID

Because the Header uses HTML properties, one can customize the ID definition by setting up a new id via method or attributes array. Pls read code documentation regarding setting ID via setId()
and setting ID via attributes

Example : Set ID via attributes

$attributes = array("width" => "200",
                    "height" => "30",
                    "bgcolor" => "red",
                    "id" => "dataGrid1_id");

$dgHead1 = new DataGridHeader("item1", "Item Id", $attributes);
$dgHead2 = new DataGridHeader("item2", "Item Description", $attributes);

This code would output:

Output:

<td id="dataGrid1_id" width="200" height="30" bgcolor="red">Item Id</td>
<td id="dataGrid1_id" width="200" height="30" bgcolor="red">Item Description</td>

The Class would override the original value Id set to the class. If the Id was removed to the attributes array the ID would return to its default value

Example : Set ID via setMethod()

$attributes = array("width" => "200",
                    "height" => "30",
                    "bgcolor" => "red");

$dgHead1 = new DataGridHeader("item1", "Item Id", $attributes);
$dgHead2 = new DataGridHeader("item2", "Item Description", $attributes);

$dgHead1->setId("dgHead1");
$dgHead2->setId("dgHead2");

This code would output:

Output:

<td id="dgHead1" width="200" height="30" bgcolor="red">Item Id</td>
<td id="dgHead2" width="200" height="30" bgcolor="red">Item Description</td>

The Class would override the original value Id set to the class. If the Id was removed to the attributes array the ID would return to its default value.
There are different advantages between two approach, if you want to customize the the header, you can use the setID() method, if you want a general design over the control
you can use the attribute array or use the default value.

Using The DataGridHeaderContainer

The DataGridHeaderContainer is a collection of DataGridHeader. It is used in displaying the DataGrid header control. There are different ways of implementing the data DataGridHeaderContainer
you can use the via addHeader() method or use an array then predefine during instantiation.

Example : using addHeader()

$dgContainer = new DataGridContainer();


$dgHead1 = new DataGridHeader("item1");
$dgContainer->addHeader($dgHead1);

$dgHead2 = new DataGridHeader("item2"); $dgContainer->addHeader($dgHead2);

Output:

<tr>
    <td id="dg_header">item1</td>
    <td id="dg_header">item2</td>
</tr>

Example : using Array method

$dgHead1 = new DataGridHeader("item1");
$dgHead2 = new DataGridHeader("item2");

$collection = new array($dgHead1, $dgHead2);
$dgContainer = new DataGridContainer($collection);

Output:

<tr>
    <td id="dg_header">item1</td>
    <td id="dg_header">item2</td>
</tr>

Both approaches works the same.

DataGridHeaderContainer Attributes

DataGridHeaderContainer can be fine-tuned using an attribute array or setId(), setClass() method for additional controls and style.

Example : Add fine-tunned controls and style to DataGridContainer

$attributes = array("height" => "90");
$dgContainer = new DataGridHeaderContainer($attributes);

$dgHead1 = new DataGridHeader("item1");
$dgContainer->addHeader($dgHead1);

$dgHead2 = new DataGridHeader("item2"); $dgContainer->addHeader($dgHead2);

Output:

<tr height="90">
    <td id="dg_header">item1</td>
    <td id="dg_header">item2</td>
</tr>

DataGrid Data Format

The DataGrid controls accepts data format before adding it into the control.
As I have said earlier, the DataGridHeader and DataGrid data has a direct connection. Data feed into the datagrid controls uses the associative array to format
and to arrange data into thier proper rows and collumns.

Example Data :

// using array first notion
$data = new array( array("item1" => "value1", "item2" => "value2"); array("item1" => "value12", "item2" => "value22"); ); // second notation
$data[0]['item1'] = "value1";
$data[0]['item2'] = "value2";
$data[1]['item1'] = "value12";
$data[1]['item2'] = "value22";

This is the accepted format used by the controls. Once the data records were evaluated, these data are stored into a DataContainer then collected into a DataGridRow
for not formatted data records, the only thing you have to do is to format the data to be displayed and then let the datagrid evaluate it.

Combining both the Header and the Data

Example:

// Data To be evaluated
$data[0]['item1'] = "value1";
$data[0]['item2'] = "value2";
$data[1]['item1'] = "value12";
$data[1]['item2'] = "value22"; $dgContainer = new DataGridHeaderContainer(); $dgHead1 = new DataGridHeader("item1"); $dgContainer->addHeader($dgHead1);
$dgHead2 = new DataGridHeader("item2"); $dgContainer->addHeader($dgHead2);

In evaluating these code: the Component would read all data with name "item1" and then put it into column 1 where the header named "item1" was located, then the same goes to "item2", so on and so forth.

DataGrid Configuration

The Data Grid Component uses different ways of customizing the controls for display and viewing

Here are the list of all controls you can use in customizing the DataGrid

Example:

$dataGridConfig = array("header" => DataGridHeaderContainer,
                        "data" => array(),
                        "attributes" => array(),

                        "displayHeader" => [true|false],
                        "dataRowAttributes" => array(),

                        "alternateType" => [id|class|attributes],

                        ["alternateId1" => string,"alternateId2" => string, |
                        "alternateClass1" => string, "alternateClass2" => string, |
                        "alternateAttribute1" => array(), "alternateAttribute2" => array()],
                        
                        // DATA GRID ADDITIONAL CONTROLS: Paging
                        "paging" => [true|false],
                        "pagingLocation" => [top|bottom|both],
                        "itemstoshow" => [int|default:10],

                        "pagingTrClass" => "className",
                        "pagingTrId" => "id",
                        "pagingTrAttributes" => array(),

                        "pagingTdClass" => "className",
                        "pagingTdId" => "id",
                        "pagingTdAttributes" => array());


$dg = new DataGrid($dataGridConfig);
$dg->fill();

echo $dg->output();

Basic Configuration:

This is the most basic DataGrid Configuration using arguments on the dataGridConfig array

Example:

$dataGridConfig = array("header" => DataGridHeaderContainer,
                        "data" => array());

$dg = new DataGrid($dataGridConfig);
$dg->fill();

echo $dg->output();

Data Grid With Paging

This Configuration will use an additional attribute for paging:
for Paging there are 3 things you can use to control the data grid's paging capabilities:

paging
Perform Data Grid paging control. If Paging is set to true, paging controls would be added to the component
Value: [true|false]
Default: false


pagingLocation
The position of the paging control
Value: [top|bottom|both]
Default: bottom


itemsToShow
How many items are to be viewed at a time
Value: int
Default: 10

Example:

$dataGridConfig = array("header" => DataGridHeaderContainer,
                        "data" => array(),
                                                
                        "paging" => true,
                        "pagingLocation" => both);


$dg = new DataGrid($dataGridConfig);
$dg->fill();

echo $dg->output();

DataGrid with Alternating Style

Data Grid can also display alternating style for viewing tabular data. To enable this feature added parameters are needed.

alternateType
There can be 3 different implementation of alternating display for datagrid: alternating style by ID, by CLASS or by ATTRIBUTES

Alternate by ID

alternateId1
Alternate ID defintion for rows

alternateId2
Alternate ID definition for rows

Alternate by CLASS

alternateClass1
Alternate Class defintion for rows

alternateClass2
Alternate Class definition for rows


Alternate by ATTRIBUTES

alternateAttribute1
Alternate Attribute defintion for rows (array)

alternateClass2
Alternate Attribute definition for rows (array)


Example: by ID

$dataGridConfig = array("header" => DataGridHeaderContainer,
                        "data" => array(),
                       
                        "alternateType" => "id",

                        "alternateId1" => "alternate_id1",
                        "alternateId2" => "alternate_id2");

$dg = new DataGrid($dataGridConfig);
$dg->fill();

echo $dg->output();