#166 - Global tracking system

Let's kill the word 'tracking'. Instead we have 'notifications'. The 'track XXX'/'untrack XXX' buttons can become 'alerts OFF' and 'alerts ON' with tooltips that clearly explain that clicking the buttons change the state that is displayed on the buttons.

I'm not entirely sure about that, I don't like mixing state explanations with action text, it gets confusing. But I think it is less confusing than the term 'tracking' which people no longer understand, and there is limited space on the buttonface (we can't say "Disable notifications" on there).

Kill reported posts - just tie into staff messaging system
Tie report content addon into staff messaging system
Kill staff emails, instead staff can sign up to alerts in their notifications settings
Any kind of log_it call can also be signed up to for alert
Any kind of syndicate_described_activity call can also be signed up to for alert
Kill SMS support - people have smart phones now
Facebook/Twitter will be handled through the non-bundled activities addon [which provides the syndication service implementation], which tie into the non-bundled Facebook/Twitter addons
RSS feeds stay as they are, although an activities RSS feed will be added
Google Wave - Forget
IM or Growl alerts - If people want to route stuff to IM, they can set up some kind of email handler outside the scope of Composr
Calendar - Leave overlays as-is
Todo lists - Leave as-is
Implement consistent notifications support (formerly 'tracking'), for creation of e-mail alerts, through the system

Continuing to refine this. This will be a really important API in the future Composr, replacing a lot of hard-coded email dispatching and giving users and staff much more control.

It's not tracking now. It's not notifications now. It's alerts. We'll just talk about getting or stopping alerts. Dead simple and intuitive :).

Users will have a member settings tab that allows them to define what alert status to have for each kind of alert they are allowed to receive. This includes email, PT, digest email, SMS (yeah, decided to put this back again), etc.

Defined the API and exact TODO list to implement...


/*
Background details, to set the context and how we have structured things for consistency...

Alerts are one-off messages sent out in response to something happening on the site. They may get delivered via e-mail, etc.
Alerts may optionally create a message that staff might discuss, in which case a discussion link will be auto-appended to anyone having access to the admin_messaging module. This should be used sparingly - remember that any staff may raise such an alert by reporting some content, so it should only be particularly eventful stuff that spawns this.
People may get an RSS feed of alerts if they track via PT, as PTs have an RSS feed - that may then be connected to Growl, IM, or whatever service they may enjoy using (kind of quirky, but some power users enjoy this for the cool factor). It's good that we support the standards, without too much complexity.

There is a separate Composr action log, called via log_it. This is not related to the alerts system, although staff may choose an alert on anything added to the action log.
Similarly, there is the Composr activities syndication system. This is not related either, but again alerts may be generated through this.
The Admin Zone front page shows tasks. These are not the same thing as alerts, although alerts may have been sent when they were set up.

Any alerts are CC'd to the configured CC email address (if there is one). This is like having that address get alerts for everything, even if they shouldn't normally be able to receive that alert (i.e. was targeted to a specific member(s)). But it's not really considered parts of the alerts system.
*/

/**
* Standard code module initialisation function.
*/
function init__alerts()
{
// Alerts will be sent from one of the following if not a specific member ID
define('A_FROM_SYSTEM_UNPRIVILEGED',-3); // Sent from system (website itself) *without* dangerous Comcode permission
define('A_FROM_SYSTEM_PRIVILEGED',-2); // Sent from system (website itself) *with* dangerous Comcode permission

// Alerts will be sent to one of the following if not to a specific list of member IDs
define('A_TO_ANYONE_TRACKING',NULL);

define('A_NA',0x1); // Not applicable
define('A_INSTANT_EMAIL',0x2);
define('A_DAILY_EMAIL_DIGEST',0x4);
define('A_WEEKLY_EMAIL_DIGEST',0x8);
define('A_MONTHLY_EMAIL_DIGEST',0x10);
define('A_INSTANT_SMS',0x20);
define('A_INSTANT_PT',0x40); // Private topic (TODO: implement using nice alerts topic emoticon)
// And...
define('A__ALL',0xFFFFFF);
// And...
define('A__STATISTICAL',-1); // This is magic, it will choose whatever the user probably wants, based on their existing settings
}

function dispatch_alert(ID_TEXT $alert_code,?SHORT_TEXT $alert_code_category,SHORT_TEXT $subject,LONG_TEXT $message,?array $to_member_id,integer $from_member_id,$priority=3,$store_in_staff_messaging_system=false,$attachments=NULL,$no_cc=false)
{
// TODO: Implement
}

// TODO: Write API doc headers

/* TODO: Add all hooks with codes for
- each kind of content (can subscribe to a category in each, or the whole lot)
- ^ the old forum tracking is now just another kind of the above. Reimplement, kill old tables
- convert over each kind of existing mail_wrap call (some will still be directed to a list of members, some to a specific member, or some to all -- but each will be sent on a alert code)
- anything added to the action log
- anything generated syndicated actions
- when a new task is created on the Admin Zone front page checklist
- Whenever the adminzone is accessed
- Whenever a particular user logs on
- When a support ticket is posted to a certain category (this used to be hard-coded into ticket types, remove that)
- Extend the CEDI post tracking to also include page adding, and let anyone get alerts for it

Hooks will be defined as...

class Hook_trackable_X
{
function list_handled_codes() // Addons can define hooks that handle whole sets of codes, so hooks are written so they can take wide authority
{
return array(
array('SOME_ALERT_CODE','Some category','Some label'),
);
}

function supports_categories($alert_code) // Content types, for example, will define alerts on specific categories, not just in general. The categories are interpreted by the hook and may be complex. E.g. it might be like a regexp match, or like FORUM:3 or TOPIC:100
{
return true;
}

function allowed_settings($alert_code)
{
return A_ALL; // Returns a bit-mask
}

function get_initial_setting($alert_code,?SHORT_TEXT $category=NULL)
{
return A_NA;
}

function get_default_optin_setting($alert_code,?SHORT_TEXT $category=NULL)
{
return A__STATISTICAL;
}

function list_members_who_could_receive($alert_code,?SHORT_TEXT $category=NULL)
{
return array();
}

function list_members_who_would_receive($alert_code,?SHORT_TEXT $category=NULL)
{
return array();
}

function member_could_potentially_receive($alert_code,$member_id,?SHORT_TEXT $category=NULL) // If they are allowed to receive these alerts
{
}

function member_would_receive($alert_code,$member_id,?SHORT_TEXT $category=NULL) // If they are actually set to receive these alerts
{
}
}
*/

// TODO: Convert tracking addon to official alerts feature, and overhaul UI - will be a member setting alerts tab

// TODO: Remove Commandr notifications feature (it's now really redundant)

// TODO: Make sure references to e-mail are changed to alert where possible

// TODO: Must be careful to ensure new private topics do not create alerts that create new private topics (and so on)

// TODO: Any alert will be sent as email to the staff CC address, even if it did not actually get truly sent via email

// TODO: Put "get alerts"/"stop alerts" buttons all over Composr (used to be called track buttons)

// TODO: UI must not show options unavailable to them. E.g. if they do not have SMS setup (or site does not), it should not show as an option. Ditto if email address not set up.

// TODO: If SMS quota reached, goes to email instead, with a note explaining this

// TODO: Kill reported posts feature - just link through to standard reporting system (posts a staff message, and alerts to any staff wanting 'reported content' alerts), based on the current non-bundled addon