Kevin Carwile

ECA Extension Guide - Adding Events, Conditions & Actions


By adding a rules extension to your application, you will allow users to automate features of your application using rules, and tie your application into customized workflows created by the client. Here are the basic steps to add your own ECA’s to rules. If you already have an application in development, then you will likely skip steps 2 and 3.

1.       Install the IPS Rules or IPS Rules LITE application to your site

2.       Enable developer mode on your IPS4 site

3.       Create a new application

4.       Go to the “Developer center” for your application

5.       Go to the “Extensions” tab in the developer center

6.       Click the “rules” extensions list

7.       Click the icon to add a new extension (give it a relevant ExtensionClassName )

Quote

ECA's = Events, Conditions, & Actions

New ECA’s are added using the IPS4 extensions framework. This way your ECA’s are available if the user has the rules application installed, but adds no additional overhead if the user does not.

Definitions Extensions

A definition extension is used to add new events, conditions, and actions which are specific to your application. One extension can be used for all of your ECA’s, or you can split ECA’s up across multiple extension classes. When an ECA is used, only the extension class that it is located in needs to be loaded. So if you are implementing a large amount of ECA’s, there will be a performance benefit of splitting them up across multiple extensions.

Conversions Extensions

A conversion extension is used to make additional arguments available for configuration in rules based on available event arguments. For example, a conversion definition may tell rules how to derive the total number of achievements a user has when the \IPS\Member object is available.

Adding Events

By triggering an event in your application code, end users will be able to create rules that take actions in response to that event. To add an event to rules, follow these steps.

1.  Create an event trigger somewhere in your application code:

if ( \IPS\Application::appIsEnabled( rules ) )
{
    \IPS\rules\Event::load( myapp’, ExtensionClassName’, event_key )->trigger( $arg1, $arg2 );
}

2.       Add the event details to the events() method in your extension class:

public function events()
{
       $events = array(
              event_key => array(
                     arguments => array(
                           arg1 => array(
                                  argtype => int
                           ),
                           arg2 => array(
                                  argtype => string
                           ),
                     ),
              ),
       );

       return $events;
}

3.       Create language strings for the event (and any arguments sent by your event) in your lang.php file.

$lang = array(

    '{myapp}_{ExtensionClassName}_event_{event_key}' => 'Event description',
    '{myapp}_{ExtensionClassName}_event_{event_key}_{arg1}' => 'Argument description',
    
);

Adding Conditions

By adding conditions to your rules extension, end users will be able to perform conditional tests in their rules related to your application.

1.       Add the condition details to the conditions() method in your extension class. You will provide the name of a callback function that returns a TRUE/FALSE value, and a description of the arguments which should be passed to that callback function.

public function conditions()
{
       $conditions = array(
              condition_key => array(
                     callback => array( $this, callbackMethod ),
                     arguments => array(
                           member => array(
                                  argtype => object’,
                                  class => \IPS\Member’,
                                  required => TRUE,
                           ),
                     ),
              ),
       );
       
       return $conditions;
}

2.       Add the condition callback function to your extension class:

public function callbackMethod( $member )
{
       if ( ! $member instanceof \IPS\Member )
       {
              throw new \UnexpectedValueException( Invalid member object );
       }
       
       /* Return result from your conditional check */
       return $member->posts > 0;
}

3.  Create language strings for the condition (and any arguments used by your condition callback) in your lang.php file.

$lang = array(

    '{myapp}_{ExtensionClassName}_conditions_{condition_key}' => 'Condition description',
    '{myapp}_{ExtensionClassName}_conditions_{condition_key}_{arg1}' => 'Argument description',

);

Adding Actions

By adding actions to your rules extension, end users will be able to perform operations related to your application in an automated way through the rules they configure.

1.       Add the action details to the actions() method in your extension class. You will provide the name of a callback function that will perform the action, and a description of the arguments which should be passed to that callback function.

public function actions()
{
       $actions = array(
              action_key => array(
                     callback => array( $this, actionCallback ),
                     arguments => array(
                           member => array(
                                  argtype => object’,
                                  class => \IPS\Member’,
                                  required => TRUE,
                           ),
                           'title' => array(
                                  'argtype' => 'string',
                           ),
                     ),
              ),
       );

       return $actions;
}

2.       Add the action callback function to your extension class:

public function actionCallback( $member, $title )
{
       if ( ! $member instanceof \IPS\Member )
       {
              throw new \UnexpectedValueException( Invalid member object );
       }

       $member->member_title = $title;
       $member->save();

       return "member title updated";

}

3.  Create language strings for the condition (and any arguments used by your condition callback) in your lang.php file.

$lang = array(

    '{myapp}_{ExtensionClassName}_actions_{action_key}' => 'Action description',
    '{myapp}_{ExtensionClassName}_actions_{action_key}_{arg1}' => 'Argument description',
    
);

  • Like 1
  Report Article


User Feedback


There are no comments to display.