Addons

Additionally to the grid class we have develop other add-on classes and methods which will help to enhance user experience. These method are as follow

setSelect - to build selects in searching, editing and grid
setDatepicker - to attach date-picker (time picker) component in editing and searching
setAutocomplete - to provide suggestions while you type into the field in editing and searching

The last two methods are actually separate classes which can be used in any input field in your application. See the docs for theses clases.

setSelect¶

As described in formatters this is special type of select.

The select type is not real select. This is used when we display data in the grid and/or use editing module and have edittype:'select'. The formatter is useful if the data contain key (or code), but we want to display in the grid the value related to this code or key. The same apply to table field on which we want to relate other description.

Definition¶

The method has the following definition

...
    /**
     *
     * Construct the select used in the grid. The select element can be used in the
     * editing modules, in formatter or in search module
     * @param string $colname (required) valid colname in colModel
     * @param mixed $data can be array (with pair key value) or string which is
     * the SQL command which is executed to obtain the values. The command should contain a
     * minimum two fields. The first is the key and the second is the value which will
     * be displayed in the select
     * @param boolean $formatter determines that the select should be used in the
     * formatter of type select. Default is true
     * @param boolean $editing determines if the select should be used in editing
     * modules. Default is true
     * @param boolean $seraching determines if the select should be present in
     * the search module. Default is true.
     * @param array<string> $defvals Set the default value if none is selected. Typically this
     * is useful in search modules. Can be something like array(""=>"All");
     * @param string $sep The default separator when select is build
     * @param string $delim The default delimiter when select string is build
     * @return boolean
     */
public function setSelect($colname, $data, $formatter=true, $editing=true, $seraching=true, $defvals=array(), $sep = ":", $delim=";" )
{
...
}

The two important parameters are colname and data. Where the colname should be a valid name from colModel. This mean that setColModel method should be called before this method.

Example:

...
// Create the jqGrid instance
$grid = new Guriddo\jqGrid\Render\Render($conn);
...
// Write the SQL Query
$grid->SelectCommand = 'SELECT OrderID, CustomerID, Freight, OrderDate, ShipCity FROM orders';
// set the ouput format to json
...
// Let the grid create the model
$grid->setColModel();
$grid->setSelect('CustomerID', "SELECT CustomerID, CompanyName FROM customers");

In the above example when the grid is created it displays not the customer Id code but the customer name related to this code. When editing or search module is used a select is constructed and display the list of the available company names. When a post to server is initiated (in edit or search) actually the code (key value) is send to the script.

The above example actually construct the following javascript:

<script>
jQuery("#grid_id").jqGrid({
...
   colModel : [ {name:'CustometID', formatter:'select', formatoptions : {value:"ALFKI:Alfreds Futterkiste;ANATR:Ana Trujillo Emparedados y helados;ANTON:Antonio Moreno Taquería;..."}}, edittype: "select", editoptions:{value:"...."},  ... ]
...
});
</script>

If for some reason your data contain colon ":" or semicolon ";" these can be replaced in the script with your own using the last parameters in the php method $sep and delim.

Setting the parameters $formatter, $editing, $seraching to false will disable build of select for that module.

The $defval parameter add additionally logic for values if none is selected. Setting a empty string will cause the grid to search on all values when search is performed

setDatepicker¶

Another usefull method is setDatepicker which adds datepicker functionality to your pages. You can customize the date format and language, restrict the selectable date ranges and add in buttons and other navigation options easily.

By default, the date-picker calendar opens in a small overlay onFocus and closes automatically onBlur or when a date is selected.

Installation and configuration¶

We support two type of date-pickers depending on the css frame work used - jQuery UI date-picker and Bootstrap 5 date-picker. This require to to setup the needed javascript and css files before using it. By default the jQuery UI date-picker is configured to be used. To use Bottstrap 5 date-picker it is needed to load the appropriate files. Additional to this it is needed in the script to set only once which css framework is used

With php code

<?php
...
$grid = new Guriddo\jqGrid\Render\Render($conn, 'pdo');
...
$grid->setCssFrameWork('Bootstrap5', 'Bootstrap5');
...

The first parameter is the name of the css framework, the second parameter is the icon set.

To use jQuery UI datepicker it is needed to load the jQuery UI lib javascript file again with the css file. The distribution package of Guriddo jqGrid contain these files, so you need just to point of them.

<head> 

<script src="path_to_dist/js/ext/jquery-ui.min.js"></script>
<link rel="stylesheet" type="text/css" href="path_to_dist/css/ext/jquery-ui.css" /> 

</head>

In case you want to use another jQuery UI theme you can download it from jQuery UI site and replace the css file.

In case when using Bootstrap 5 date-picker it is needed to load the following files:

<!-- bootstrap datepicker -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-datepicker/1.9.0/css/bootstrap-datepicker.min.css" integrity="sha512-mSYUmp1HYZDFaVKK//63EcZq4iFWFjxSL+Z3T/aCt4IO9Cejm03q3NKKYN6pFQzY0SBOr8h+eCIAZHPXcpZaNw==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-datepicker/1.9.0/js/bootstrap-datepicker.min.js" integrity="sha512-T/tUfKSV1bihCnd+MxKD0Hm1uBBroVYBOYSk1knyvQ9VyZJpc/ALb4P0r6ubwVPSGB2GvjeoMAJJImBG12TiaQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

and then in the script to set

...
$grid->setCssFrameWork('Bootstrap5', 'Bootstrap5');
...

setDatepicker should be used after the colModel is created and it has the following parameters:

    /**
     *
     * Construct a pop up calender used in the grid. The datepicker can be used in the
     * editing modules or/and in search module.
     * @uses Calendar class.
     * @param string $colname (required) valid colname in colModel
     * @param array<string,mixed> $options - array with options for the datepicker. Can be
     * all available options from jQuery UI and Bootstrap datepicker in pair name=>value.
     * In case of events a "js:" tag should be added before the value.
     * @param boolean $editing determines if the datepicker should be used in editing
     * modules. Default is true
     * @param boolean $searching determines if the datepicker should be present in
     * the search module. Default is true.
     * @return void
     */
    public function setDatepicker($colname, $options=array(), $editing=true, $searching=true)
    {
  }

All available options, methods and events for jQuery UI date-picker can be found here.

All available options, methods and events for Bootstrap date-picker can be found here

Note

It is important to note that the script automatically set the user date format set with setUserDate - so there is no need to configure it

Example

To set today highlight, auto closing when selecting data and today button in Bootstrap date-picker do the following:

...
 $grid->setColModel(...);
 $grid->setDatepicker('Date', array("todayBtn"=> true, "autoclose"=> true, "todayHighlight" => true,  "title"=>"Calendar"));
 ...

Having this the final output can look like this:

Subgrid

setAutocomplete¶

Autocomplete, when added to an input field, enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.

By giving an Autocomplete field focus or entering something into it, the plugin starts searching for entries that match and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches.

This can be used to enter previous selected values, for example you could use Autocomplete for entering tags, to complete an address, you could enter a city name and get the zip code, or maybe enter email addresses from an address book.

You can pull data in from a local and/or a remote source: Local is good for small data sets (like an address book with 50 entries), remote is necessary for big data sets, like a database with hundreds or millions of entries to select from.

Installation and configuration¶

Similar to date-picker we support two type of autocompleters depending on the css frame work used - jQuery UI autocomplete and Bootstrap 5 autocomplete. This require to to setup the needed javascript and css files before using it. By default the jQuery UI autocompleter is configured to be used. To use Bottstrap 5 one it is needed to load the appropriate files. Additional to this it is needed in the script to set only once which css framework is used

To use jQuery UI autocomplete it is needed to load the jQuery UI lib javascript file again with the css file. The distribution package of Guriddo jqGrid contain these files, so you need just to point of them.

<head> 

<script src="path_to_dist/js/ext/jquery-ui.min.js"></script>
<link rel="stylesheet" type="text/css" href="path_to_dist/css/ext/jquery-ui.css" /> 

</head>

In case you want to use another jQuery UI theme you can download it from jQuery UI site and replace the css file.

In case when using Bootstrap 5 autocomplete it is needed to load the following files from the distribution again with bootstrap css file and bootstrap JavaScript file.

<!-- bootstrap 5 -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.8.0/font/bootstrap-icons.css">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/js/bootstrap.bundle.min.js" integrity="sha384-pprn3073KE6tl6bjs2QrFaJGz5/SUsLqktiwsUTF55Jfv3qYSDhgCecCxMW52nD2" crossorigin="anonymous"></script>

<!-- bootstrap autocomplete -->
<script type="module" src="../vendor/dist/js/ext/autocomplete.js"></script>

Warning

Please note the type attribute of the script type=module. If this is not set the script will output error.

and then in the script to set

...
$grid->setCssFrameWork('Bootstrap5', 'Bootstrap5');
...

setAutocomplete should be used after the colModel is created and it has the following parameters:

    /**
     * Construct autocompleter used in the grid. The autocomplete can be used in the
     * editing modules or/and in search module.
     * @uses Autocomplete class. This requiere to include jqAutocomplete.php in order
     * to work
     * @param string $colname (requiered) valid colname in colModel
     * @param string|bool $target if set determines the input element on which the
     * value will be set after the selection in the autocompleter
     * @param mixed $data can be array or string which is
     * the SQL command which is executed to obtain the values. The command can contain
     * one, two or three fields.
     * If the field in SQL command is one, then this this field will be displayed
     * and set as value in the element.
     * If the fields in SQL command are two,  then the second field will be displayed
     * but the first will be set as value in the element.
     * @param array<string,mixed> $options - array with options for the autocomplete. Can be
     * all available options from jQuery UI autocomplete in pair name=>value.
     * In case of events a "js:" tag should be added before the value.
     * Additionally to this the following options can be used - cache, searchType,
     * ajaxtype, itemLiength. For more info refer to docs.
     * @param boolean $editing determines if the autocomplete should be used in editing
     * modules. Default is true
     * @param boolean $searching determines if the autocomplete should be present in
     * the search module. Default is true.
     * @return void 
     */ 
    public function setAutocomplete($colname, $target=false, $data='', $options=array(), $editing = true, $searching=false)
    {
  }

The first parameter $colname is required and shuld correspond to a name in colModel

The second parameter $target if set determines the input element on which the value will be set after the selection in the autocompleter. The value should be a string an shold begin with '#'; The rule of this setting depemd on the input data.

The third parameter $data can be array or string which is the SQL command which is executed to obtain the values. The command can contain one, two or three fields.

If the field in SQL command is one, then this field will be displayed and set as value in the element. If target elemet is set the value will be populate to it too
If the fields in SQL command are two, the first field is associated with value and the second with label - then the second field will be displayed but the first (value) will be set as value in the element. If the target element is set it will be set with first (value) field.
If the fields in SQL command are three, the first field is associated with value, the second with label , the third field with id - then the second field will be displayed, the first (value) will be set as value in the element and the id field will be set in the target element if defined.

The forth parameter $options is array and allow to configure the behavior of the autocomplete. The different autocomplete plug-ins (jQuery UI and Bottstrap 5) have different options (see below)

The fifth and sixth parameters enable/disable the autocomplete in editing and searching modules.

The a Bootstrap 5 autocomplete plugin has the following options and events:

Name	Type	Description
showAllSuggestions	`Boolean`	Show all suggestions even if they don't match
suggestionsThreshold	`Number`	Number of chars required to show suggestions
maximumItems	`Number`	Maximum number of items to display
autoselectFirst	`Boolean`	Always select the first item
updateOnSelect	`Boolean`	Update input value on selection (doesn't play nice with autoselectFirst)
highlightTyped	`Boolean`	Highlight matched part of the label
fullWidth	`Boolean`	Match the width on the input field
fixed	`Boolean`	Use fixed positioning (solve overflow issues)
labelField	`String`	Key for the label
valueField	`String`	Key for the value
queryParam	`String`	Key for the query parameter for server
items	`Array`	`Object`
source	`function`	A function that provides the list of items
datalist	`String`	The id of the source datalist
server	`String`	Endpoint for data provider
serverParams	`String`	`Object`
liveServer	`Boolean`	Should the endpoint be called each time on input
noCache	`Boolean`	Prevent caching by appending a timestamp
debounceTime	`Number`	Debounce time for live server
notFoundMessage	`String`	Display a no suggestions found message. Leave empty to disable
onRenderItem	`function`	Callback function that returns the label
onSelectItem	`function`	Callback function to call on selection
onServerResponse	`function`	Callback function to process server response. Must return a Promise