Advanced Datetime Type

From dispage wiki

Jump to:navigation, search

Advanced Datetime extension adds to SugarCRM a new field type: AdvancedDatetime. The new AdvancedDatetime fields are more versatile than the default SugarCRM ones, since any date/time measure and dimension can be managed.

Additionally, Enhanced Studio’s Code fields can be used to perform any kind of calculation among AdvancedDatetime fields thanks to the AdvancedDatetimeOperations library, included in Advanced Datetime extension.


Contents

Create an AdvancedDatetime field

An AdvancedDatetime field has the creation mask shown in Figure 1.

Advanced datetime field.png

Figure 1


An AdvancedDatetime field can be created both through Studio or Module Builder by selecting AdvancedDatetime in the “Data Type” selector. A screen similar to the SugarCRM DateTime type appears. Plus, the key-field “Date / Time Type” is above the “Default Value” entry, and allows the Administrator to select an AdvancedDatetime sub-type among the followings:


The meaning of sub-types is explained in the following paragraph.


AdvancedDatetime Sub-Types

Date / Time Sub-Type

Date / Time sub-type allows the user to enter in the same field a date and a time values using the format chosen in the SugarCRM options (see AdvancedDatetime Values Sub-Paragraph).


For instance an AdvancedDatetime field in the Edit View looks like the one in Figure 2, with the default SugarCRM date / time format.


Advanced Date time subtype.jpg

Figure 2


Time Sub-Type

The Time sub-type is a new sub-type that manages only the time of the day, without specifying a date.


LengthTime Sub-Type

LengthTime sub-type is a new sub-type that allows managing a time measure. Compared to the Time sub-type it does not have the limitation of the 24 hours upperbound and can be useful to store time measures across multiple days.


A detail of the LengthTime EditView from an example with an input value of 100 minutes and 16 seconds can be found in Figure 3.

AdvancedDatetime Time length.jpg

Figure 3


Search for an AdvancedDatetime value

AdvancedDatetime Values can be search for through the Advanced Search Tab.

To achieve this, the last version of the Enhanced Search extension must be installed (more details about Enhanced Search can be found at http://www.dispage.com/products/enhanced-search).


This functionality is restricted to the Date / Time Sub-Type only.


AdvancedDatetime calculated fields

Advanced Datetime provides a way to manipulate AdvancedDatetime fields from inside the PHP Code of a Code type field of Enhanced Studio. The Administrator is then allowed to:

As parameters of object’s methods, DateTime values can be referred to in two ways :



AdvancedDatetime Values

When a parameter is passed by specifying the value, the rules explained in this sub-paragraph are followed.

Advanced Datetime uses the date/time format that has been selected in the specific SugarCRM user preferences for both the input and output of the AdvancedDatetime values. This implies that, for example, if the date format “m/d/Y” and the time format “h:i A” have been chosen (the syntax of the format used in this Manual is the one of the PHP date function that can be found at the PHP official website http://www.php.net/manual/en/function.date.php), a valid DateTime value can be “03/13/2009 11:05 AM”. The previous rule applies to DateTime and Time sub-types.

On the other hand, the LengthTime sub-type fields do not depend on the user preferences and can have one of the following formats:

Where Nh , Ni and Ns are number of hours, minutes and seconds, without the 24 / 60 upperbounds.

Thus valid LengthTime values can be either “10:59:59”, “999:12:02”, “103:32” or “110200”, but NOT “11:60:60”.


Initialization

To access the methods of the AdvancedDatetimeOperations class, the Code field must contain the following PHP code:

global $dtcm;
require_once('custom/include/AdvancedDatetime/AdvancedDatetime.php');
$dtcm = new AdvancedDatetimeOperations($bean); 

$dtcm is an instance of a class that provides a user-friendly programming interface that helps to perform the operations detailed below.


Access to the AdvancedDatetime values

To get the value of an existing AdvancedDatetime Field of the module, the method getValue can be used. For example if the field’s name is “Arrival”, the code to display the value of the field is:

echo $dtcm->getValue('Arrival');


If a AdvancedDatetime field of that name does not exist in the current module, an error value is returned:

NO DATE / TIME VALUE FOUND !

All the examples hereafter assume the date format “m/d/Y” and the time format “H:i” (PHP date function format).

To set the value of a AdvancedDatetime Field of the module, or to create a new AdvancedDatetime variable, the method setValue must be used. For example to change the value of the existing variable “Arrival” (that is supposed to be of sub-type Time in this example) to “01/21/2009 20:15” the code is:

$dtcm->setValue('Arrival', '01/21/2009 20:15');


Whereas to create a new TimeLength “Duration” variable of 132 min. and 15 sec. it is:

$dtcm->setValue('Duration', '132:15', 'lengthtime');


The last parameter 'lengthtime' could have been omitted in this case, and the sub-type would have been correctly assigned by the method:

$dtcm->setValue('Duration', '132:15');
/* Same result as the example before */


Calculate values from the existing ones

To perform calculations from the existing AdvancedDatetime fields, a set of methods is available in the AdvancedDatetimeOperation class.


To add a fixed value to a DateTime field, the addDate method can be used. For example if the existing field is named “MileStone” and 1 day is to be added to it and echoed to screen, the following code can be used :

$dtcm->setValue('AddingValue', '24:00:00');
$result = $dtcm->addDate('MileStone', 'AddingValue');
echo $dtcm->getValue($result);


Please note that $result does not contain the value itself, but the name of a new AdvancedDatetime variable that is automatically created and must be accessed to through the getValue method.

The previous code can be simplified by creating the AdvancedDatetime variables automatically:

echo $dtcm->getValue($dtcm->addDate('MileStone', '24:00')); 
/* Same result as the example before */


This is possible thanks to the capability to correctly guess the AdvancedDatetime sub-type (using the rules described in the AdvancedDatetime Values Sub-Paragraph).


Nested calculations are also allowed. For example, the difference between two DateTime variables (in the example FadeIn and FadeOut) can be added to a third DateTime (in the example Ciak).

echo $dtcm->getValue($dtcm->addDate(
    'Ciak', 
    $dtcm->subDate('FadeOut','FadeIn')
));

The following paragraph contains a complete reference on AdvancedDatetime methods.


AdvancedDatetimeOperations Method Reference

The following is a list of the available operators.


getValue

Synopsis:


field_value $dtcm->getValue (field_name)


Where :


    • field_value is the value of the field named field_name.
    • field_name is the name of the field to get the value.

Description:


Returns the value associated to the specified field_name. It can be used to retrieve the values of a AdvancedDatetime field of the module, or either a calculated field that has been automatically generated by a AdvancedDatetimeOperation method.


If no AdvancedDatetime field is associated to field_name, the following error value is returned:

NO DATE / TIME VALUE FOUND !


setValue

Synopsis:


void $dtcm->setValue (field_name, field_value[, field_sub_type])

Where :


Description:

The method can be used either to create a new AdvancedDatetime field named field_name with the initial value set to field_value, or to modify the value of an existing field.

The field_sub_type parameter is the sub-type of the field: it can be used to force the class to assign the sub-type to the field. If it is not specified, the application guesses the sub-type from the format of the initial value. If it cannot retrieve the sub-type from the format, the following error value is returned:

NO DATE / TIME VALUE FOUND !


addDate

Synopsis:

field_name $dtcm->addDate (dtc_value, dtc_length )

field_name $dtcm->addDate (dtc_value, array(dtc_length_1..dtc_length_n) )

Where :


Description:

Adds a value or a list of values of sub-type LenghtTime (possibly derived by a previous calculation) to any AdvancedDatetime field.

If the second parameter is not of sub-type LenghtTime, the following error value is returned:

DATE / TIME TYPE MISMATCH ERROR !


subDate

Synopsis:

field_name $dtcm->subDate (dtc_value1, dtc_value2)

Where :


Description:

Subtracts the value of the dtc_value2 (of any AdvancedDatetime sub-type) from the dtc_value1 .


floorDate

Synopsis:

field_name $dtcm->addDate (dtc_value, dtc_length )

Where :


Description:

Rounds down dtc_value to the highest multiple of dtc_length less than dtc_value. For example if dtc_value is equal to “21/12/2009 17:14” and dtc_length is “05:00”, it returns “21/12/2009 17:10”.

If the second parameter is not of sub-type LenghtTime, the following error value is returned:

DATE / TIME TYPE MISMATCH ERROR !


ceilDate

Synopsis:

field_name $dtcm->addDate (dtc_value, dtc_length )

Where :


Description:

Rounds up the dtc_value to the lowest multiple of dtc_length greater than dtc_value. For example if dtc_value is “21/12/2009 14:03” and dtc_length is “30:00”, it returns “21/12/2009 14:30”.

If the second parameter is not of sub-type LenghtTime, the following error value is returned:

DATE / TIME TYPE MISMATCH ERROR !


AdvancedDatetime Method Parameters Table

The following table shows the sub-types of the return value for each combination of input value of each method.


Field #2
DateTime
Time
LengthTime
Method
Field #1
addDate
DateTime
Type Mismatch Error
Type Mismatch Error
DateTime
Time
Type Mismatch Error
Type Mismatch Error
Time
LengthTime
Type Mismatch Error
Type Mismatch Error
LengthTime
subDate
DateTime
LengthTime
LengthTime
LengthTime
Time
LengthTime
LengthTime
LengthTime
LengthTime
LengthTime
LengthTime
LengthTime
floorDate
DateTime
Type Mismatch Error
Type Mismatch Error
DateTime
Time
Type Mismatch Error
Type Mismatch Error
Time
LengthTime
Type Mismatch Error
Type Mismatch Error
LengthTime
ceilDate
DateTime
Type Mismatch Error
Type Mismatch Error
DateTime
Time
Type Mismatch Error
Type Mismatch Error
Time
LengthTime
Type Mismatch Error
Type Mismatch Error
LengthTime
Navigation
dispage support
Toolbox