Integration With v2.0.0

MyAlerts version 2.0.0 (currently in active development) changes (and simplifies) the way developers integrate with MyAlerts. This guide will show the easiest way to get up and running with the system.

##Alert Types

###Adding an alert type

The first step to working with MyAlerts is to register your custom alert type. This should ideally be done in your plugin's installation routine, and reversed in the uninstallation routine.

Registering your alert type:

// First, get the instance of the alert type manager:
if (class_exists('MybbStuff_MyAlerts_AlertTypeManager')) {
	$alertTypeManager = MybbStuff_MyAlerts_AlertTypeManager::getInstance();

	if (!$alertTypeManager) {
		$alertTypeManager = MybbStuff_MyAlerts_AlertTypeManager::createInstance($db, $cache);
	}

	$alertType = new MybbStuff_MyAlerts_Entity_AlertType();
	$alertType->setCode('my_alert_type_code'); // The codename for your alert type. Can be any unique string.
	$alertType->setEnabled(true);
	$alertType->setCanBeUserDisabled(true);

	$alertTypeManager->add($alertType);
}

###Unregistering your alert type:

if (class_exists('MybbStuff_MyAlerts_AlertTypeManager')) {
	$alertTypeManager = MybbStuff_MyAlerts_AlertTypeManager::getInstance();

	if (!$alertTypeManager) {
		$alertTypeManager = MybbStuff_MyAlerts_AlertTypeManager::createInstance($db, $cache);
	}

	$alertTypeManager->deleteByCode('my_alert_type_code');
}

##Alert Formatters

An alert formatter is used to format the message shown for an alert type. Each alert type should have a formatter associated and registered.

###Create an alert formatter

Alert formatters are just classes that extend MybbStuff_MyAlerts_Formatter_AbstractFormatter. An example formatter is shown below.

/**
 * Alert formatter for my custom alert type.
 */
class MyCustomAlertFormmatter extends MybbStuff_MyAlerts_Formatter_AbstractFormatter
{
    /**
     * Format an alert into it's output string to be used in both the main alerts listing page and the popup.
     *
     * @param MybbStuff_MyAlerts_Entity_Alert $alert The alert to format.
     *
     * @return string The formatted alert string.
     */
    public function formatAlert(MybbStuff_MyAlerts_Entity_Alert $alert, array $outputAlert)
    {
        return $this->lang->sprintf(
            $this->lang->my_alert_type_lang_string,
            $outputAlert['from_user'],
            $outputAlert['dateline']
        );
    }

    /**
     * Init function called before running formatAlert(). Used to load language files and initialize other required
     * resources.
     *
     * @return void
     */
    public function init()
    {
        if (!$this->lang->my_custom_alert_type) {
            $this->lang->load('my_custom_alert_type');
        }
    }

    /**
     * Build a link to an alert's content so that the system can redirect to it.
     *
     * @param MybbStuff_MyAlerts_Entity_Alert $alert The alert to build the link for.
     *
     * @return string The built alert, preferably an absolute link.
     */
    public function buildShowLink(MybbStuff_MyAlerts_Entity_Alert $alert)
    {
        return get_profile_link($alert->getFromUserId());
    }
}

###Register an alert formatter

All alert formatters must be registered in order for alerts to be formatted. This should be done in the global_start hook so that the formatter is ready by the global_intermediate hook.

if (class_exists('MybbStuff_MyAlerts_AlertFormatterManager')) {
	$formatterManager = MybbStuff_MyAlerts_AlertFormatterManager::getInstance();

	if (!$formatterManager) {
		$formatterManager = MybbStuff_MyAlerts_AlertFormatterManager::createInstance($mybb, $lang);
	}

	$formatterManager->registerFormatter(
        new MyCustomAlertFormmatter($mybb, $lang, 'my_alert_type_code')
    );
}

##Alerts

Adding an alert

Once you're registered your alert type with the system, you can start adding new alerts for users. This is done very simply and transparently as follows. Alert type settings are checked automatically by the alert manager, as are duplicate alerts.

	/** @var MybbStuff_MyAlerts_Entity_AlertType $alertType */
    $alertType = MybbStuff_MyAlerts_AlertTypeManager::getInstance()->getByCode('my_alert_type_code');

    if ($alertType != null && $alertType->getEnabled()) {
    	/**
	     * Initialise a new Alert instance.
	     *
	     * @param int|array                                      $user     The ID of the user this alert is for.
	     * @param int|MybbSTuff_MyAlerts_Entity_AlertType|string $type     The ID of the object this alert is linked to.
	     *                                                                 Optionally pass in an AlertType object or the
	     *                                                                 short code name of the alert type.
	     * @param int                                            $objectId The ID of the object this alert is linked to. (eg: thread ID, post ID, etc.)
	     */
        $alert = new MybbStuff_MyAlerts_Entity_Alert($userToSendAlertTo, $alertType, 0);

        MybbStuff_MyAlerts_AlertManager::getInstance()->addAlert($alert);
    }

Closing

Note that none of this is fully finalised, and some isn't yet even written, but I don't expect the approach to change much if at all. If you have any questions, please feel free to contact me at MyBBStuff.