Differences

This shows you the differences between two versions of the page.

Link to this comparison view

glfusion:development:subscription [2011/04/03 01:44] (current)
Mark created
Line 1: Line 1:
 +====== Subscription Notification System ======
 +The subscription and notification system provides a set of APIs that allow plugin to easily implement an email subscription to their content items. 
 +
 +The API is implemented as a set of PLG_ APIs.
 +
 +
 +**<fs medium>function PLG_subscribe( $type, $category, $id, $uid = 0, $cat_desc = <nowiki>''</nowiki>, $id_desc=<nowiki>''</nowiki> )</fs>**
 +
 +Subscribe user to notification feed for an item
 +
 +|$type  |This will be the plugin name when subscribing to a plugin notification. For example, Media Gallery could implement notificaitons for uploads to an album. \\ $type = to 'comment' for the comment subscription service  |
 +|$category  |Category can be used by the plugin if it needs to maintain additional information.  For example, for the comment subscriptions, $category will contain the comment type (article, filemgmt, staticpages).  The Forum plugin will use the $category field to store the Forum Category #.  |
 +|$id  |The ID of the item being tracked.  The comment notification would store the ID of the item being tracked, i.e.; story_id, filemgmt_fileid, album_id  |
 +|$uid  |User ID to subscribe - if 0 use the current user as defined in $_USER['uid']  |
 +|$id_desc  |A text description of the item ID, i.e.; Story Title, FileMgmt File Title, MG Album Title  |
 +|$category_description  |A text description of the category. The intent of this field is to remove the requirement to query the database each time the category description is needed; i.e.; notification emails, listing the subscription data.  |
 +
 +**NOTE**:  Plugins should wrap the subscribe call in their own function that handles other house keeping such as where to land (what page) after subscribing.  See public_html/comment.php - handlesubscribe() for an example.
 +
 +There are 3 $MESSAGE texts to assist with subscriptions:
 +
 +  $MESSAGE = array(
 +      518 => 'You must login to subscribe to a notification feed.',
 +      519 => 'You are already subscribed to this notification feed.',
 +      520 => 'You have been subscribed to this notification feed.',
 +  )
 +
 +
 +**<fs medium>function PLG_unsubscribe( $type, $category, $id, $uid = 0 )</fs>**
 +
 +Unsubscribe user from notification feed for an item
 +
 +|$type  |This will be the plugin name when unsubscribing to a plugin notification. For example, Media Gallery could implement notificaitons for uploads to an album.  \\ $type = 'comment' for the comment subscription service  |
 +|$category  |Category can be used by the plugin if it needs to maintain additional information.  For example, for the comment subscriptions, $category will contain the comment type (article, filemgmt, staticpages).  The Forum plugin will use the $category field to store the Forum Category #.  |
 +|$id  |The ID of the item being tracked.  The comment notification would store the ID of the item being tracked, i.e.; story_id, filemgmt_fileid, album_id  |
 +|$uid  |User ID to subscribe - if 0 use the current user as defined in $_USER['uid']  |
 +
 +**NOTE**:  Plugins should wrap the unsubscribe call in their own function that handles other house keeping such as where to land (what page) after unsubscribing.  See public_html/comment.php - handleunsubscribe() for an example.
 +
 +There is 1 $MESSAGE text to assist with unsubscriptions:
 +
 +  $MESSAGE = array(
 +      521 => 'You have been successfully un-subscribed from the notification feed.',
 +  )
 +
 +
 +**<fs medium>function PLG_isSubscribed( $type, $category, $id, $uid = 0 )</fs>**
 +
 +Check if user is subscribed to the item.
 +
 +|$type  |This will be the plugin name when unsubscribing to a plugin notification. For example, Media Gallery could implement notificaitons for uploads to an album.  \\ $type = 'comment' for the comment subscription service  |
 +|$category  |Category can be used by the plugin if it needs to maintain additional information.  For example, for the comment subscriptions, $category will contain the comment type (article, filemgmt, staticpages).  The Forum plugin will use the $category field to store the Forum Category #.  |
 +|$id  |The ID of the item being tracked.  The comment notification would store the ID of the item being tracked, i.e.; story_id, filemgmt_fileid, album_id  |
 +
 +
 +**<fs medium>function PLG_sendSubscriptionNotification( $type, $category, $post_id, $item_id, $uid )</fs>**
 +
 +Send notification emails to all subscribers.  Should be called after an item is saved.
 +
 +|$type |This will be the plugin name when subscribing to a plugin notification. For example, Media Gallery could implement notificaitons for uploads to an album. \\  $type = to 'comment' for the comment subscription service  |
 +|$category  |Category can be used by the plugin if it needs to maintain additional information.  For example, for the comment subscriptions, $category will contain the comment type (article, filemgmt, staticpages).  The Forum plugin will use the $category field to store the Forum Category #.  |
 +|$track_id  |The ID of the item being tracked.  The comment notification would store the ID of the item being tracked, i.e.; story_id, filemgmt_fileid, album_id  |
 +|$post_id  |This is the ID of the new item posted. For example, the comment subscription would set the comment ID to the $post_id field.  This allows the function to pull the actual content of the item posted.  |
 +
 +**NOTE**: This function expects the plugin to also define the following function:
 +
 +**<fs medium>plugin_subscription_email_format_PINAME ( $category, $track_id, $post_id, $uid )</fs>**
 +
 +|$category  |The category id  |
 +|$track_id  |Item being tracked (i.e.; story id)  |
 +|$post_id  |The post id - actual comment id or item posted id  |
 +|$uid  | The UID of the poster  |
 +
 +This function will return an array containing a formatted HTML email and a TEXT formatted email body and an attached image (optional).
 +
 +**ALL EMAILS SHOULD CONTAIN A LINK FOR THE USER TO UNSUBSCRIBE**
 +
 +see lib-comment.php - plugin_subscription_email_format_comment() for an example
 +
 +
 +====== Subscription Management ======
 +
 +A new tab has been added to the My Account Section called 'Subscriptions'. This provides a single list of all subscriptions a user has.  It also allows them to delete any descriptions they no longer want to receive.
 +
 +====== COM_emailNotification() ======
 +
 +I have also implemented a new COM_emailNotification() function
 +
 +This function tries to be a little more friendly to the host's email system. Instead of sending a separate email to each user, it loads upto 25 users into the BCC field and then sends the single email.  It will loop through the list sending in batches of 25.
 +
 +This function expects the following array items to be present:
 +
 +  msgDate = array(
 +    'subject' => 'subject of email',
 +    'htmlmessage' => 'HTML formatted email body',
 +    'textmessage' => 'TEXT formatted email body',
 +    'imageData'   => array(
 +                       'file' => full path / filename to image,
 +                       'name' => name referenced in email body,
 +                       'filename' => filename of image,
 +                       'encoding' => encoding (generally base64),
 +                       'mime' => mime type (i.e.; image/jpeg )
 +                     )
 +    'from' => array('email','name'),
 +    'to'   => array of to addresses which can be an array of ('email','name')
 +  );
 +
 +====== Example Implementation ======
 +
 +The subscription system has been implemented into the Media Gallery plugin.  The following modification were made to Media Gallery:
 +
 +**<fs medium>subscription.php</fs>**
 +
 +subscription.php is a separate PHP file that handles user requests to subscribe or unsubscribe to album upload notification.   All notification emails contain a link to subscription.php that allows the user to easily unsubscribe if they wish.
 +
 +Links within the album to subscribe or unsubscribe also call subscription.php.  subscription.php has a feature to pull the referring URL so it can redirect back to that URL after it has performed the requested function.
 +
 +<code>
 +    $referer = isset($_SERVER['HTTP_REFERER']) ? $_SERVER['HTTP_REFERER'] : $_CONF['site_url'];
 +    if ( $referer == '' ) {  // if no referer use site url
 +        $referer = $_CONF['site_url'];
 +    }
 +    // validation check to ensure the referer is from this site
 +    $sLength = strlen($_CONF['site_url']);
 +    if ( substr($referer,0,$sLength) != $_CONF['site_url'] ) {
 +        $referer = $_CONF['site_url'];
 +    }
 +    // determine separator based on any parameters in the URL
 +    $hasargs = strstr( $referer, '?' );
 +    if ( $hasargs ) {
 +        $sep = '&amp;';
 +    } else {
 +        $sep = '?';
 +    }
 +</code>    
 +
 +**<fs medium>Implement Subscribe / Unsubscribe Links</fs>**
 +
 +The album display code (album.php) was modified to add a new template variable to subscribe or unsubscribe.  It first checks to see if the user is logged in, then calls **PLG_isSubscribed()** to determine if the user has already subscribed to this album.  It will then display the appropriate link.
 +
 +<code>
 +$subscribe = '';
 +if ( !COM_isAnonUser() ) {
 +    if ( PLG_isSubscribed('mediagallery','',$album_id,$_USER['uid']) ) {
 +        $subscribe = '<a class="subscribelink" href="'.$_MG_CONF['site_url'].'/subscription.php?op=unsubscribe&amp;sid='.$album_id.'">'.$LANG01['unsubscribe'].'</a>';
 +    } else {
 +        $subscribe = '<a class="subscribelink" href="'.$_MG_CONF['site_url'].'/subscription.php?op=subscribe&amp;sid='.$album_id.'">'.$LANG01['subscribe'].'</a>';
 +    }
 +}
 +$T->set_var('subscribe', $subscribe);
 +</code>
 +
 +**<fs medium>Implement PLG_sendSubscriptionNotification() Call</fs>**
 +
 +Modify the media upload code to call **PLG_sendSubscriptionNotification()** once a media item has been uploaded to an album.  **PLG_sendSubscriptionNotification()** will then check to see if there are any subscriptions for this album and send the emails.
 +
 +**<fs medium>Implement plugin_subscription_email_format_mediagallery()</fs>**
 +
 +The **plugin_subscription_email_format_mediagallery()** function is responsible for creating the actual email content that will be send to each user.  This function returns an array of 3 items:
 +
 +  * HTML formatted message
 +  * TEXT formatted message
 +  * Embedded Image Data (optional)
 +
 +**<fs medium>That's It!</fs>**
 +
 +Once all the steps above are completed, the plugin now has full subscription and notification support.
 +
 +
 +
  
glfusion/development/subscription.txt · Last modified: 2011/04/03 01:44 by Mark
 
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3