Notifications

This article assumes you have built a module or an extension which will use CartThrob's notifications settings to configure and manage email notification events for your your application. You should have a clear understanding of PHP, PHP Classes, and arrays, as well as a good working knowledge of CartThrob.

CartThrob has a notifications system that can be used to configure emails that will be sent based on event triggers. CartThrob includes its own internal triggers, which cause emails to be sent when those events occur. If you have your own application or extension, you can register a new custom email notification trigger with CartThrob's notifications system. You will use CartThrob's Notifications settings to manage your notifications, and your application will use CartThrob's email library to send those notifications when your event occurs.

Overview

To use the CartThrob notification system you must

  1. Register (install) an event with CartThrob (similar to registering an extension hook)
  2. You must then configure a notification in CartThrob's Notification System (setup email to/from, message content, etc)
  3. Your application must pull any notifications that have been configured and send them through CartThrob's systems.

Table of Contents

Installing an event

Sample code needed to install AND update notifications. Whatever you use, extension or module, you can use the following code in both the install AND the update process to register new and update existing notifications.

$this->EE =& get_instance();
// add the package path so we can access CT scripts & libraries
$this->EE->load->add_package_path(PATH_THIRD.'cartthrob/');
// load CT in. IMPORTANT!
$this->EE->load->library('cartthrob_loader');

$this->notification_events = array('my_notification_event','my_other_event'); 
// this does not have to be the same as the file name. It's arbitrary, make it say whatever you want.
// The module name will be used in the event registration list. For example: My_module:my_notification_event would show up in the notifications drop-down as a selectable event. 
$this->module_name = "The_name_of_your_module_or_extension"; 

/////////////// NOTIFICICATIONS /////////////////////////
if (!empty($this->notification_events))
{
    $this->EE->db->select('notification_event')
            ->from('cartthrob_notification_events')
            ->like('application', ucwords($this->module_name), 'after');

    $existing_notifications = array();

    foreach ($this->EE->db->get()->result() as $row)
    {
        $existing_notifications[] = $row->notification_event;
    }
    
    foreach ($this->notification_events as $event)
    {
        if (!empty($event))
        {
            if ( ! in_array($event, $existing_notifications))
            {
                $this->EE->db->insert(
                    'cartthrob_notification_events',
                    array(
                        'application' => ucwords($this->module_name),
                        'notification_event' => $event,
                    )
                );
            }
        }
    }
}

Configure a notification

See this section for more details on configuring notifications in the backend.

Send notifications

The following can be used in your application to find existing notifications for my_notification_event event

////////// We're only going to send emails for my_notification_event ////////////// 
// you could call any other event... or all events at once if you don't check for a specific event. 

$this->EE =& get_instance();
// add the package path so we can access CT scripts & libraries
$this->EE->load->add_package_path(PATH_THIRD.'cartthrob/');
// load CT in. IMPORTANT!
$this->EE->load->library('cartthrob_loader');
$this->EE->load->library('cartthrob_emails');

// make sure whatever you use here is the same module name you used when you installed the notifications. 
$this->module_name = "The_name_of_your_module_or_extension"; 

$emails = $this->EE->cartthrob_emails->get_email_for_event(ucwords($this->module_name."_".$event)); 
if (!empty($emails))
{
    foreach ($emails as $email_content)
    {
        /*
        // any variables that might be add to the TO or FROM email addresses (like {customer_email}) will need to be manually added here. 
        // they don't get magically pulled from the system. So if you don't know the person that will sending to or from, you'll need to
        // add that information yourself. 
        // you can var_dump($email_content) to see the array keys & their data that need to be manipulated if you need to set any dynamic data.
        
        // you can add your own custom variables that will be available in the notification by adding a "constants" array
        $email_content['constants'] = array(
            "{some_var}" => 'some val', 
            "{some_other_var}" => 'some other val'
            ); 
        */
        $this->EE->cartthrob_emails->send_email($email_content); 
    }
}

Uninstalling Events

If you have an uninstall method for your addon, use the following to remove your notifications. You don't have to remove them. If you don't remove them when you uninstall they will continue to be listed in the notification events settings.

// make sure whatever you use here is the same module name you used when you installed the notifications. 
$this->module_name = "The_name_of_your_module_or_extension"; 

$this->EE->db->delete('cartthrob_notification_events', array('class' => ucwords($this->module_name)));