phpGrid - Document - Functional Methods

Once we finished installation and called phpGrid constructor, the next step is to set phpGrid properites through phpGrid methods before displaying datagrid.

Two types of methods, or functions, are available. Technically, they are the same type of methods in PHP environment, but here for sake for clarity, we separate the methods we used in phpGrid in two main categories, Functional & Cosmetic.

Functional Methods

The Functional methods are the methods control logics and handle events of datagrid. For instance, set sorting data fields and direction, set number of records in a page, determine actions performed when mouse over, set read only fields, hide certains data fields, create conditional output display, etc.

To see how each function is used in context of real world solution, explore our online examples.

Expand All | Contract All

set_sql()
- Description: Set SQL query string
- Parameter(s): (String $sql_string)
- Examples:
```
$dg->set_sql("SELECT * FROM Employees");
```
set_sql_key()
- Description: Define the SQL primary key used to access the record in the table
- Parameter(s): (String $sql_primarykey)
- Examples:
```
$dg->set_sql_key("employeeId");
```
- Remark: When not called "id" is used as primary key
set_sql_table()
- Description: Name of the database table
- Parameter(s): (String $sql_table_name)
- Examples:
```
$dg->set_sql_table("Employees");
```
set_gridpath()
- Description: Set file path to the required phpgrid class files. Similar to PHP include function but only the path. Do not include file name.
- Parameter(s): (String $phpGrid_file_path)
- Examples:
```
$dg->set_gridpath("datagrid/include/");
```
- Remark: If this function is not called phpGrid will try to locate the required file path itself. But for sake of safty, use this function to set datagrid file path.
set_ok_rowindex()
- Description: Whether to display table row index, e.g. 1, 2, 3... etc.?
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_ok_rowindex(true);
```
set_allow_actions() (** LIMITED FUNCTIONALITY IN DEMO **)
- Description: Provide admin features with View, Edit and Delete capability
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_allow_actions(true);
```
- Remark: Beginning version 1.5 phpGrid comes with automatic data size validation and automatic row span for large data field such as text.
set_action_type()
- Description:
  Action Type:
  "V": view
  
  "E": edit
  
  "D": delete
  
  Set admin action by setting any one or combination of the flags above. The default is "VED". E.g "V" view only; "VE" view and edit only; "ED" edit and delete only; "VED" gives all admin action types: view, edit, and delete.
- Parameter(s): (String $action_type)
- Examples:
```
$dg -> set_action_type("VED"); // all actions	
```
set_page_size()
- Description: Define the number of records shown in each page
- Parameter(s): (Integer $page_size)
- Examples:
```
$dg -> set_page_size(5);
```
- Remark: 9999 is used for page size when the method is not called, which indicates
set_col_title()
- Description: Give a more descriptive name to the column header
- Parameter(s): (String $db_field, String $descriptive_title)
- Examples:
```
$dg -> set_col_title("lname", "Last Name");	
$dg -> set_col_title("fname", "First Name");
```
set_col_hidden()
- Description: Hide a column from displaying, such as primary key
- Parameter(s): (String $db_field)
- Examples:
```
$dg -> set_col_hidden ("employeeId");
```
set_col_link()
- Description: Set hyper link in a table cell for a data field
- Parameter(s):
  (String $db_field, String $hyper_ link[, String $db_field] [, String $extra_attribute])
- Examples:
```
$dg -> set_col_link ("managerId", 
                     $_SERVER["SCRIPT_NAME"]."?managerId=", 
                     "managerId", 
                     " target=_new" );
```
- Remark:
  The third parameter is used as the part of the hyperlink as a GET element. The default is the value of the data field of current record.
  
  The fourth parameter is used as an "extra" attribute to the hyperlink to be rendered. A common value is the HTML target attribute, but it can be ANY one or more HTML attribute. If it is defined, the 3rd parameter must be defined as well since they are parameters with default value.

set_col_img()

Description: Display image in table cell for a data field
Parameter(s): (String $db_field, String $path_info, String $CSS_style)

Examples:

$dg -> set_col_img ("imgUrl", 
                     "../", 
                     "border:1px solid black");

set_col_txt()
- Description: Overwrite displayed text from the database, or display text dynamically based on condition, or display no text at all.
- Parameter(s): (String $col_index, String $op_val_pair="", String $true_val="", String $false_val="", Boolean $show_old_val = false)
- Parameters:
  1. $col_index -- data field name
  2. $op_val_pair -- Oprand value pair. e.g. " > 10 "; " = 'abc'"; " != true " etc.
  3. $true_val -- value to return when the comparison is true
  4. $false_val -- value to return when the comparison is false
  5. $show_old_val -- when set to true, the original value will display as well
- Examples:
```
$dg -> set_col_txt("isSenior", " = 1", "YES", "NO", false);
```
set_allow_sort()
- Description: Enable/Disable sorting. It is set to true when the method is not called.
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_allow_sort(true);
```
set_onmouseover()
- Description: Set highlighted color when mouse pointer is over a record. # sign must be included before the Hex color.
- Parameter(s): (String $color)
- Examples:
```
$dg -> set_onmouseover("#ffcc11");
```
set_ok_showcredit() (** NOT AVAILABLE IN DEMO **)
- Description: Display "Powered by phpGrid" at the bottom of the grid.
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_ok_showcredit(true);
```
set_sorted_by()
- Description: Sort datagrid by any data field with descending or ascending directional. The second value is either "DESC" or "ASC".
- Parameter(s): (String $db_field, String $sort_direction)
- Examples:
```
$dg -> set_sorted_by("age", "DESC");
```
set_allow_export()
- Description: Display Export to PDF, Excel and XML buttons which export datagrid to external .pdf, .xlt, and .xml files.
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_allow_export(true);
```
set_ok_nl2br()
- Description: Automatic conversion of cartridge return to HTML
  tag in display
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_ok_nl2br(true);
```
set_toolbar_enabled()
- Description: Show or hide datagrid tool bar. Default is true.
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_toolbar_enabled(true);
```
set_print_enabled()
- Description: Show or hide print command from tool bar. Default is false.
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_print_enabled(false);
```
set_col_sum_enabled()
- Description: Flag whether to display the total of a column.
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_col_sum_enabled(true);
```
set_col_sum()
- Description: Automatically shows sum of a column in datagrid footer. Applicable to data fields with numeric data type.
- Parameter(s): (String $db_field)
- Examples:
```
$dg -> set_col_sum("quantity");
```
set_multidel_enabled()
- Description: Flag whether allowing deletion of multiple records. If the flag is set to true, a checkbox will be shown in front of each row, and the multiple delete button will appear on the toolbar (assuming the set_toolbar_enabled is set to true).
- Parameter(s): (Boolean {true|false})
- Examples:
```
$dg -> set_multidel_enabled(true);
```
set_inlineedit_enabled()
- Description: Inline editng works just like a spreadsheet, this method enables editing the value of each cell in the grid directly. Set the second parameter to true enables AJAX auto-save feature. The new value is automatically saved in database without clicking the Save button on the toolbar. When omitted the second parameter is default to true.
- Parameter(s): (Boolean {true|false} [,Boolean {true|false}])
- Examples:
```
$dg -> set_inlineedit_enabled(true, true);
```
- Remark: The browser must have JavaScript enabled in order to take advantage of the AJAX feature.
set_fields_readonly()
- Description: Set some of the data fields to be read-only (uneditable) in both pop-up edit and inline edit. Seperate each field by comma.
- Parameter(s): (String[] $array_of_dbfield)
- Examples:
```
$dg -> set_fields_readonly("employeeId, SSN, DateHired");
```
- Remark: The browser must have JavaScript enabled in order to take advantage of the AJAX feature.
set_masterdetail()
- Description: Create Master/Detail table. It is extremely easy to use. The first Parameter is the SQL SELECT statement for the detail table. The second Parameter is the foreign key data field name from the main master table. You can use the third parameter to further filter sql result. It will be appended after the WHERE clause after the first condition.
- Parameter(s): (String $SQL_SELET, String $master_foreign_key[, String $extra_filter])
- Examples:
```
/*
The internal SQL statement to retrieve the details is:
SELECT * FROM Sales 
WHERE employeeId = '[$employeeId value]' AND price > 100
*/
$dg -> set_masterdetail("SELECT * FROM Sales", 
                        "employeeId", 
                        " AND price > 100");
```
add_column()
- Description: Add a column to the end of the grid. This function creates a column object from Column class and save it into an array, then It automatically gets rendered when function display() is called.
- Parameter(s): (String $db_field, String $column_description, String $column_type="DataField")
- Parameters Details:
    1: String db_field -- name of the data field name
    2. String column_description -- A descriptive name for the column
    3. String column_type -- The default column type is "DataField" if it
        is not specified, so the actualy value is rendered in HTML.
  
  Hint:
  There are other column type to choose from. Use "Chart:Bar" to display a numeric column in presented in bars.
- Examples:
```
$dg -> add_column("salary", "Annual Salary", "Chart:Bar");
```
add_control()
- Description: Add a HTML control to data input form. You can also create control groups as well.
  
  If no control has been added, phpGrid will default the control to either TEXT or TEXTAREA depending on the size of the data field.
- Parameter(s): (String $db_field, Ctrl $ctrl_type, String[] $arr_kvpair, String $delimiter=",", Int $size=1, String $varname="")
- Parameters Details:
  1: $db_field -- name of the database field name
  2. $ctrl_type -- HTML control type
    Available controls:
          • RADIO
          • CHECKBOX
          • DROPDOWN
          • MULTISELECT
          • TEXT *
          • TEXTAREA *
  3. $arr_kvpair -- key-value pair array used single or group control.
  4. $delimiter -- define the delimiter used to separate multiple values for that single data field. It can be comma, space, tab, or any character of choice.
  5. $size -- this parameter is exclusively used for HTML select dropdown menu, the same as size in <select multiple size=2>. Default value is 1. If greater than 1, the phpGrid assumes it is a multiple select dropdown.
  6. $varname -- To avoid HTML form variable name collision, otherwise, phpGrid defaultly choose the column name as the form variable name.
  
  * Automatically set by system depending on the size of the field.
- Examples:
```
// add a checkbox group control
$dg -> add_control("status", CHECKBOX, 
			array("shipped"=>"Shipped",
			  "approved"=>"Approved",
			  "onhold"=>"On hold",
			  "received"=>"Received",
			  "rejected"=>"Rejected"), ",");
			  
// add a dropdown menu
$dg -> add_control("price", DROPDOWN,
			array("11.98"=>"11.98",
			  "10.8"=>"10.8",
			  "11.3"=>"11.3",
			  "10.15"=>"10.15"));
```
add_action()
- Description: Add user-defined actions to the action column
- Parameter(s): (String $name, String $link[, String $link_id][, String $extra_attr][, String $image])
- Parameters Details:
  1. $name -- name of the action displayed
  2. $link -- URL link
  3. $link_id -- data field name (will be used as part of the hyperlink)
  4. $extra_attr -- additional attributes, such as anchor target
  5. $image -- if image used the $name will be surpressed
- Examples:
```
$dg -> add_action("New Action", 
                  "new_action.php", 
                  "field_name", 
                  "_new", 
                  "../images/new_action_img.gif");
```
add_toolbar_command()
- Description: Similar to add_action() but this adds additonal commands/items to the toolbar instead of datagrid actions column
- Parameter(s): (String $name, String $link[, String $link_id][, String $extra_attr][, String $image])
- Parameters Details:
  1. $name -- name displayed
  2. $link -- URL link
  3. $link_id -- data field name (will be used as part of the hyperlink)
  4. $extra_attr -- additional attributes, such as anchor target
  5. $image -- if image used the $name will be surpressed
- Examples:
```
$dg -> add_toolbar_command("New Command", 
                  "new_command.php", 
                  "field_name", 
                  "_new", 
                  "../images/new_command_img.gif");
```
get_vernum()
- Description: Returns the current phpGrid version number.
- Parameter(s): None
- Examples:
```
// returns "phpGrid Enterprise ver 3.x.x"
echo $dg -> get_vernum();
```
display()
- Description: Display the PHP data grid. This should be the last datagrid function gets called.
- Parameter(s): None
- Examples:
```
$dg -> display ();
```
debug()
- Description: A handy debug function that dumps and displays values in the datagrid object and values of all the phpgrid session variables
- Parameter(s): None
- Examples:
```
$dg -> debug();
```

› Continue to Cosmetic Methods

phpGrid ^tm

The professional PHP datagrid made easy.

phpGrid ^tm Document

Functional Methods

Topics

phpGrid tm

The professional PHP datagrid made easy.

phpGrid tm Document

Functional Methods

Topics

phpGrid ^tm

phpGrid ^tm Document