glFusion Wiki

Site Tools


glfusion:development:subscription

Differences

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

Link to this comparison view

glfusion:development:subscription [2011/04/02 20:44]
glfusion:development:subscription [2016/07/16 19:39] (current)
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.
 +
 +
 +