How Can We Help?

Calendar Configuration

 
The module “Calendar” of Deepser lets you view the events inside a fully-customizable calendar.

 

To access the Calendar, expand the menu Calendar.
We can see different items: an item All with a link to a page that displays all the calendars on the system. This page is visibile only to Administrators with visibility on all modules; below the “All” item we will see all the calendars configured in the system.

 

Note: non-Administrator users (or Administrators with a limited visbility) cannot see all the items in that menu.

 

 



 

Create a new calendar

To create a new calendar, with a user of type Administrator, go to the Calendar configuration, using the menu System > Calendars.

 

Now, click the menu Add Calendar upper on the right.
We will see the form to insert new calendars.

 

The fields have the following meaning:

 

Field Meaning
Name The name of the calendar that will be displayed under the navigation menu “Calendar”.
Position The position of the calendar in the navigation menu “Calendar”.
Description The description of the Calendar.
Icon Icon of the calendar, displayed on the navigation menu.
Enabled Groups User groups that will see the calendar.
Status If disabled the calendar is not active.

Once inserted the calendar, we can see the fields Source and Backlogs.
This fields are the core of the calendar configuration and will be discussed in the next sections.

 



 

Configure the Source

The field Source contains all the information to retrieve data that are displayed in the calendar.
Deepser Calendar is powerful and flexible: the source can be an internal entity (eg: the table of the Service Operations) or an external source (eg: to call a Rest API and get the events from a Google Calendar or an Exchange Server).

 
Note: every calendar can be linked to more than one source, so that we can populate a calendar with multiple sources.

 
Start configuring a Source.

We will see the form to insert a new source in the calendar.

 

The fields have the following meaning:

 

Field Meaning
Name The name of the source that will be displayed on the lists of the sources.
Code Code of the source, used internally.
Start Date Field The field of the source that identifies the start date of the event displayed on the calendar.
End Date Field The field of the source that identifies the end date of the event displayed on the calendar.
Enabled Groups User groups that can see the source of that calendar.
Status If the source is enabled or not.
Collection Code PHP code executed to retrieve data from the source. We can execute a query on a table or an API call to get an external source.
It is important that this field returns an object that implements the iterable interface of the PHP language, so for example a Collection, an Array, etc.
Drop Code PHP code executed server-side when dropping an element on the calendar. Use this code to modify the dates of the event.
Event Name javascript code used to display the name of the event. This code must return a string that will be displayed on the calendar.
Tooltip Code javascript code executed to display a tooltip (mouse over the element).
Color Code Use this field to return a custom color for the events.
Drop js Code javascript code executed on the client when we move an element on the calendar.

 
Despite of the presence of many fields, following the instructions, we will understand how easy and simple is the configuration of a source. It is also very powerful and flexible for an advanced usage.
To make the next section more readable, we will give an example: we will create a calendar with all Service Operations that have Critical or High priority and we will color the events using the status field of the operation. Every element drop will change the Due Date of our Operations.



 

Example of Source Configuration

Insert the main data to configure a calendar:

 

Create a Source and fill in the fields:

 

Insert now the PHP code to retrieve a datasource. In the field Collection Code insert:
[php]
$collection = Deep::getResourceModel(‘deep_service/operation_collection’);
$collection->addFieldToFilter(‘due_date’, [‘gteq’ => $start]);
$collection->addFieldToFilter(‘due_date’, [‘lteq’ => $end]);
$collection->addFieldToFilter(‘priority_id’, [‘in’ => array(1,2)] );

$this->applyFilters($collection);

foreach ($collection as $operation){
$startEvent = $this->convertToTimezone($operation->getDueDate());
$endEvent = $this->convertToTimezone($operation->getDueDate());
$this->addEvent($startEvent, $endEvent, $operation->toArray());
}
[/php]
This code retrieves all the Operations in the system, it filters them by dates (variables: $start and $end) and then by priority (1=Critical, 2=High).
Then we apply the user filters (we will see in the next section how to configure filters) and in the end with a foreach structure we convert the TimeZone of the Due Dates of the Operations. We add the event to the calendar using addEvent().
This code is enough to display the events on our calendar.

 
The events have no text and they all have the same color.

 

Edit the Event Name field to insert the event title:
[js]
var t = event.item.title;
return t;
[/js]
The properties of the object event.item are valorized by the $collection we defined in the field “Collection Code”. Thus, in our example, the object event.item contains all the information of our Operations.

 
To color the events, modify the Color Code field:
[js]
if (event.item.status == 1 || event.item.status == 2 || event.item.status == 4 )
return “green”;
else
return “black”;
[/js]
We are telling Deepser to set the background of the events with status 1 or 2 or 4 (New, Work In Progress, Reopened) GREEN and BLACK for every other status. To check the status IDs go to Tools $gt; Lists and select the list with the Status of the Operations.

 
Edit the field with the Tooltip Code that way:
[js]
jQuery(element).tooltipster({
theme: “tooltipster-shadow”,
interactive: true,
side: “right”,
content: jQuery(event.item.description)
});
[/js]
Using the jQuery library integrated with Deepser it is easy to display a tooltip with the description of the event.

 

Now our calendar is completed but it has no filter and, most important configuration, if we drop an event we don’t modify anything.

 
Configure now the source so that when move an event the Due Date changes in the Operation record.
Modifichiamo il campo Drop Code della Source in questo modo:
[php]
$operation = Deep::getModel(‘deep_service/operation’)->load($item[‘entity_id’]);
$operation->setDueDate($this->convertToSystemTimezone($start));
$operation->save();
[/php]
Now, when we drop an event, the Due Date will be modified.
We have told the system to get the Operation with entity_id (unique id) represented by the element in the calendar, so we can change the Due Date using the variable $start passed back by the Calendar, we convert it in the system TimeZone in order to avoid inconsistencies. Then, we save the Operation in the database.

 
The field “Drop js Code” is used, for example, to show an alert in the browser when a user moves an event.
This is only an example, we could also implement a very powerful javascript function to call a REST API service invoking an external system or an email notification.
Configure the field “Drop js Code” to display a confirm alert when moving the event.
[js]
if (confirm(‘Are you sure?’))
return true;
else
return false;
[/js]
The user can now cancel the event changes before saving them in the DataBase.

 



 

Configure Filters

For every single source we can add a variable number of filters, that will be displayed on the Deepser screen.

 

Filters are useful to display only the requests assigned to a specific user team, or to filter the status of the requests displayed on the calendar.
Once we have configured a Source, to create a new filter, we have to add it in the configuration, like below:

 

We will see the form with the filter configuration.

 

The fields have the following meaning:

 

Field Meaning
Name The name of the filter, that will be displayed in the filters list.
Code Code of the filter, internally used.
Status If the filter is enabled or not.
Html Element It tells the system which HTML element to use to display the filter. We can add elements with type text, select-box, multiple select, etc.
Collection Code The PHP code executed on the data collection retrieved by the source.

 



 

Filters Configuration Example

We will set a multiple selection filter to select the requests status in the Calendar.
Create a new filter, insert a value of you choice in the field “Code” and “Name”.
In the Html Element field write the following PHP code:
[php]
$this->addField(
‘status’,
‘select’,
array(
‘label’ => ‘Status’,
‘name’ => ‘status’,
‘multiple’ => ‘multiple’,
‘values’ => Deep::helper(‘deep_list’)->loadListValues(Deep_Service_Model_Operation::LIST_CODE_STATUS)->toOptionHash()
)
);
[/php]
This code uses an important feature of the Deepser framework: the addField() function. Using addField() we can insert dynamically HTML objects (input boxes or select boxes) in the form.

 
To apply that filter to the source, write this PHP code in the Collection Code field:
[php]
foreach ($this->getRequestFilter() as $k => $v){
if ($v)
$collection->addFieldToFilter($k, [‘in’ => $v]);
}
[/php]
This code tells Deepser to apply the filters to every $collection element of the source.

 

Note: in the field Collection Code (in the Source configuration), to apply the filters every time we reload the calendar, we need to write the following code, otherwise filters will be ignored:
[php]
$this->applyFilters($collection);
[/php]

 



 

Configure the Backlogs

Backlogs have the same configuration of the Sources: they are data sources of events not yet inserted in the DB.
As for the Sources, also for the Backlogs we can configure a set of filters.
The meaning of the Backlogs is they are elements to give a visual list of tasks/activities not already planned or completed, so that we can visually plan them by dropping a backlog on the calendsr.
Think about a software development manager that has to plan a list of bug resolutions.
Configuring a source with all the already planned bugs and another source with the backlogs where we list all the bugs not yet planned, the manager can immediately see the time-slots available to plan tasks to the developers that have in charge the bug resolutions.

Table of Contents