Using Events instead of methods

1. Register to an event within a class in order to execute some code in a callback method.
2. Enter the PHP code you want to execute in an object method.

itop_design version="3.1"

  <classes>
     <class id="UserRequest">
      <event_listeners>
        <event_listener id="HideTransitionsIfApprovalRule" _delta="define">
          <event>EVENT_ENUM_TRANSITIONS</event>
          <rank>10</rank>
          <callback>HideTransitionsIfApprovalRule</callback>
        </event_listener>
      </event_listeners>
      <methods>
        <method id="HideTransitionsIfApprovalRule" _delta="define">
          <comment>/**
            * If an approval rule could apply to the current object, hide all transitions
            * As the service and service subcategory are not yet set, we can't determine if the approval rule will really apply
            * So we hide all transitions if the object is new and in a state where an approval rule could apply
            */</comment>
          <static>false</static>
          <access>public </access>
          <code><![CDATA[public function HideTransitionsIfApprovalRule(Combodo\iTop\Service\Events\EventData $oEventData)
{
    // PHP code here...
}]]></ code>
        </method>
      </methods>

• Callback method receive an event in parameter, you may allow it to be null in the signature, to reuse the method

1. Register to an event outside of any class in order to execute some code,
2. provided that code outside of any class

Example from combodo-autodispatch-ticket

itop_design version="3.1"

    <event_listeners>
        <event_listener id="HideTransitionsIfAutoDispatchRule" _delta="define">
            <event>EVENT_ENUM_TRANSITIONS</event>
            <filters/>
            <rank>0</rank>
            <code><![CDATA[function(Combodo\iTop\Service\Events\EventData $oEventData)
{
    // PHP code to execute...
}
            ]]></ code>
        </event_listener>
    </event_listeners>

Register to this event in order to compute the value of field based on the values of other fields of the same object…

public function EvtComputeValues(Combodo\iTop\Service\Events\EventData $oEventData)
{         
        $this->Set('vat', 0.2*$this->Get('cost'));             
}

In previous versions of iTop and in some classes, you may encounter the method ComputeValues() which is deprecated and was performing the same job.

There are two different EVENTs, one before displaying the creation form and the other on displaying the modification form of a given class

public function EvtSetInitialAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
   $this->AddInitialAttributeFlags($sAttCode, $iFlags);
}
/* constant values for $iFlags to combine with bit operator |
 * OPT_ATT_NORMAL
 * OPT_ATT_HIDDEN
 * OPT_ATT_READONLY
 * OPT_ATT_MANDATORY
 * OPT_ATT_MUSTCHANGE
 * OPT_ATT_MUSTPROMPT
 */

public function EvtSetAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
   $this->AddAttributeFlags($sAttCode, $iFlags);
}

The methods GetAttributeFlags and GetInitialStateAttributeFlags which were performing the same job and can still be found on some classes in the Designer are deprecated and should no more be used.

This event is triggered just before an object is written in database.

• It allow to prevent recording the current object if certain conditions aren’t met
• It can also simply warn the user about non blocking issue.
• Adding a AddCheckIssue message in the callback method, will stop the object creation/modification/transition with an error message

  // A blocking issue
        $this->AddCheckIssue('Some message');
        // A non-blocking warning
        $this->AddCheckWarning('Some message');

It is too late to modify the object itself

Check UserRequest::DoCheckToWrite() in Designer, method doing the same job but deprecated.

If you want to modify the current object automatically, the right answer is usually EVENT_DB_COMPUTE_VALUES.

• If this change must only occur at object creation, use EVENT_DB_BEFORE_WRITE and test if you are in creation using

  $oEventData->Get('is_new') == $this->IsNew()

• If this update is resources intensive and should only be done if some field have been set/modified, then do it in an EVENT_DB_BEFORE_ WRITE after having checked the on-going changes:

  $this->ListChanges()

If you want to modify other objects automatically when a given object is modified. The event to use is EVENT_DB_AFTER_WRITE.

• It is triggered once after the current object is saved in DB
• Test if it was created with $oEventData→Get('is_new’)
• To checked the performed changes, use one or the other:

  $aChanges = $oEventData->Get('changes');
  $aChanges = $this->ListPreviousValuesForUpdatedAttributes();

Updating other objects from an EVENT_DB_BEFORE_WRITE expose you to the risk that an EVENT_DB_CHECK_TO_WRITE blocks the creation/update and so makes your propagated modification incoherent.

This event is triggered just before an object is displayed in a user Portal.

• It’s not design to act on what is displayed, but it allow you to count how many times a FAQ was displayed in the User Portal for eg. and maybe store this count within the FAQ object it-self.

This event is triggered on an object, after the modification of one of its LinkedSet flagged with « PHP computation ».

• It is not triggered if the host object it-self is modified
• It is not triggered if a PHP code update the LinkedSet of an object

$oObj->Set(‘xxxx_list’, $oSet); $oObj->DBUpdate();

• It is not triggered if the remote object of a LinkedSetIndirect is modified (eg. on a Team.persons_list, a change a status on Person)
• It is triggered if one sub-object inside the LinkedSetAttribute is added, remove or modified individually (either from the other side of the links or with the host object being in display mode)

During this execution of the callback, you don’t know:

• What has changed, not even which LinkedSet
• If the current object was just created or modified

Use-cases: It allows to be sure that as soon as a link is created, modified or deleted, your code is executed. It can be used for storing a count or sum of relations, reordering them, finding one relation having a particular value and storing it in the object as an ExternalKey.

Example: LinkedSet related values

This event is triggered just before an object is displayed.

• It allows to remove transitions from an object on some conditions.
• For example prevent a user other than the current agent to reassign a Ticket to another team.
• If you remove a transition which is not available it has no effect.

$this->DenyTransition($sTransitionCode)

This event is triggered on the object, just after an attachment is added to it.

• It allows to add an entry in the caselog or test constrains on the attachment and remove it automatically on some conditions (file types at risk for eg.)

$oEventData->Get('attachment')

Example: Add a log entry when an attachment is added