Developers

Triggers

Most of the examples below can be found on a plugin example on github.

Define a new trigger

Add a new trigger class, for example :

<?php

use Ryssbowh\CraftTriggers\Triggers;
use Ryssbowh\CraftTriggers\models\Trigger;
use craft\base\Element;
use craft\elements\Asset;
use craft\events\ModelEvent;
use yii\base\Event;

class AssetBeforeDeleted extends Trigger
{
    /**
     * @inheritDoc
     */
    public function getType(): string
    {
        return \Craft::t('triggers', 'Before an asset is deleted');
    }

    /**
     * @inheritDoc
     */
    public function getHandle(): string
    {
        return 'asset-before-deleted';
    }

    /**
     * @inheritDoc
     */
    public function initialize()
    {
        $_this = $this;
        Event::on(Asset::class, Element::EVENT_BEFORE_DELETE, function (ModelEvent $e) use ($_this) {
            Triggers::$plugin->triggers->onTriggerTriggered($_this, [
                'asset' => $e->sender
            ]);
        });
    }
}

You can define any number of attributes for your trigger and use them and validate them normally, they will automatically be added to project config and saved in database. You must not define the following attributes : id, uid, handle, type, name, active, triggered, dateCreated, dateUpdated, conditions, actions, config, data, instructions, tip.

Then register it :

use Ryssbowh\CraftTriggers\services\TriggersService;
use Ryssbowh\CraftTriggers\events\RegisterTriggersEvent;

Event::on(TriggersService::class, TriggersService::EVENT_REGISTER_TRIGGERS, function (RegisterTriggersEvent $e) {
    $e->add(new AssetBeforeDeleted);
});

You can define some configuration which will show on the add trigger form by defining those 2 methods on your trigger :

public function hasConfig(): bool
{
    return true;
}

/**
 * @inheritDoc
 */
public function configTemplate(): ?string
{
    return 'my-template';
}

You can show some instructions and/or tips to the user which would show on the add trigger form:

/**
 * @inheritDoc
 */
public function getInstructions(): string
{
    return 'These are instructions';
}

/**
 * @inheritDoc
 */
public function getTip(): string
{
    return 'This is a tip';
}

Modify triggers worflow

Trigger workflow can be changed at several times during its execution through events :

use Ryssbowh\CraftTriggers\services\TriggersService;
use Ryssbowh\CraftTriggers\events\RegisterTriggersEvent;

Event::on(TriggersService::class, TriggersService::EVENT_BEFORE_CHECKING_CONDITIONS, function (TriggerTriggeredEvent $e) {
    $e->handled = true; //This stops the execution entirely
    $e->triggerData['my-variable'] = 'my-value';
});

Event::on(TriggersService::class, TriggersService::EVENT_AFTER_CHECKING_CONDITIONS, function (TriggerTriggeredEvent $e) {
    //$e->result contains the result of conditions (true or false)
    $e->triggerData['my-variable'] = 'my-value';
});

//Those won't be executed if the result of conditions is false :

Event::on(TriggersService::class, TriggersService::EVENT_BEFORE_APPLYING_ACTIONS, function (TriggerTriggeredEvent $e) {
    $e->handled = true; //This stops the execution entirely
    $e->triggerData['my-variable'] = 'my-value';
});

Event::on(TriggersService::class, TriggersService::EVENT_AFTER_APPLYING_ACTIONS, function (TriggerTriggeredEvent $e) {
});

Conditions

Define new conditions

Add a new condition class, for example :

<?php

use Ryssbowh\CraftTriggers\interfaces\TriggerInterface;
use Ryssbowh\CraftTriggers\models\Condition;

class MyCondition extends Condition
{
    /**
     * @inheritDoc
     */
    public function getName(): string
    {
        return 'My Condition';
    }

    /**
     * @inheritDoc
     */
    public function getDescription(): string
    {
        return 'this is a new condition'
    }

    /**
     * @inheritDoc
     */
    public function getHandle(): string
    {
        return 'my-condition';
    }

    /**
     * @inheritDoc
     */
    public function hasConfig(): bool
    {
        return true;
    }

    /**
     * @inheritDoc
     */
    public function configTemplate(): string
    {
        return 'my-template';
    }

    /**
     * Return null for a global condition
     */
    protected function defineForTriggers(): ?array
    {
        return ['asset-saved', 'asset-deleted'];
    }

    /**
     * @inheritDoc
     */
    public function check(TriggerInterface $trigger, array $data): bool
    {
        if ($data['my-condition-is-met']) {
            return true;
        }
        return false;
    }
}

You can define any number of attributes for your condition and use them and validate them normally, they will automatically be added to project config and saved in database. You must not define the following attributes : id, uid, name, handle, order, operator, active, group_id, group, trigger_id, trigger, dateCreated, dateUpdated, config, data, description.

Then register it :

use Ryssbowh\CraftTriggers\services\TriggersService;
use Ryssbowh\CraftTriggers\events\RegisterTriggersEvent;

Event::on(TriggersService::class, TriggersService::EVENT_REGISTER_CONDITIONS, function (RegisterConditionsEvent $e) {
    $e->add(new MyCondition);
});

Modify which triggers a condition applies to

Triggers for which conditions apply are hard coded on the trigger class itself but can be modified through an event :

use Ryssbowh\CraftTriggers\events\DefineConditionTriggers;

Event::on(Mycondition::class, Mycondition::EVENT_DEFINE_FOR_TRIGGERS, function (DefineConditionTriggers $e) {
    $e->triggers[] = 'trigger-handle';
});

Actions

An action can do anything you want, it won't be executed if the conditions added to a trigger aren't met.

Define a new action

Create a new action class :

<?php

use Ryssbowh\CraftTriggers\models\Action;
use Ryssbowh\CraftTriggers\interfaces\TriggerInterface;

class MyAction extends Action
{
    /**
     * @inheritDoc
     */
    public function getName(): string
    {
        return 'My Action';
    }

    /**
     * @inheritDoc
     */
    public function getHandle(): string
    {
        return 'my-action';
    }

    /**
     * @inheritDoc
     */
    public function getDescription(): string
    {
        return 'This is an action that does nothing';
    }

    /**
     * @inheritDoc
     */
    public function hasConfig(): bool
    {
        return true;
    }

    /**
     * @inheritDoc
     */
    public function configTemplate(): ?string
    {
        return 'my-template';
    }

    /**
     * @inheritDoc
     */
    public function apply(TriggerInterface $trigger, array $data)
    {
        //Whatever you need to do here
    }
}

You can define any number of attributes for your action and use them and validate them normally, they will automatically be added to project config and saved in database. You must not define the following attributes : id, uid, name, handle, order, active, trigger_id, trigger, dateCreated, dateUpdated, config, data, description.

Then register it :

use Ryssbowh\CraftTriggers\services\TriggersService;
use Ryssbowh\CraftTriggers\events\RegisterActionsEvent;

Event::on(TriggersService::class, TriggersService::EVENT_REGISTER_ACTIONS, function (RegisterActionsEvent $e) {
    $e->add(new MyAction);
});