HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


Downloads Follow-up Email support

Login / Search

 [ Join | More ]
 Add topic 
Posted
Item has a rating of 5 (Liked by Chris GrahamLiked by FletchLiked by DuckLiked by Jean)  
Rating:
#99535 (In Topic #19560)
Avatar

Community saint

This topic contains additional documentation and support for the Downloads Follow-up Email addon.

Download: HERE

The addon has been tested on ocPortal v9.0.7 and v9.0.8 but should work on any 9.x.x version, and I suspect it would also work on v8 but that hasn't been tested. You can install it automatically in any ocPortal v9.x version from the Admin Zone.  Go to Admin Zone->Structure->Addons and scroll to the bottom of that page and click the Import non-bundled addon(s) link. From the Import non-bundled addon(s) page, select the Download radio button, expand the New Features category and there you can select the Downloads Follow-up Email addon.

Source files are in the ocPortal github repository in the V9 branch and includes the following files:

Code


  - lang_custom/EN/downloads_followup_email.ini
  - sources_custom/hooks/systems/cron/downloads_followup_email.php
  - sources_custom/hooks/systems/notifications/downloads_followup_email.php
  - themes/default/templates_custom/DOWNLOADS_FOLLOWUP_EMAIL.tpl
  - themes/default/templates_custom/DOWNLOADS_FOLLOWUP_EMAIL_DOWNLOAD_LIST.tpl
​​​​​​

Planned future enhancements: Make the cron interval and backlog interval times configurable, option to send one notification per download or combine all dowloads into one notification, if sending one notification per download then add an option to limit the maximum number of notifications a member could receive in one day, and possibly add an option to define a list of download categories that the member cannot disable notifications for.

Quickstart/General Overview:
This addon adds follow-up email functionality to the ocPortal Downloads module. This addon requires you to have the Downloads module installed and also have cron_bridge.php properly running via a cronjob or some other method. See http://ocportal.com/docs/tut_configuration.htm#title__11 for more information on setting up cron_bridge.php. By default this addon will scan your download_logging database table for downloads for approximately the past 24 hours and send a follow-up email to each member that has downloaded any files. Members can enable, disable, or change the notification type and also do it on a per-category basis from their Profile page->Edit tab->Notifications tab and making the desired changes to the Downloads follow-up email notification in the Content section of the Notifications tab. Admins can force the follow-up emails and/or private topics and prevent the members from changing the settings by making the necessary changes in the Admin Zone->Setup->Notification Lock-down->Downloads follow-up email in the Content section. 
 
The Language downloads_followup_email.ini File:
The email/topic subject is configured in the downloads_followup_email.ini file (located in the lang_custom/EN directory). This text string has some special variables that you can include to customize the subject to your liking. {1} is replaced with your site name, {2} is replaced with the user name of the member the notification is addressed to, and {3} is either blank or is 's' (without the quotes) to allow you to pluralize based on the download count included in the notification, so if the download count is 1, {3} is blank, and if the download count is greater than 1, {3} is s. I don't believe I have the addon properly coded for full language awareness. You can translate the .ini file to the another language and drop it in the approriate lang_custom subdirectory. If you run a multi-language site, the notification name in the Profile Notifications tab will properly translate for your members. But I don't think it will translate in any other language other than the site default language for the notification message subject. And the notification message body is moved from the language .ini file into templates, so that limits the message body to a single language as well. If there is a dire need for multi-language subjects and templates, post a reply here with the request and I may add that in an update. WARNING: If you edit this .ini file, it will be replaced and your changes will be wiped out if you update to a new version of the addon in the future. Make your changes and then save a backup copy of your changes. I will try to work a language file _CUSTOM override into the next version like I did for the templates (see below) so you won't have to keep re-editing after every update.
 
The Templates:
The main body of the message is contained in the DOWNLOADS_FOLLOWUP_EMAIL.tpl template. The formatting of the download list is also templated and is contained in the DOWNLOADS_FOLLOWUP_EMAIL_DOWNLOAD_LIST.tpl. Since this is a non-bundled addon, the templates are already in the templates_custom directory and may not be overridable without the risk of your changes being overwritten if the addon is updated in the future. I accounted for this by allowing a _CUSTOM override template. Simply make a copy of the existing templates and add _CUSTOM to the base file name (like this: DOWNLOADS_FOLLOWUP_EMAIL_CUSTOM.tpl and DOWNLOADS_FOLLOWUP_EMAIL_DOWNLOAD_LIST_CUSTOM.tpl) and then you can edit these without the risk of losing your changes with future updates. The download list template is embedded into the main body template which is embedded into either MAIL.tpl for emails and (I think) OCF_NOTIFICATION.tpl for private topic notifications. Since the included templates are embedded in a parent template for the notification, care needs to be taken when using HTML within the DOWNLOADS_FOLLOWUP_EMAIL templates. Tempcode and comcode should work within the included templates, however, since the templates are processed by a cronjob there may be some tempcode or comcode that is user-specific that won't work. But I do pass the member id number of the member the current notification is being generated for into the DOWNLOADS_FOLLOWUP_EMAIL.tpl so it can be used for any user-specific tempcode or comcode that accepts a member id number. The following three variables are passed into the DOWNLOADS_FOLLOWUP_EMAIL.tpl:

Code


{MEMBER_ID} : This is the member id number for the member the current notification is for.
{DOWNLOAD_COUNT} : This is the total number of downloads that will be listed in the notification.
{DOWNLOAD_LIST} : This is the full list that is generated using the DOWNLOADS_FOLLOWUP_EMAIL_DOWNLOAD_LIST.tpl.

The {DOWNLOAD_COUNT} variable is currently used to select plural vs. non-plural wording. The {DOWNLOAD_LIST} variable is generated using the DOWNLOADS_FOLLOWUP_EMAIL_DOWNLOAD_LIST.tpl template which also has three variables passed to it:

Code


{DOWNLOAD_NAME} : This is the readable text name of the download.
{DOWNLOAD_FILENAME} : This is the filename of the download.
{DOWNLOAD_URL} : This is the URL to the download page of the download.
 
Troubleshooting/Debug Mode:
There is some debug code embedded in the cron hook that can be enabled/disabled through the OcCLE that will dump out some relevant variables. In the OcCLE, enter :set_value('downloads_followup_email_debug','1'); to enable debug mode 1, :set_value('downloads_followup_email_debug','2'); to enable debug mode 2, or :set_value('downloads_followup_email_debug','0'); to disable debug mode. Debug mode is off by default and it is highly recommended to keep it disabled if you have a high traffic download site. When enabling debug mode you have two enabling modes available. Debug mode 1 will keep the 24 hour schedule and simply dump out a couple of lines of debug data with each cron_bridge run and full data when the 24 hour cycle restarts. Debug mode 2 should only be used for realtime testing and manually running cron_bridge.php for debugging and shouldn't be used long term as it will likely irritate members by possibly sending multiple emails per day. Debug mode 2 cuts the 24 hour cycle down to 36 seconds so you can initiate a download or manually manipulate a download in the download_logging database table and then manually run cron_bridge.php (at as little as 36 second intervals) to see what it's doing. WARNING: don't run cron_bridge.php manually unless you have properly set it up with a cronjob or are running it via some other method on a regular schedule (again, see http://ocportal.com/docs/tut_configuration.htm#title__11 for setting up a schedule).

Important note: The logging function of the downloads module only logs the first download a user makes to a file, so subsequent downloads that user makes to that file won't be logged. In other words, if you download file A.zip today for the first time, then you will get a download follow-up notification. If you download file A.zip again a month from now, the logging function knows you have already downloaded it before and won't log it again so you won't get another follow-up notification for that file. If I extend this addon further, I may make this a configurable option so subsequent downloads at least have the timestamp updated so another notification can be sent.

One final note...with a new installation, this addon won't send out a flood of notifications going back to the beginning of the download log. The very first time it runs it will restrict notifications to user downloads in the log that are less than 48 hours old. Each time after, it will look back to the time the cron hook last ran which should be approximately 24 hours depending on how often you run cron_bridge.php, but will not go back more than 48 hours. That means, if you uninstall the addon and reinstall it at a later time or if there is a cronjob or cron_bridge failure that stops this cron hook from running for more than two days, when it does get reinstalled or starts working again, it will restrict notifications to user downloads in the log that are less than 48 hours old.


Last edit: by Jason Verhagen
Back to the top
 
Posted
Rating:
#99537
Avatar

Community saint

Nice job Jason, and comprehensive as usual :thumbs:

Do you have a Samsung Galaxy S / Galaxy S II ? If so, why not check out my ScreenFree FM Radio .
Back to the top
 
Posted
Rating:
#99874
Avatar

Community saint

OK, major bug fix. If you installed this addon, you will want to install the update to fix a major bug :$

The download_list was initialized outside the main notification loop and not reset for each run through the loop, so the download list would get longer and longer each run through the loop.

The code is updated on github and a new version is uploaded to the addons download area so it should now be available from your Admin Zone->Structure->Addons page as an update as well.
Back to the top
 
There are too many online users to list.
Control functions:
 Add topic 

Quick reply   Contract

Your name:
Your message: