How Can We Help?

Custom Grids

 
Deepser allows you to customize every grid in the system in a very flexible way, using the native customization features.
Think about the need of some organizations to color a field in the grids based on the priority, or to configure a specific grid to list all the requests in a certain status.
It is possibile to see all the grids in the system: System > Custom Grids .

 

However, to customize a grid, access the module where we want to edit that grid and use the buttons to edit the grid. We will follow an example based on the Service Operation module, so notice in that module the buttons on the upper side of the main screen:

 

This buttons have the following functions:

  1. View the existing grids, open the grid menu (abreast the grid) or create a new grid (this option is visibile only to Administrators and Agents).
  2. Configure the fields of the grid.

 



 

Grid Menu

This feature lets you open a menu abreast the grid where we can see all the grids available for that module.
Using that menu we can easily change the visualization of the grid.

 

This menu is useful, for example, if a working team needs to change rapidly the visualization of the data in the grids. It is possibile (Administrator or Agent) to edit the order of the items with drag&drop.

 

 



 

Create a new grid

To create a new grid, click on the item New Grid:

 

In the popup insert the name of the grid. Choose a name:

Now we have a new grid with all the default fields. To edit it, click on the button to modify the grid:

 

We will enter the screen to edit that grid.
On the left we will see the available columns, or rather the fields (also custom fields defined by the users).

In the middle we can see the visibile fields.
Simply drag&drop those columns to modify them:

 

On the right we have all the settings for that grid:

 

The fields have the following meaning:

 

Field Meaning
Grid Name The name of the grid displayed on the menu.
Prepared Collection This is the most important field to apply custom filters to the data.
Records of Deepser are read from the DataBase (or from another datasource in particular cases) and are inserted into a Collection.
The Collection is an object that contains all the records retrieved from the database.
It is possible, using PHP code, to edit the Collection in order to filter all the data displayed on the grid.
This fields is the right entry point to apply filters to the set of data.
The collection is explored in depth under this section.
Mass Action Here we can configure the Mass Actions, or rather the actions applied by the system to a set of records.
If we enable Mass Actions we can, for example, delete simultaneously more records or give a different value to a set of records, directly from the context menu.
To enable Mass Actions, use this PHP syntax:
[php]
$this->setEnableMassActions(true);
[/php]

 

Row Url Here we can define a custom URL to redirect the user when clicking on a row.
If, for example, we use the following PHP code:
[php]
return “http://erp/id/” . $row->getId();
[/php]
When a user clicks on the row he will not be redirected to the form, but will be redirected to the company ERP passing the ID of the selected row.
Groups Visbility With this field we can filter the visibility of the grid only to certain groups.
Deepser has a flexible configuration: for any grid we can define which working groups can see that grid.

 



 

Understanding Collections

Collections in Deepser are a powerful tool to filter data.
This objects are used in all the grids and lists of the system to provide a fast access to the data, without writing any SQL query.
In the field Prepared Collection we can access the grid object using the PHP variable $this and to get the Collection we can use this PHP syntax:
[php]
$this->getCollection();
[/php]

To add filters to the collection use:
[php]
$this->getCollection()
->addFieldToFilter(‘nome_campo’, [‘expression’ => $value]);
[/php]

Let’s give an example.
If we wanted to filter a grid in the Service module, to display only the operations with status = New (New has ID = 1), then write:

[php]
$this->getCollection()
->addFieldToFilter(‘main_table.status’, [‘eq’ => 1]);
[/php]

Notice we have used the alias main_table to tell the system we are referring to the field Status of the main table (if the grid is in the Service module, entity Operations, the main_table is then the operation table of the database; if the grid is in the Users module, then main_table is the table users, and so on).
For the common fields, like Status, it is important always to set this alias to avoid error of interpretaion. Those errore are indicated by the interface:

 

 
Collections can be filtered using different filter values (‘eq’ means equals):

 

Expression Meaning
eq equals.
neq Not equals.
like Apply a like as in the SQL language.
in The value is in an array:
[php]
$this->getCollection()
->addFieldToFilter(‘main_table.status’, [‘in’ => array(1,2,3)]);
[/php]
retrieves all records with status ID = 1 or 2 or 3.
nin not in
null The field value is null
[php]
$this->getCollection()
->addFieldToFilter(‘main_table.archived’, [‘null’ => true]);
[/php]
retrieves all records with Archived flag null in the DataBase.
gt (lt) Grater than
[php]
$this->getCollection()
->addFieldToFilter(‘main_table.counter’, [‘gt’ => 3]);
[/php]
retrieves all records with counter grater than 3.
lt retriev records with a value less than.
gteq (lteq) Like gt (or lt) but includes also the equals.
regexp Filter a value that matches a Regular Expression.

There are a lot of other expressions that can be used (for example from and to to retrieve a range of values), but with those listed above we can cover the 99% of our needs.

 
We can also filter collections by multiple values, with a logical combination of AND / OR expressions.
Let’s see how to use an OR expression:
[php]
$this->getCollection()->addFieldToFilter(‘main_table.archived’, [[‘neq’ => 1], [‘null’ => true]]);
[/php]
This expression retrieves all records with archived flag equals to 1 OR null.

 
We can also add AND expressions:
[php]
$this->getCollection()
->addFieldToFilter(‘main_table.archived’, [‘eq’ => 1])
->addFieldToFilter(‘main_table.deleted’, [‘eq’ => 1]);
[/php]
This expression retrieves all records with deleted flag = 1 and archived flag = 1.

 



 

Customize fields in the Grids

We have seen we can modify data retrieved by the grid using collections. We can also customize every field layout in the grid.
Select a column in the grid edit form and we will see all the fields to edit a single column layout:

 

The fields have the following meaning:

 

Field Meaning
Header The label of the column header.
Sql Index The name of the field in the DataBase.
Width Width of the column in the grid.
Filter / Sortable If enabled we can sort or filter the column.

 

Type HTML element used to display the field.
If “Text”, then we will filter the column using a textbox.
If “Options”, then the field will be retrievd from a key/value pair.
If “Image”, then the field will display an icon.
There are a lot of Types, but the commonly used are the three listed above.
Renderer PHP code to render the field.
If we want to render a field with the Priority using a particular CSS class use the following syntax (PHP code that returns a string with HTML code):
[php]
try{
$value = $this->escapeHtml($this->getColumn()
->getOptions()[$row->getPriorityId()]);
}catch(Throwable $e){

}

if($row->getPriorityId() == 1){
return ‘<span class=”badge badge-danger”>’.$value.'</span>’;
}
if($row->getPriorityId() == 2){
return ‘<span class=”badge badge-dark”>’.$value.'</span>’;
}
if($row->getPriorityId() == 3){
return ‘<span class=”badge badge-warning”>’.$value.'</span>’;
}
if($row->getPriorityId() == 4){
return ‘<span class=”badge badge-success”>’.$value.'</span>’;
}
if($row->getPriorityId() == 5){
return ‘<span class=”badge badge-info”>’.$value.'</span>’;
}
return $value;
[/php]

Options If the element type is Options we can define a customized set of Items (give the key/value pair).
Table of Contents