Index: sites/all/modules/simplenews/README.txt =================================================================== --- sites/all/modules/simplenews/README.txt (revision 186) +++ sites/all/modules/simplenews/README.txt (working copy) @@ -3,28 +3,32 @@ DESCRIPTION ----------- -This module sends html or plain text newsletters to the subscription list. In -the newsletter footer an unsubscribe link is provided. Subscription and -unsubscription are managed through a block, a form or by the newsletter -administrator on the module's admin pages. +This module enables the management, creation and sending of HTML and plain +text email newsletters to opt-in subscription lists. End-user subscription +management is offered through a registration block, through the user's own +account page, or through the unsubscribe link provide in the footer of every +mailed newsletter issue. -Individual newsletters are grouped in newsletters by a newsletter taxonomy term. -Newsletters can have a block with the ability of (un)subscription, listing of -recent newsletters and an associated rss-feed. +Newsletters issues are grouped into newsletters by a taxonomy term +representing the newsletter name. Each newsletter has a registration block +available extending subscription, unsubscription, an RSS feed link, and a +listing of recent newsletter issues. -Send newsletters and not-sent newsletters are listed separately. The -subscription list can be managed. +All newsletters, their sent/unsent status, and their respective subscription +lists are listed and easily managed on the module's admin page. There is a +facility for bulk import of email addresses. -Sending of large mailings can be managed by cron. +Please note that sending of large mailings requires setting up Drupal cron. + REQUIREMENTS ------------ * Drupal 6 * Taxonomy module * For large mailing lists, cron is required. - * HTML-format newsletters and/or newsletters with file attachments require the - mimemail module. + * HTML-formatted newsletters and/or sending of file attachments require the + mimemail module. INSTALLATION @@ -43,10 +47,10 @@ 3. ACCESS PERMISSION Grant the proper access to user accounts at the Access control page: - Administer > User management > Access control. + Administer > User management > Access control. To enable users to (un)subscribe to a newsletter use the "subscribe to newsletters" permission. This will enable the Simplenews block where the - user can (un)subscribe to a newsletter. + user can (un)subscribe to a newsletter. Use the "view links in block" permission to enable the display of previous newsletters in the Simplenews block. @@ -54,13 +58,12 @@ Enable the Simplenews block on the Administer blocks page: Administer > Site building > Blocks. - One block is available for each newsletter you have on the website. + One block is available for each newsletter you have on the website. 5. CONFIGURE SIMPLENEWS Configure Simplenews on the Simplenews admin pages: Administer > Content Management > Newsletters > Settings. - You can select the content type used by Simplenews for it's newsletters. Select the taxonomy term Simplenews uses to determine different newsletter series. @@ -68,46 +71,53 @@ 6. CONFIGURE SIMPLENEWS BLOCK Configure the Simplenews block on the Block configuration page. You reach - this page from Block admin page (Administer > Site building > Blocks). Click - the 'Configure' link of the appropriate simplenews block. - + this page from Block admin page (Administer > Site building > Blocks). + Click the 'Configure' link of the appropriate Simplenews block. + Permission "subscribe to newsletters" is required to view the subscription - form in the simplenews block or to view the link to the subscription form. - Links in the simplenews block (to previous issues, previous issues and + form in the Simplenews block or to view the link to the subscription form. + Links in the Simplenews block (to previous issues, previous issues and RSS-feed) are only displayed to users who have "view links in block" privileges. 7. SIMPLENEWS BLOCK THEMING - More control over the content of simplenews blocks is possible using the + More control over the content of Simplenews blocks is possible using the block theming. Additional variables are available for custom features: $block['subscribed'] is TRUE if user is subscribed to the newsletter $block['user'] is TRUE if the user is logged in (authenticated) $block['tid'] is the term id number of the newsletter - 8. Multilingual support - + 8. MULTILINGUAL SUPPORT + Simplenews supports multilingual newsletters for node translation, multilingual taxonomy and url path prefixes. - When translated newsletter issues are avialable subscribers revieve the - newsletter in their preferred language (according to account setting). - Translation module is required for newsletter translation. + * Node Translation: + When translated newsletter issues are available, subscribers receive the + newsletter in their preferred language (according to account setting). + Translation module is required for newsletter translation. - Multilingual taxonomy of 'Localized terms' and 'per language terms' is - supported. 'per language vocabulary' is not supported. - I18ntaxonomy module is required. - Use 'Localized terms' for a multilingual newsletter. Taxonomy terms are - translated and translated newsletters are each taged with the same - (translated) term. Subscribers reveive the newsletter in the preferred - language set in their account settings or in the site default language. - Use 'per language terms' for mailinglists each with a different language. - Newsletters of different language each have their own tag and own list of - subscribers. - - Path prefixes are added to footer message according to the subscribers - preferred language. + * Mulilingual Taxonomy: + The I18ntaxonomy module is required to enable taxonomy translations. + Only "localized terms" and "per language terms" are the only supported + modes for vocabulary translation; "set language to vocabulary" is NOT + supported. + Use "Localized terms" for a multilingual (ie translated) newsletter. + Each newsletter name (taxonomy term) is translated before-hand. Each new + newsletter issue (node) gets its translated term applied upon + translation from the original. Subscribers receive the newsletter + language set in their account settings or in the site default language. + + Use "per language terms" for untranslated, single-language newsletters. + Each newsletter in the system has its own language-dependent name + (taxonomy term) and its own list of subscribers. + + * Path Prefixes: + Path prefixes are added to footer message according to the subscribers + preferred language. + The preferred language of anonymous users is set based on the interface language of the page they visit for subscription. Anonymous users can NOT change their preferred language. Users with an account on the site will be @@ -117,48 +127,55 @@ A subscription page is available at: /newsletter/subscriptions + SEND NEWSLETTERS WITH CRON -------------------------- -Cron jobs are required to send large mailing lists. Cron jobs can be triggered -by Poormanscron or any other cron mechanisme such as crontab. -If you have a medium or large size mailinglist (i.e. more than 500 -subscribers) always use cron to send the newsletters. - -When you use cron: - * Check the 'Use cron to send newsletters' checkbox. - * Set the 'Cron throttle' to the number of newsletters send per cron run. - Too high values will lead to the warning message 'Attempting to re-run cron - while it is already running' - -When you do not use cron: - * Uncheck the 'Use cron to send newsletters' checkbox. - All newsletters will be send after saving a newsletter node with - 'Send newletter' selected. - -These settings are found on the Newsletter Settings page under - Mail backend options at: +Due to limitations on PHP script runtimes, an automated cron task is necessary +to send emails to large mailing lists. If your list has more than about 500 +subscribers, always use an automated cron scheduler to send the newsletters. +Automating Drupal cron may be done by Poormanscron module or through 'crontab' +on Unix-based servers. Read more about how to configure Drupal cron at: + http://drupal.org/cron/ + +Once cron is setup, you should configure Simplenews appropriately. + +Configure Simplenews to use cron on the Send mail page at: Administer > Content Management > Newsletters > Settings + (admin/settings/simplenews/mail) + * Enable the "Use cron to send newsletters" checkbox. Leaving this option + unchecked forces a newsletter issue to be sent upon saving in combination + with the "Send newsletter" option on the node edit/create page. If you + experience WSOD (White Screen Of Death) after clicking save, then your + mailing list is too long, and you should be using cron. + + * Set the "Cron throttle" value to the number of newsletters to send per cron + run. Setting this value too high may result in a warning message: + + "Attempting to re-run cron while it is already running" + + COLLABORATION WITH OTHER MODULES -------------------------------- * Taxonomy - The taxonomy module is required by Simplenews. Simplenews creates a - 'Newsletter' vocabulary which contains terms for each series of newsletters. - Each newsletter node is tagged with one of the terms to group it into one of - the newsletter series. + The Taxonomy module is required by Simplenews. Simplenews uses a vocabulary + "Newsletter" to enable the possibility for more than one newsletter. The + content type named "Newsletter issue" to represent actual newsletter nodes. + You must add a term to the Newsletter vocabulary for each desired newsletter + series you wish to make available. Each newsletter issue is classified with + one of the terms you created to group it into a newsletter series. - * Mimemail (Currently under development for 6.x) - By using Mimemail module simplenews can send HTML emails. Mime Mail takes - care of the MIME-encoding of the email. - Mime Mail is also required to be able to send emails with attachments, both - plain text and HTML emails. + * Mime Mail (Currently under development for 6.x) + Mime Mail handles MIME-encoding for complex emails (i.e., anything other + than just plain text). Simplenews integrates with the Mime Mail module to + send HTML emails and/or to send emails with file attachments. * Simplenews_template (Currently not available for 6.x) - Simplenews Template provides a themable template with configurable header, - footer and style. Header, footer and style are configurable for each - newsletter independently. + Simplenews Template adds the ability to customize email header text, footer + text and css styles within the admin interface. Each newsletter has its own + customizations options, editable in the newsletter term edit page. * Simplenews_roles (Currently not available for 6.x) A helper module for the Simplenews module which automatically populates a @@ -166,8 +183,9 @@ * Poormanscron Use Poormanscron if you don't have access to cron systems such as crontab. - Read the 'Send newsletters with Cron' remarks above. + See the section SEND NEWSLETTERS WITH CRON above. + CREDITS -------