Getting Started

PHP DataGrid - Step by Step.

Step 1.
+---------------------------------------------------------------------------+
| Creating & Calling:
+---------------------------------------------------------------------------+

Be sure you write here a true path to the datagrid.class.php file, relatively to this file.

require_once('datagrid/datagrid.class.php');


Write true values to these variable. Be sure you use a prefix if you need it.

## *** creating variables that we need for database connection
$DB_USER='name'; /* usually like this: prefix_name */
$DB_PASS=''; /* must be already enscrypted (recommended) */
$DB_HOST='localhost'; /* usually localhost */
$DB_NAME='dbName'; /* usually like this: prefix_dbName */


First of all we need to be connected to database.

$db_conn = mysql_connect($DB_HOST,$DB_USER,$DB_PASS);
mysql_select_db($DB_NAME,$db_conn);


Now you have to prepare SELECT SQL statement. It can be any type of SELECT statement your database supports (with JOIN, UNION etc.), but you must put the primary key on the first place. Also be careful to write all fileds you need to be shown, because the DataGrid class works with only fields you placed in SELECT statement. Don't add here ORDER BY, LIMIT words or ; at the end of the statement.

## *** put a primary key on the first place
$sql = "SELECT primary_key, filed_1, filed_2 ... FROM tableName ";


Creating the new class instance and linking the DataGrid class to our database.

$debug_mode = false;
$messaging = true;
$dgrid = new DataGrid($debug_mode, $messaging);
$dgrid->dataSource($db_conn, $sql);



Step 2.
+---------------------------------------------------------------------------+
| General Settings:
+---------------------------------------------------------------------------+

We can add an unique prefix (optional) to our datagrid if we want to prevent using of double names on this page (in case, when you use some datagrids or forms on one page)

## *** set unique prefix
$u_prefix = "_abc";
$dgrid->setUniqueNames($u_prefix);


If you want to use a local language (not English) - you have to set the right
encoding. The properly fields in your database must be created with the same CHARACTER SET.

## *** set encoding (default - utf8)
$dg_encoding = "utf8";
$dgrid->setEncoding($dg_encoding);


Option for some right-to-left languages (Hebrew, Arabic etc.)

## *** set direction: "ltr" or "rtr" (default - ltr)
$direction = "ltr";
$dgrid->setDirection($direction);


Set layouts for datagrid in view mode, edit mode and for the filtering block

## *** set layouts: 0 - tabular(horizontal) - default, 1 - columnar(vertical)
$layouts = array("view"=>0, "edit"=>1, filter=1);
$dgrid->setLayouts($layouts);


Set various modes for datagrid.
True - allow the operation in this mode("view" or "edit"), false - don't allow.
Type - a type of command button (link, html button or image).
byFieldValue - if you want to make this field to be a link to edit mode page (instead of edit button), write here a name of the field. If you want to use a standart edit command button leave it empty - "byFieldValue"=>""

## *** set other modes ("type" = "link|button|image"), ("byFieldValue" - make the field as a link to edit mode page)
$modes = array(
 "add"=>array("view"=>true, "edit"=>false, "type"=>"link"),
 "edit"=>array("view"=>true, "edit"=>true, "type"=>="link",  "byFieldValue"=>"FieldName"),
 "cancel"=>array("view"=>true, "edit"=>true, "type"=>="link"),
 "details"=>array("view"=>true, "edit"=>false, "type"=>="link"),
 "delete"=>array("view"=>true, "edit"=>true, "type"=>="image")
);
$dgrid->setModes($modes);


Set "nowrap" attribute for all columns in the datagrid.

## *** set nowrap attribute for all columns
$wrap = "nowrap";
$dgrid->setColumnsNoWrap($wrap);


Set CSS parameters for the datagrid. If you want to use embedded css class - define $css_type as "embedded" and $css_class as you wish. If you use external file of CSS styles - you define $css_type as "file" and $css_class as full path to your file. For example: $css_class = "../css/datagrid_style.css". Embedded CSS styles: "default", "gray", "like adwords" and "salomon".

## *** set CSS class for datagrid:
$css_class = "default";
$css_type = "embedded";
$dgrid->setCssClass($css_class, $css_type);


To be continued...


Step 3.
+---------------------------------------------------------------------------+
| Printing & Exporting Settings:
+---------------------------------------------------------------------------+

Set printing as true, if you want to allow this option

## *** set printing option: true(default) or false
$printing_option = true;
$dgrid->allowPrinting($printing_option);

Set exporting as true, if you want to allow this option

## *** set exporting option: true(default) or false
$exporting_option = true;
$dgrid->allowExporting($exporting_option);



Step 4.
+---------------------------------------------------------------------------+
| Sorting & Paging Settings:
+---------------------------------------------------------------------------+

Set sorting option as true, if you want to allow sorting on columns

## *** set sorting option: true(default) or false
$$sorting_option = true;
$dgrid->allowSorting($$sorting_option);


Set paging option as true, if you want to allow paging on datagrid

## *** set paging option: true(default) or false
$paging_option = true;
$dgrid->allowPaging($paging_option);


Set aditional paging settings. $bottom_paging or $top_paging are defines both (top and bottom) paging behaviour. We have thee part of paging line: results, pages and page_size dropdownbox. You need to set parameters for each of them. If you don't want to show any of them - leave it empty (Ex.: $bottom_paging = array()). If you want to define your own dropdown box with page sizes - you can make it in $pages_array array - see example below. Also you need to define default page size in $default_page_size variable.

## *** set paging settings
$bottom_paging = array("results"=>true, "results_align"=>"left", "pages"=>true, "pages_align"=>"center", "page_size"=>true, "page_size_align"=>"right");
$top_paging = array("results"=>true, "results_align"=>"left", "pages"=>true, "pages_align"=>"center", "page_size"=>true, "page_size_align"=>"right");
$pages_array = array(10, 25, 50, 100, 250, 500, 1000);
$default_page_size = 10;
$dgrid->setPagingSettings($bottom_paging, $top_paging, $pages_array, $default_page_size);



Step 5.
+---------------------------------------------------------------------------+
| 5. Filter Settings:
+---------------------------------------------------------------------------+

If you want to allow filtering mode, set $filtering_option as true.

## *** set filtering option: true or false(default)
$filtering_option = true;
$dgrid->allowFiltering($filtering_option);


To be continued...


Step 5.
+---------------------------------------------------------------------------+
| 6. View Mode Settings:
+---------------------------------------------------------------------------+

This method sets up columns, that will be viewable.
"header"=>"..." - name of the column header
"type"=>"..." - type of column: label, image, linktoview, link (http://, mailto:) or password
"align"=>"..." - alignment of the column data (left or right)
"wrap"=>"..." - wraping of the column data (wrap or nowrap)
"text_length"=>"..." - viewable text length (any number, "-1" - don't truncate )
"case"=>"..." - text case (normal or upper or lower)

## *** set columns in view mode
$vm_colimns = array(
"FieldName_1"=>array("header"=>"Name_A", "type"=>"label", "align"=>"left", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "case"=>"normal|upper|lower"),
"FieldName_2"=>array("header"=>"Name_B", "type"=>"image", "align"=>"left", "wrap"=>"wrap|nowrap", "text_length"=>'-1', "case"=>"normal|upper|lower"),
"FieldName_3"=>array("header"=>"Name_C", "type"=>"linktoview", "align"=>"left", "wrap"=>"wrap|nowrap", "text_length"=>'-1', "case"=>"normal|upper|lower"),
"FieldName_4"=>array("header"=>"Name_D", "type"=>"link", "align"=>"left", "wrap"=>"wrap|nowrap", "href"=>"www.yahoo.com", "target"=>"_new", "text_length"=>"-1", "case"=>"normal|upper|lower"),
"FieldName_5"=>array("header"=>"Name_E", "type"=>"link", "align"=>"left", "wrap"=>"wrap|nowrap", "field"=>"field_name", "prefix"=>"http://", "target"=>"_new", "text_length"=>"-1", "case"=>"normal|upper|lower"),
"FieldName_6"=>array("header"=>"Name_F", "type"=>"password", "align"=>"left", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "case"=>"normal|upper|lower")
);
$dgrid->setColumnsInViewMode($vm_colimns);


To be continued...