Changeset 15685 for trunk/inc

Timestamp:

11/20/11 22:31:38 (6 months ago)

Author:

Alexander Trofimov

Message:

Grid - docs and samples

Location:

trunk/inc

Files:

• classes/BxDolGrid.php (modified) (2 diffs)
• classes/BxDolGridQuery.php (modified) (2 diffs)
• js/jquery.webForms.js (modified) (1 diff)

trunk/inc/classes/BxDolGrid.php

@@ -16 +16 @@
 
 /**
- * Grid for any content
- * TODO: doc
+ * Grid for any content. 
+ *
+ * It allows to display some data as grid with ready to use features:
+ * - paginate
+ * - reordering
+ * - sorting
+ * - search
+ * - actions
+ *
+ * The advantages of the this system: 
+ * - Less code to write - so you can concentrate on the main functionality.
+ * - Flexibility - you can turn on/off ready features or override it for the custom behavior.
+ *
+ * Grid is working together with Paginate to look through the data in the grid. @see BxDolPaginate
+ * 
+ * @section grid_create Creating the new Grid object:
+ *
+ * 1. add record to 'sys_objects_grid' table:
+ *
+ * - object: name of the grid object, in the format: vendor prefix, underscore, module prefix, underscore, internal identifier or nothing; for example: bx_profiles_admin - to display profiles in admin panel.
+ * - source_type: type of the source data:
+ *      - Sql: the source is SQL query.
+ *      - Array: the source is serialized array.
+ * - source: the source data, different for each 'source_type':
+ *      - Sql: the SQL query string, without ORDER BY and LIMIT clauses, these clauses are added automatically for sorting, pagination and filtering.
+ *      - Array: 2 dimentional serialized array string.
+ * - table: table name (if 'source_type' is 'Sql'), to automatically update order field and delete records.
+ * - field_id: name of the ID field.
+ * - field_order: name of the order field.
+ * - paginate_url: URL of the page for the grid, set it empty for AJAX paginate, or specify the url for regular page reloading in paginate, with the following markers:
+ *      - {start}: starting record to show data from.
+ *      - {per_page}: number of records per one page.
+ * - paginate_per_page: number of records per one page.
+ * - paginate_simple: show full or simple paginate, the following values are supported:
+ *      - NULL: show full(big) paginate.
+ *      - ''(empty string): show simple(small) paginate.
+ *      - 'some url': show simple(small) paginate with "View All" link to the specified URL.
+ * - paginate_get_start: GET variable name for 'start'.
+ * - paginate_get_per_page: GET variable name for 'per_page'.
+ * - filter_fields: comma separated field names, to search in.
+ * - filter_mode: search mode:
+ *      - like: use SQL LIKE expression for search, if 'source_type' is not 'Sql' it doesn't matter.
+ *      - fulltext: use MATCH ... AGAINST expression for search, if 'source_type' is not 'Sql' it doesn't matter.
+ *      - auto: use 'like' or 'fulltext', depending on 'useLikeOperator' setting option.
+ * - sorting_fields: comma separated field names, which will be allowed for sorting.
+ * - override_class_name: user defined class name which is derived from BxTemplGrid.
+ * - override_class_file: the location of the user defined class.
+ *
+ * 2. Specify field names (columns in the grid) in sys_grid_fields table:
+ *
+ * - object: name of the Grid object.
+ * - name: name of the field, it must refer to the SQL field name in the case of 'Sql' 'source_type' or index of the 2 dimentional array in the case of 'Array' 'source_type'.
+ * - title: title of the field, the language key.
+ * - width: width of the column in % or px, pt, etc.
+ * - params: searialized array of additional params:
+ *      - display: display function from BxDolFormCheckerHelper class, for example to convert unix timestamp to the regular date/time string.
+ *      - attr_cell: tag attributes for the data cell.
+ *      - attr_head: tag attributes for the header cell.
+ * - order: order of the field.
+ * 
+ * There are some fields which are always available, additionally to the provided set of fields:
+ * 
+ * - order: display column as dragable handle, it makes sense if you have data ordered by some field 
+ *          and it is specified in field_order, field_id and table fields; reordering is not correctly 
+ *          working with paginate, so make sure that paginate_per_page number is big enough to show all records; 
+ *          reordering is working with Sql source_type.
+ * - checkbox: display column with checkboxes, so several records can be selected for bulk action; 
+ *          you need to specify field_id field, so every checkbox have unique row id; 
+ *          you need to specify bulk actions separately in sys_grid_actions table.
+ * - actions: display column with single actions, displayed as buttons; you need to specify field_id field, 
+ *          so every action is provided with unique row id; you need to specify single actions separately in sys_grid_actions table.
+ *  
+ * 3. Add actions to sys_grid_actions table:
+ * 
+ * - object: name of the Grid object.
+ * - type: action type, one of the following:
+ *      - bulk: bulk action, to perform on the set of records, the action is usually displaed below the grid.
+ *      - single: simple action, to perform on one record, the action is usually displayed in the grid row.
+ *      - independent: independent actionm which is not related to any rowm the action is usually displayed above the grid.
+ * - name: action name.
+ * - title: title of the action, the language key.
+ * - confirm: ask confirmation before performing the action, 0 or 1.
+ * - order: order of the action in particular actions set by type.
+ * 
+ * Usually you need to handle actions manually, but there are several actions which are available by default:
+ * 
+ * - delete: delete the record, it works automatically when 'source_type' is 'Sql' and 'field_id', 'table' fields are specified.
+ *
+ *
+ *
+ * @section grid_display_custom_cell Displaying custom cell
+ * 
+ * Cell is displayed with default design. It is possible to easily customize its design by specifying custom attributes as 'attr_cell' in params field in sys_grid_fields table. 
+ *
+ * If it is not enough, you can customize it even more by adding the method to your custom class with the following format: 
+ * _getCell[field name]
+ * where [field name] is the name of the field you want to have custom look with the capital first letter. 
+ *
+ * For example:
+ *
+ * @code
+ * protected function _getCellStatus ($mixedValue, $sKey, $aField, $aRow) {        
+ * 
+ *     $sAttr = $this->_convertAttrs(
+ *         $aField, 'attr_cell',
+ *         false, 
+ *         isset($aField['width']) ? 'width:' . $aField['width'] : false // add default styles
+ *     );
+ *     return '<td ' . $sAttr . '><span style="background-color:' . ('Active' == $mixedValue ? '#cfc' : '#fcc') . '">' . $mixedValue . '</span></td>';
+ * } 
+ * @endcode
+ *  
+ * Above example is displaying user's status using different colors depending on the status value. Please note that you need to convert attributes by adding some default classes or styles if you need.
+ *
+ *
+ *
+ * @section grid_display_custom_header Displaying custom column header
+ * 
+ * This is working similar to displaying custom cell. It easily customize its design by specifying custom attributes as 'attr_head' in params field in sys_grid_fields table.
+ * If it is not enough, you can customize it even more by adding the method to your custom class with the following format: 
+ * _getCellHeader[field name]
+ * where [field name] is the name of the field you want to have custom look with the capital first letter. 
+ * 
+ * For example:
+ *
+ * @code
+ * protected function _getCellHeaderStatus ($sKey, $aField) { 
+ *     $s = parent::_getCellHeaderDefault($sKey, $aField);
+ *     return preg_replace ('/<th(.*?)>(.*?)<\/th>/', '<th$1><img src="' . BxDolTemplate::getInstance()->getIconUrl('user.png') . '"></th>', $s);
+ * }
+ * @endcode
+ * 
+ * The above example replaces column header text with the image. 
+ *
+ *
+ *
+ * @section grid_display_custom_action Displaying custom action
+ * 
+ * All actions are displayed as buttons. Bulk and independent actions are displaed as big buttons and single actions are displayed as small buttons.
+ * 
+ * It is possible to completely customize it by adding the following method to your custom class:
+ * _getAction[action name]
+ * where [action name] is the action name with the capital first letter. 
+ * 
+ * For example:
+ *
+ * @code
+ * protected function _getActionCustom1 ($sType, $sKey, $a, $isSmall = false) {
+ *     $sAttr = $this->_convertAttrs(
+ *         $a, 'attr',
+ *         'bx-btn bx-def-margin-sec-left' . ($isSmall ? ' bx-btn-small' : '') // add default classes
+ *     );
+ *     return '<button ' . $sAttr . ' onclick="$(this).off(); alert(\'default behaviour is overrided, so the action is not performed\');">' . $a['title'] . '</button>';
+ * }
+ * @endcode
+ * 
+ * The above example disables default onclick event and just displays an alert. Please note that you need to convert attributes by adding some default classes or styles if you need.
+ *
+ * 
+ * 
+ * @section grid_add_action_handler Add action handler
+ *
+ * As it was mentioned earlier only several actions can be handled automatically, all other actions must be processed manually. 
+ * To add action handler you need to add method to your custom class with the following format: 
+ * performAction[action name]
+ * where [action name] is the action name with the capital first letter. 
+ *
+ * For example:
+ *
+ * @code
+ * public function performActionApprove() {
+ * 
+ *     $iAffected = 0;
+ *     $aIds = bx_get('ids');
+ *     if (!$aIds || !is_array($aIds)) {
+ *         $this->_echoResultJson(array());
+ *         exit;
+ *     }
+ * 
+ *     $aIdsAffected = array ();
+ *     foreach ($aIds as $mixedId) {
+ *         if (!$this->_approve($mixedId))
+ *             continue;
+ *         $aIdsAffected[] = $mixedId;
+ *         $iAffected++;
+ *     }
+ * 
+ *     $this->_echoResultJson(array(
+ *         'msg' => $iAffected > 0 ? sprintf("%d profiles successfully activated", $iAffected) : "Profile(s) activation failed", 
+ *         'grid' => $this->getCode(false),
+ *         'blink' => $aIdsAffected,
+ *     ));
+ * }
+ * 
+ * protected function _approve ($mixedId) {
+ *     $oDb = BxDolDb::getInstance();
+ *     $sTable = $this->_aOptions['table'];
+ *     $sFieldId = $this->_aOptions['field_id'];
+ *     $sQuery = $oDb->prepare("UPDATE `{$sTable}` SET `Status` = 'Active' WHERE `{$sFieldId}` = ?", $mixedId);
+ *     return $oDb->query($sQuery);
+ * }
+ * @endcode
+ * 
+ * The action can be used as 'single' or 'bulk', in the case of 'single' action 'ids' array always has one element.
+ * 
+ * As the result, action must outputs JSON array, which is done by _echoResultJson function. 
+ * The defined indexes in the array determines behavior after action is performed, the following behaviors are supported:
+ * 
+ * - msg: display javascript alert message.
+ * - grid: reload grid data with the provided HTML code.
+ * - popup: display popup with the provided HTML code.
+ * - blink: highlight(blink effect) the specified rows, by the ids.
+ * 
  */
-
-                /**
-                 * Source, different depending on source_type:
-                 * Array - array of arrays.
-                 * Sql - SQL query without LIMIT part, it is added automatically.
-                 */
-/*
-                'object' => 'id' . rand(1000000, 9999999),
-                'source' => array(),  
-                'source_type' => 'Array', // Array, Sql
-                'fields' => array (), // array of fields to display width some options
-                'field_id' => false, // name of id field
-                'field_order' => false, // name of order field
-                'actions_bulk' => array (), // available bulk actions for the diplayed data, standard action is delete
-                'actions_single' => array (), // available single actions for the diplayed data, standard action is delete
-                'actions_independent' => array (), // available independent actions 
-                'form_add' => false, // add data form object
-                'form_edit' => false, // edit data form object
-                'paginate' => false, // array of paginate options
-                'paginate_position' => false, // array of paginate positions(top, bottom) or false to position it by default (bottom)
-                'paginate_simple' => false, // show smaller, simpler paginate; set to non false value to start showing simple paginate
-                'filter' => array(), // filter options: fields and mode (like or fulltext); by default filter is empty array - not shown
-
-*/
-
-
-/*
-
-        'id' => 'sample',
-        'source' => $aAll,  
-        'source_type' => 'Array', // Array, Sql
-        'fields' => array ( // array of fields to display width some options
-            'order' => array('title' => '', 'width' => '1%'),
-            'checkbox' => array('title' => 'Select', 'width' => '2%'),
-            'name' => array('title' => 'Name', 'width' => '25%'),
-            'value' => array('title' => 'Value', 'width' => '15%', 'display' => 'DateTime', 'attr_cell' => array('style' => 'text-align:center'), 'attr_head' => array('style' => 'text-align:center')), 
-            'caption' => array('title' => 'Caption', 'width' => '42%'),
-            'actions' => array('title' => 'Actions', 'width' => '15%'),
-        ), 
-        'field_id' => 'id', // name of id field
-        'field_order' => 'order', // name of order field
-        'actions_bulk' => array ( // available bulk actions for the diplayed data, standard action is delete
-            'delete' => array ('title' => _t('_Delete')),
-            'pause' => array ('title' => _t('_Approve')),
-            'div1' => array (),
-            'custom1' => array ('title' => _t('_Custom1')),
-            'custom2' => array ('title' => _t('_Custom2')),
-        ), 
-        'actions_single' => array ( // available single actions for the diplayed data, standard action is delete
-            'delete' => array ('title' => _t('_Delete')),
-            'edit' => array ('title' => _t('_Edit')),
-        ),
-        'actions_independent' => array ( // available independent actions 
-            'add' => array ('title' => _t('_Add record')),
-        ),
-        'form_add' => false, // add data form object
-        'form_edit' => false, // edit data form object
-        'paginate' => array( // array of paginate options
-            'page_url' => BX_DOL_URL_ROOT . 'samples/grid.php?start={start}',
-            'per_page' => 10,
-        ),
-        'paginate_simple' => false, // show smaller, simpler paginate; set to non false value to start showing simple paginate
-        'filter' => array( // filter options, by default filter is not shown
-            'fields' => array('name', 'value', 'caption'),
-            'mode' => 'like', // like or fulltext
-        ),
-
-*/
 
 class BxDolGrid extends BxDol {
@@ -126 +269 @@
             require_once(BX_DIRECTORY_PATH_ROOT . $aObject['override_class_file']);
         $o = new $sClass($aObject);
-
-        // TODO: check some setting for incompatibility, like:
-        // soring + reordering
-        // paginate + reordering
 
         return ($GLOBALS['bxDolClasses']['BxDolGrid!'.$sObject] = $o);

trunk/inc/classes/BxDolGridQuery.php

@@ -1 @@
-<?php
+<?php defined('BX_DOL') or die('hack attempt');
 /**
- * @package     Dolphin Core
- * @copyright   Copyright (c) BoonEx Pty Limited - http://www.boonex.com/
- * @license     CC-BY - http://creativecommons.org/licenses/by/3.0/
+ * Copyright (c) BoonEx Pty Limited - http://www.boonex.com/
+ * CC-BY License - http://creativecommons.org/licenses/by/3.0/
+ *
+ * @defgroup    DolphinCore Dolphin Core
+ * @{
  */
-defined('BX_DOL') or die('hack attempt');
 
 bx_import('BxDolDb');
 
 /**
- * Database queries for File storage class.
- * @see BxDolStorage
+ * Database queries for grid.
+ * @see BxDolGrid
  */
 class BxDolGridQuery extends BxDolDb {
@@ -74 +75 @@
 }
 
+/** @} */

trunk/inc/js/jquery.webForms.js

@@ -9 +9 @@
     $(this).addNonWebForms();
 
-    // collapsable headers TODO:
+    // collapsable headers TODO: there is other duplicated functionlaity now and this one is not used
     $('thead.collapsable', this).each(function() {
         var $thead = $(this);