Getting Started (find latest version here)

From DataGrid Wiki

Getting Started (for version 4.0.0 or above)

Contents 1 Common Notices 1.1 Syntax. 1.2 Common notes. 2 Getting Started 2.1 Step 1. Creating & Calling. 2.2 Step 2. General Settings. 2.3 Step 3. Printing & Exporting Settings. 2.4 Step 4. Sorting & Paging Settings. 2.5 Step 5. Filter (search) Settings. 2.6 Step 6. View Mode Settings. 2.7 Step 7. Add/Edit/Details Mode Settings. 2.8 Step 8. Bind the DataGrid. 3 Not documented features and functions. 3.1 Properties 3.2 Methods 3.3 Features

Common Notices

Syntax.

We use

## as comments
// as lines, that must be uncommented
/// as lines, that may be uncommented (optional)

Common notes.

Please, use a $debug_mode = true; before you say "Why Nothing Works ?!"

From version 4.2.4 only PHP5 is supported!

Do not put DataGrid code into another HTML form: <form>...</form>

Getting Started

(for version 4.0.0 or above)

Step 1. Creating & Calling.

+---------------------------------------------------------------------------+
| Creating & Calling:
+---------------------------------------------------------------------------+

Be sure you write here a right relative (virtual) path to the datagrid.class.php file and pear directory (relatively to the current file).

RELATIVE PATH ONLY

define ("DATAGRID_DIR", "");    /* Ex.: "datagrid/" */
define ("PEAR_DIR", "pear/");   /* Ex.: "datagrid/pear/" */

require_once(DATAGRID_DIR.'datagrid.class.php');
require_once(PEAR_DIR.'PEAR.php');
require_once(PEAR_DIR.'DB.php');

Put valid values into these variables. 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 our database.

ob_start();
 
## *** (example of ODBC connection string)
## *** $result_conn = $db_conn->connect(DB::parseDSN('odbc://root:12345@test_db'));
## *** (example of Oracle connection string)
## *** $result_conn = $db_conn->connect(DB::parseDSN('oci8://root:12345@localhost:1521/mydatabase)); 
## *** (example of PostgreSQL connection string)
## *** $result_conn = $db_conn->connect(DB::parseDSN('pgsql://root:12345@localhost/mydatabase)); 
## === (Examples of connections to other db types see in "docs/pear/" folder)

$db_conn =& DB::factory('mysql'); 
$result_conn = 
   $db_conn->connect(DB::parseDSN('mysql://'.$DB_USER.':'.$DB_PASS.'@'.$DB_HOST.'/'.$DB_NAME));
if(DB::isError($result_conn)){ 
   die($result_conn->getMessage()); 
}

Now you have to prepare the 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 them to be shown, because the DataGrid class works with only on fields that 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 a new class instance and linking the DataGrid class to our database. 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 same page).

##  *** set needed options and create a new class instance 

// display SQL statements while processing 
$debug_mode = false;
// display system messages on a screen     
$messaging = true;
// prevent overlays - must be started with a letter
$unique_prefix = "abc_";

$dgrid = new DataGrid($debug_mode, $messaging, $unique_prefix, DATAGRID_DIR);

Now we need to set data source to the DataGrid. We may define default columns ordering, by writing an apropriate field in $default_order_field (you can write some fields, separated by commas) and a sorting type in $default_order_type (they also may be written with commas).
Example:
$default_order_field = "Region, CountryID";
$default_order_type = "ASC, DESC";

##  *** set data source with needed options

// make default(first) ordering by this field
$default_order_field = "field_name_1 [, field_name_2...]";
// default field order type
$default_order_type = "ASC|DESC [, ASC|DESC...]";

$dgrid->DataSource($db_conn, $sql, $default_order_field, $default_order_type);	    

Step 2. General Settings.

+---------------------------------------------------------------------------+
| General Settings:
+---------------------------------------------------------------------------+

If you want to use a local language (not English) - you have to set the right encoding. The database, tables and appropriate fields in your database must be created with the same CHARACTER SET and COLLATE too. Also you need to define in your file: header('Content-type: text/html; charset=XXXX'); where xxxx ISO-8859-1 or UTF-8 or whatever you have.
Example: CHARSET=utf8 COLLATE=utf8_unicode_ci
Example:

##  *** set encoding (default - utf8)

$dg_encoding = "utf8"; 
$dgrid->SetEncoding($dg_encoding);

Set interface language for DatagGrid (en - default). All supported languages are listed under commented lines.

##  *** set interface language (default - English)
##  *** (en) - English     (de) - German     (se) - Swedish   (hr) - Bosnian/Croatian
##  *** (hu) - Hungarian   (es) - Espanol    (ca) - Catala    (fr) - Francais
##  *** (nl) - Netherlands/"Vlaams"(Flemish) (it) - Italiano  (pl) - Polish
##  *** (ch) - Chinese     (sr) - Serbian    (bg) - Bulgarian (pb) - Brazilian Portuguese
##  *** (ar) - Arabic      (tr) - Turkish    (cz) - Czech


$dg_language = "en";  
$dgrid->SetInterfaceLang($dg_language);

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

##  *** set direction: "ltr" or "rtl" (default - ltr)

$direction = "ltr";
$dgrid->SetDirection($direction);

Set layouts for datagrid in view or 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 this parameter empty: "byFieldValue"=>""

##  *** set modes for operations ("type" = "link|button|image"),
##  *** ("byFieldValue" - make the field as a link to edit mode page)
##  *** ("show_add_button"=>"inside|outside" - draw Add button inside or outside of DataGrid)

$modes = array(
  "add"     =>array("view"=>true, "edit"=>false, "type"=>"link", "show_add_button"=>"inside|outside"),
  "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 scrolling settings and parameters for DataGrid. If you want the DataGrid will be displayed with scrolling, allow this option by the next commands.

##  *** allow scrolling on datagrid

$scrolling_option = false;
$dgrid->AllowScrollingSettings($scrolling_option);  


##  *** set scrolling settings (optional)
$scrolling_width = "90%";
$scrolling_height = "100%";
$dgrid->SetScrollingSettings($scrolling_width, $scrolling_height);

If you want to allow multirow operations for DataGrid, set $multirow_option = true;

##  *** allow mulirow operations

$multirow_option = true;
$dgrid->AllowMultirowOperations($multirow_option);

You can work with embedded multi-row operations: delete/details or define your own operation, like in example below. Number of operations, that you may define - is not limited.

$multirow_operations = array(
  "delete"  => array("view"=>true),
  "details" => array("view"=>true),
  "my_operation_name" => 
     array("view"=>true, 
           "flag_name"=>"my_flag_name", 
           "flag_value"=>"my_flag_value", 
           "tooltip"=>"Do something with selected", 
           "image"=>"image.gif")
);
$dgrid->SetMultirowOperations($multirow_operations);  

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 an external file of CSS styles - you define $css_type as "file" and $css_class as the full path to your file.

For example:$css_class = "css/style.css".
Embedded CSS styles: "default", "blue", "gray", "green" and "pink".

##  *** set CSS class for datagrid:
##  *** "default" or "blue" or "gray" or "green" or your css file relative path with name

$css_class = "default";

## "embedded" - use embedded classes, "file" - link to external css file (relative path)

$css_type = "embedded"; 
$dgrid->SetCssClass($css_class, $css_type);

Set variables that you use to get access to your page or have passed from the previous page/s.

##  *** set variables that used to get access to the page
##  *** (like: my_page.php?act=34&id=56 etc.)  

$http_get_vars = array("act", "id");
$dgrid->SetHttpGetVars($http_get_vars);

If you want to use some PHP DataGrid on your page, you need to define other datagrids uniquie prefixes to allow each datagrid to detect others. You need to define in which mode (view/edit/details) the current datagrid will recognize others.

##  *** set another datagrid/s unique prefixes (if you use few datagrids on one page)
##  *** format (in wich mode to allow processing of another datagrids)
##  *** array("unique_prefix"=>array ("view"=>true|false, "edit"=>true|false, "details"=>true|false), [,...]);

$anotherDatagrids = array("abcd_"=>array("view"=>true, "edit"=>true, "details"=>true));
$dgrid->SetAnotherDatagrids($anotherDatagrids);  

Set datagrid title (caption).

##  *** set DataGrid Caption

$dg_caption = "My Favorite Lovely PHP DataGrid";
$dgrid->SetCaption($dg_caption);

Step 3. Printing & Exporting Settings.

+---------------------------------------------------------------------------+
| Printing & Exporting Settings:
+---------------------------------------------------------------------------+

If you want to allow users to view printer-priendly pages and print them - set printing as true.

##  *** set printing option: true(default) or false 

$printing_option = true;
$dgrid->AllowPrinting($printing_option); 

If you want to allow users to export datagrid data - set exporting as true and define exporting directory.

##  *** set exporting option: true(default) or false and relative (virtual) path
##  *** to export directory (relatively to datagrid.class.php file).
##  *** Ex.: "" - if we use current datagrid folder


$exporting_option = true;
$exporting_directory = ""; 
$dgrid->AllowExporting($exporting_option, $exporting_directory);
$exporting_types = array("excel"=>"true", "pdf"=>"true", "xml"=>"true");
$dgrid->AllowExportingTypes($exporting_types);

Step 4. Sorting & Paging Settings.

+---------------------------------------------------------------------------+
| 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. If you want to add a column with rows numeration - set $rows_numeration as true.

##  *** set paging option: true(default) or false 

$paging_option = true;
$rows_numeration = false;
$numeration_sign = "N #";
$dgrid->AllowPaging($paging_option, $rows_numeration, $numeration_sign);

Set aditional paging settings.
$top_paging or $bottom_paging - both define paging (top and bottom) behaviour. We have three parts of the paging line (left, center, right): 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 or all of them - leave it empty Ex.: $bottom_paging = array() or $bottom_paging = array("results"=>true, "results_align"=>"left");.
If you want to define your own dropdown box with page sizes - you can make it in $pages_array array - see example below or leave it empty. Also you can 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"=>"10", "25"=>"25", "50"=>"50", "100"=>"100", "250"=>"250");
$default_page_size = 10;
$paging_arrows = array("first"=>"|<<", "previous"=>"<<", "next"=>">>", "last"=>">>|");
$dgrid->SetPagingSettings($bottom_paging, $top_paging, $pages_array, $default_page_size);

Step 5. Filter (search) Settings.

+---------------------------------------------------------------------------+
| Filter Settings:
+---------------------------------------------------------------------------+

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

##  *** set filtering option: true or false(default)
##  *** tips: use "," (comma) if you want to make search by some words, for ex.: hello, bye, hi

$filtering_option = true;
$dgrid->AllowFiltering($filtering_option);

Set aditional filtering settings.

"Caption_1/2/3/.../n"=> - caption for the filtering field
"table"=>"tableName_1/2/3/.../n"
"field"=>"fieldName_1/2/3/.../n" - table and field we want to filter
"source"=>"self"|$fill_from_array - take values for filtering field (dropdown list) from the specific array or not
Example:

$fill_from_array = array("0"=>"No", "1"=>"Yes");

"operator"=>false|true - draw comparison operators dropdown list or not
"order"=>"ASC|DESC" - dropdown list values order (optional)
"type"=>"textbox|dropdownlist|calendar" - view type of filtering filed (textbox - default)
"autocomplete"=>"false|true" - AJAX autocomplete function (for textbox only)
"handler"=>"modules/autosuggest/test.php" - script that handels autocomplete (for autocomplete only)
"maxresults"=>"12" - number of results, that autocomple function returns (for autocomplete only)
"shownoresults"=>"false|true" - show or not "No Results" box (for autocomplete only)
"case_sensitive"=>false|true - whether filtering is case sensitive
"comparison_type"=>"string|numeric|binary" - filtering comparison type
"on_js_event"=>"" - add here client side javascript function or code
"width"=>"" - define a width of filtering field
"show"=>"" - "show"=>"CONCAT(field1,','field2) as field3" or "show"=>"'link' as field3" or "show"=>"field_name as my_field_name"
"condition"=>"" - some condition. Ex.: TableName_1.FieldName > 'a' AND TableName_1.FieldName < 'c'

##  *** set aditional filtering settings


$filtering_fields = array(
    "Caption_1"=>array(
        "type"=>"textbox",
        "table"=>"tableName_1",
        "field"=>"fieldName_1|,fieldName_2",
        "show_operator"=>false|true,
        "default_operator"=>"=|<|>|like|%like|like%|%like%|not like",
        "case_sensitive"=>false|true,
        "comparison_type"=>"string|numeric|binary",
        "width"=>"",
        "on_js_event"=>""),
    "Caption_2"=>array(
        "type"=>"textbox",
        "autocomplete"=>"false|true",
        "handler"=>"modules/autosuggest/test.php",
        "maxresults"=>"12",
        "shownoresults"=>"false|true",
        "table"=>"tableName_1",
        "field"=>"fieldName_1|,fieldName_2",
        "show_operator"=>false|true,
        "default_operator"=>"=|<|>|like|%like|like%|%like%|not like",
        "case_sensitive"=>false|true,
        "comparison_type"=>"string|numeric|binary", 
        "width"=>"",
        "on_js_event"=>""),
    "Caption_3"=>array(
        "type"=>"dropdownlist",
        "order"=>"ASC|DESC",
        "table"=>"tableName_2",
        "field"=>"fieldName_2",
        "source"=>"self"|$fill_from_array,
        "show_operator"=>false|true,
        "default_operator"=>"=|<|>|like|%like|like%|%like%|not like",
        "case_sensitive"=>false|true,
        "comparison_type"=>"string|numeric|binary",
        "width"=>"",
        "on_js_event"=>""
        "show"=>"",
        "condition"=>""),
    "Caption_4"=>array(
        "type"=>"calendar",
        "table"=>"tableName_3",
        "field"=>"fieldName_3",
        "show_operator"=>false|true,
        "default_operator"=>"=|<|>|like|%like|like%|%like%|not like",
        "case_sensitive"=>false|true,
        "comparison_type"=>"string|numeric|binary",
        "width"=>"",
        "on_js_event"=>"")
);
$dgrid->SetFieldsFiltering($filtering_fields);

Step 6. View Mode Settings.

+---------------------------------------------------------------------------+
| View Mode Settings:
+---------------------------------------------------------------------------+

Set some properties for view mode table

##  *** set table properties

$vm_table_properties = array("width"=>"90%");
$dgrid->SetViewModeTableProperties($vm_table_properties);  

This method sets up columns, that will be viewable.

For all types:
"header"=>"..." - name of the column's header
"type"=>"..." - type of the column.
Possible values: label, image, linktoview, linktoedit, linktodelete, link (http://, mailto:, ftp:// ...), password or barchart
"align"=>"..." - horizontal alignment of the column's content (left, center or right)
"sort_type"=>"string|numeric" - type of column sorting
"width"=>"..." - width of the column in pixels or in percents
"wrap"=>"..." - wraping of the column data (wrap or nowrap)
"text_length"=>"..." - viewable length of the text in characters (any integer number - truncate after this number of characters, "-1" - don't truncate (view a full text))
"case"=>"..." - text case (normal, upper, lower or camel)
"summarize"=>... - summarize values in this column (true or false)
"on_js_event"=>"..." - javascript code or js function on some event. Example: onClick(alert('Clicked!'))

For the "link" type:
"field_key"=>"field_name_0"|"field_key_1"=>"field_name_1"|..., - field for href parameter in
"field_data"=>"...", - field for field_data
"href"=>"..." - href parameter, {0}/{1}/... will be changed on "field_key_0/1/..." value
"target"=>"..." - target parameter

For the "image" type:
"target_path"=>"..." - relative path to image
"default"=>"..." - default image name
"image_width"=>"..." - viewing width of image
"image_height"=>"..." - viewing height of image
"magnify"=>"true|false" - magnify image on mouse over

For the "money" type:
"sign"=>"$" - money sign
"decimal_places"=>"2" - number of decimal places
"dec_separator"=>"." - sign for separation of decimal digits
"thousands_separator"=>"." - sign for separation of thousands digits

For the "barchart" type:
"field"=>"..." - filed name
"maximum_value"=>"..." maximal value for the chart. Number rormat in SELECT SQL must be equal with number format in max_value.

For the "enum" type:
"source"=>"..." - source for enum type. Possible values: user's pre-defined array

##  *** set columns in view mode
##  *** Ex.: "on_js_event"=>"onclick='alert(\"Yes!!!\");'"


$vm_columns = array(
    "FieldName_1" => array("header"=>"Name_A", "type"=>"label",      "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_2" => array("header"=>"Name_B", "type"=>"image",      "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "target_path"=>"uploads/", "default"=>"default_image.ext", "image_width"=>"50px", "image_height"=>"30px", "magnify"=>"false"),
    "FieldName_3" => array("header"=>"Name_C", "type"=>"linktoview", "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_4" => array("header"=>"Name_D", "type"=>"linktoedit", "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_5" => array("header"=>"Name_E", "type"=>"linktodelete", "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_6" => array("header"=>"Name_F", "type"=>"link",       "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "field_key"=>"field_name_0"|"field_key_1"=>"field_name_1"|..., "field_data"=>"field_name_2", "rel"=>"", "title"=>"", "target"=>"_new", "href"=>"{0}"),
    "FieldName_7" => array("header"=>"Name_G", "type"=>"link",       "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "field_key"=>"field_name_0"|"field_key_1"=>"field_name_1"|..., "field_data"=>"field_name_2", "rel"=>"", "title"=>"", "target"=>"_new", "href"=>"mailto:{0}"),
    "FieldName_8" => array("header"=>"Name_H", "type"=>"link",       "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "field_key"=>"field_name_0"|"field_key_1"=>"field_name_1"|..., "field_data"=>"field_name_2", "rel"=>"", "title"=>"", "target"=>"_new", "href"=>"http://mydomain.com?act={0}&act={1}&code=ABC"),
    "FieldName_9" => array("header"=>"Name_I", "type"=>"money",      "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "sign"=>"$", "decimal_places"=>"2", "dec_separator"=>".", "thousands_separator"=>","),
    "FieldName_10"=> array("header"=>"Name_J", "type"=>"password",   "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_11"=> array("header"=>"Name_K", "type"=>"barchart",   "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "field"=>"field_name", "maximum_value"=>"value"),
    "FieldName_12"=> array("header"=>"Name_L", "type"=>"enum",       "align"=>"left", "width"=>"X%|Xpx", "wrap"=>"wrap|nowrap", "text_length"=>"-1", "tooltip"=>"false", "tooltip_type"=>"floating|simple", "case"=>"normal|upper|lower|camel", "summarize"=>"false", "sort_type"=>"string|numeric", "sort_by"=>"", "visible"=>"true", "on_js_event"=>"", "source"=>$fill_from_array),
);
$dgrid->SetColumnsInViewMode($vm_columns);

If you want to get auto-genereted columns - set $auto_column_in_view_mode as true.

##  *** set auto-genereted columns in view mode

$auto_column_in_view_mode = false;
$dgrid->SetAutoColumnsInViewMode($auto_column_in_view_mode);

Step 7. Add/Edit/Details Mode Settings.

+---------------------------------------------------------------------------+
| Add/Edit/Details Mode Settings:
+---------------------------------------------------------------------------+

Set properties for edit mode table.

##  *** set add/edit mode table properties

$em_table_properties = array("width"=>"70%");
$dgrid->SetEditModeTableProperties($em_table_properties);

Set properties for details mode table.

##  *** set details mode table properties

$dm_table_properties = array("width"=>"70%");
$dgrid->SetDetailsModeTableProperties($dm_table_properties);

Set settings for add/edit/details modes

##  ***  set settings for add/edit/details modes

// Table for adding and editing
$table_name  = "table_name";

// Primary key for this table
$primary_key = "primary_key"; 

// Condition. Ex.: table_name.field = 'xxx'
$condition = "";

$dgrid->SetTableEdit($table_name, $primary_key, $condition);

This method sets up columns, that will be viewable.

For all types:
"header"=>"..." - name of the column's header
"type"=>"..." - type of the column.

Possible values: 
    textbox,          textarea, 
    label,            password,  
    print,            date(yyyy-mm-dd), 
    enum,             datedmy(dd-mm-yyyy), 
    image,            datetime(yyyy-mm-dd hh:mm:ss), 
    checkbox,         datetimedmy(dd-mm-yyyy hh:mm:ss),                  
    file,             link (http://, mailto:, ftp:// ...) 
    hidden,           delimiter            

"req_type"=>"..." - field parameters:

first letter: 
    r - required,      s - simple (not required)
second letter: 
    t - text(including datetime), 
    n - numeric,       a - alphanumeric, 
    e - email,         f - float, 
    y - any,           l - login name, 
    z - zipcode,       p - password, 
    i - integer,       v - verified, 
    z - zip code       u - URL
third letter (optional): 
    for numbers: s - signed, u - unsigned, p - positive, n - negative
    for strings: u - upper,  l - lower,    n - normal,   y - any

"align"=>"..." - field horizontal align

Possible values: 
    left, center, right

"width"=>"..." - width of the field in pixels
"title"=>"..." - title (tooltip) of the field
"readonly"=>"..." - if the filed is readonly (false|true)
"maxlength"=>"..." - maximal size in characters of the field value
"default"=>... - default value for the field (for add mode only)
"unique"=>... - make or not (true|false) validation for unique values for this field
"unique_condition"=>... - validation for unique values for this field by the condition (ex.: field_1 > 1 OR field_2 = 99)
"on_js_event"=>"..." - javascript code or js function on some event. Example: onClick(alert('Clicked!'))

For the "link" type:
"field_key"=>"field_name_0"|"field_key_1"=>"field_name_1"|..., - field for href parameter in <a href="...field_key_x...">
"field_data"=>"...", - field for <a href="">field_data
"href"=>"..." - href parameter, {0}/{1}/... will be changed on "field_key_0/1/..." value
"target"=>"..." - target parameter

For the "image" type:
Make sure, that target_path directory has 777 permissions
"target_path"=>"..." - relative (or full) path to image
"file_name"=>"..." - set new name for image or use an original file name
"max_file_size"=>"..." - maximal image size allowed. Ex.: 1000, 10K, 1.2M or 1G
"image_width"=>"..." - viewing width of image
"image_height"=>"..." - viewing height of image
"magnify"=>"true|false" - magnify image on mouse over

For the "file" type:
Make sure, that target_path directory has 777 permissions
"target_path"=>"..." - relative (or full) path to file
"file_name"=>"..." - set new name for file use an original file name
"max_file_size"=>"..." - maximal image size allowed. Ex.: 1000, 10K, 1.2M or 1G

For the "checkbox" type:
"true_value"=>"..." - set value for checked checkbox
"false_value"=>"..." - set value for unchecked checkbox

For the "enum" type:
"source"=>"..." - source for enum type. Possible values: "self" or from customized array
"view_type"=>"..." - view type of the field: dropdownlist (default) or radiobutton
"radiobuttons_alignment"=>"horizontal|vertical" - type of radiobuttons alignment
"multiple"=>... - true or false (default) - if allow multirows listbox
"multiple_size"=>... - number of rows in multirows listbox (4 - default)

// Fill enum type from the array (optional)
$fill_from_array = array("0"=>"No", "1"=>"Yes", "2"=>"Don't know", "3"=>"My be");  

For the "textarea" type:
"edit_type"=>"..." - simple view - "simple" or advanced wysiwyg editor - "wysiwyg"
"resizable"=>"..." - if the textarea can be resized by mouse
"rows"=>"..." - number of rows (default 7)
"cols"=>"..." - number of columns (default - 50)

For the "delimiter" type:
"inner_html"=>"..." - html for delimiter row

For the "validator" type:
"for_field"=>"..." - name of the field for validation process
"validation_type"=>"password|email" - type of validation field

$em_columns = array(
    "FieldName_1"  =>array("header"=>"Name_A", "type"=>"textbox",    "req_type"=>"rt", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_2"  =>array("header"=>"Name_B", "type"=>"textarea",   "req_type"=>"rt", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "edit_type"=>"simple|wysiwyg", "resizable"=>"false", "rows"=>"7", "cols"=>"50"),
    "FieldName_3"  =>array("header"=>"Name_C", "type"=>"label",      "req_type"=>"rt", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_4"  =>array("header"=>"Name_D", "type"=>"date",       "req_type"=>"rt", "width"=>"187px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "calendar_type"=>"popup|floating"),
    "FieldName_5"  =>array("header"=>"Name_E", "type"=>"datetime",   "req_type"=>"st", "width"=>"187px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "calendar_type"=>"popup|floating"),
    "FieldName_6"  =>array("header"=>"Name_F", "type"=>"time",       "req_type"=>"st", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_7"  =>array("header"=>"Name_G", "type"=>"image",      "req_type"=>"st", "width"=>"220px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "target_path"=>"uploads/", "max_file_size"=>"100000|100K|10M|1G", "image_width"=>"Xpx", "image_height"=>"Ypx", "magnify"=>"false", "file_name"=>"Image_Name", "host"=>"local|remote"),
    "FieldName_8"  =>array("header"=>"Name_H", "type"=>"password",   "req_type"=>"rp", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_9"  =>array("header"=>"Name_I", "type"=>"enum",       "req_type"=>"st", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "source"=>"self"|$fill_from_array, "view_type"=>"dropdownlist(default)|radiobutton", "radiobuttons_alignment"=>"horizontal|vertical", "multiple"=>false, "multiple_size"=>"4"),
    "FieldName_10" =>array("header"=>"Name_J", "type"=>"print",      "req_type"=>"st", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>""),
    "FieldName_11" =>array("header"=>"Name_K", "type"=>"checkbox",   "req_type"=>"st", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "true_value"=>1, "false_value"=>0),
    "FieldName_12" =>array("header"=>"Name_L", "type"=>"file",       "req_type"=>"st", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "target_path"=>"uploads/", "max_file_size"=>"100000|100K|10M|1G", "file_name"=>"File_Name", "host"=>"local|remote"),
    "FieldName_13" =>array("header"=>"Name_M", "type"=>"link",       "req_type"=>"st", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true", "on_js_event"=>"", "field_key"=>"field_name_0"|"field_key_1"=>"field_name_1"|..., "field_data"=>"field_name_2", "target"=>"_new", "href"=>"http://mydomain.com?act={0}&act={1}&code=ABC"),
    "FieldName_14" =>array("header"=>"Name_N", "type"=>"foreign_key","req_type"=>"ri", "width"=>"210px", "title"=>"", "readonly"=>false, "default"=>"", "unique"=>false, "unique_condition"=>"", "visible"=>"true"),
    "FieldName_15" =>array("header"=>"",       "type"=>"hidden",     "req_type"=>"st", "default"=>"default_value", "visible"=>"true", "unique"=>false|true),
    "validator"    =>array("header"=>"Name_O", "type"=>"validator",  "req_type"=>"rv", "width"=>"210px", "title"=>"", "readonly"=>false, "maxlength"=>"-1", "default"=>"", "visible"=>"true", "on_js_event"=>"", "for_field"=>"", "validation_type"=>"password|email"),
    "delimiter"    =>array("inner_html"=>"
"),
);

$dgrid->SetColumnsInEditMode($em_columns);

If you want to get auto-genereted columns - set $auto_column_in_edit_mode as true.

##  *** set auto-genereted columns in edit mode

$auto_column_in_edit_mode = false;
$dgrid->SetAutoColumnsInEditMode($auto_column_in_edit_mode);

then uncomment and set right values for the next rows:

##  ***  set settings for add/edit/details modes

$table_name  = "table_name";
$primary_key = "primary_key";
$condition   = "";
$dgrid->SetTableEdit($table_name, $primary_key, $condition);

Settings for the foreign keys.

"ForeignKey_1/2/3.../n"=>"..." - foreign key from "Edit" table

"table"=>"..." - foreign table name
"field_key"=>"..." - key in foreign table
"field_name"=>"..." - filed, that will be viewed or virtual field: "field_name"=>"CONCAT(field1,','field2) as field3"
"view_type"=>"..." - view type. Possible values: dropdownlist(default), radiobutton or texbox
"condition"=>"..." - some condition. Ex.: TableName_1.FieldName > 'a' AND TableName_1.FieldName < 'c'
"order_by_field"=>"..." - sorting order by the filed
"order_type"=>"..." - sorting type
"on_js_event"=>"..." - javascript code or js function on some event. Example: onClick(alert('Clicked!'))

##  *** set foreign keys for add/edit/details modes (if there are linked tables)
##  *** Ex.: "condition"=>"TableName_1.FieldName > 'a' AND TableName_1.FieldName < 'c'"
##  *** Ex.: "on_js_event"=>"onclick='alert(\"Yes!!!\");'"

$foreign_keys = array(
    "ForeignKey_1"=>array("table"=>"TableName_1", "field_key"=>"FieldKey_1", "field_name"=>"FieldName_1", "view_type"=>"dropdownlist(default)|radiobutton|textbox", "condition"=>"", "order_by_field"=>"My_Field_Name", "order_type"=>"ASC|DESC", "on_js_event"=>""),
    "ForeignKey_2"=>array("table"=>"TableName_2", "field_key"=>"FieldKey_2", "field_name"=>"FieldName_2", "view_type"=>"dropdownlist(default)|radiobutton|textbox", "condition"=>"", "order_by_field"=>"My_Field_Name", "order_type"=>"ASC|DESC", "on_js_event"=>"")
);
 
$dgrid->SetForeignKeysEdit($foreign_keys);

Step 8. Bind the DataGrid.

+---------------------------------------------------------------------------+
| 8. Bind the DataGrid: |
+---------------------------------------------------------------------------+

Now we need to bind our DataDrid and draw it on the screen.

*** bind the DataGrid and draw it on the screen

$dgrid->Bind(true);
ob_end_flush();

Not documented features and functions.

Properties

---

Allows automatical getting focus on the first displayed field in edit mode (default - false)

first_field_focus_allowed = true|false;

Allows floating tool tips (default - false)

floating_tool_tips_allowed = true|false;

Attributes in view mode for labels and in add/edit/details modes for textboxes

"pre_addition"=>""; and "post_addition"=>"";

Hides DataGrid before searching and shows DataGrid after the search is completed (default - false)

hide_grid_before_serach = true|false;

Return Datagrid to specified mode after updating (default - view)

mode_after_update = "edit";

Runs user's pre-defined function on_item_created event attributes in view/add/edit/details modes for customized work with field value. This function must be defined with 1 parameter, that will get fild's data. Ex.: function function_name($field_value){ ... return $new_field_value;}

"on_item_created" => "function_name"

Define a text, that will be shows on empty dataset

NoDataFoundText = "";

"Autocomplete" attribute for textboxes in add/edit modes (default - "on")

"autocomplete"=>"on|off";

Attributes in view/add/edit/details modes for customized work with field value,
function_name must be defined with 1 parameter, that will get filed data.
Ex.: function_name($field_value){ ... }

"on_item_created"=>"function_name"

Methods

---

Executes SQL query - use it after dataSource() method only (after the using dataSource() need to be recalled)

executeSql()

// Example:
// $sql = "SELECT * FROM tblPresidents WHERE tblPresidents.CountryID = ".$_GET['f_rid'];
// $dSet = $dgrid->ExecuteSql($sql);
// while($row = $dSet->fetchRow()){
//  for($c = 0; ($c < $dSet->numCols()); $c++){ echo $row[$c]." "; }
//  echo "
";
// }

Retuns first column data from SELECT SQL - use it after dataSource() method only (after the using dataSource() need to be recalled)

selectSqlItem()

// Example:
// $sql = "SELECT COUNT(presidentID) FROM tblPresidents WHERE CountryID = ".$_GET['f_rid'];
// $presidents = $dgrid->SelectSqlItem($sql);

Allows rows highlighting (default - true)

allowHighlighting(true|false)

Display validation error all together or separately

setJsErrorsDisplayStyle("all"|"each")

Returns next id of edit table

getNextId()

Returns current id of edit table

getCurrentId()

Features

---

Allows using user's javascript function for extra checkings on form submition in edit mode

// Example: 
// unique_prefix_ - an unique prefix for the datagrid
// <script type='text/javascript'>
// function unique_prefix_onSubmitMyCheck(){
//   alert("Thanks for adding/updating your data!");
//   return true;
// }	
// </script>

Allows to reload form in Edit mode

"on_js_event"
=>"onchange='formAction(\"\", \"\", \"".$dgrid->uniquePrefix."\", \"".$dgrid->HTTP_URL."\", \"".$_SERVER['QUERY_STRING']."\")'"

true - draw DataGrid on the screen
false - do all nedded actions, but don't draw datagrid on the screen

bind(true|false)

Tricks

---

1. Set default value, that disappears on focus:

"default"=>"http://www.website.com",
"on_js_event"=>"onBlur='if(this.value == \"\")
this.value = \"http://www.website.com\";
this.style.color=\"#f68d6f\";' onClick='if(this.value==\"http://www.website.com\")
this.value=\"\"; this.style.color=\"#000000\";'",

2. Set uniquie value for uploading image:

a) "file_name"=>"img_".((isset($_GET['prfx_mode']) && ($_GET['prfx_mode'] == "add")) ? $dgrid->GetNextId() : $dgrid->GetCurrentId())
b) "file_name"=>"img_".((isset($_GET['prfx_mode']) && ($_GET['prfx_mode'] == "add")) ? $dgrid->GetRandomString("10") : $dgrid->GetCurrentId())