README.txt

   1
   2 DESCRIPTION
   3 -----------
   4
   5 Simplenews publishes and sends newsletters to lists of subscribers. Both
   6 anonymous and authenticated users can opt-in to different mailing lists.
   7 HTML email can be sent by adding Mime mail module.
   8
   9
  10 REQUIREMENTS
  11 ------------
  12
  13  * For large mailing lists, cron is required.
  14  * HTML-format newsletters and/or newsletters with file attachments require the
  15    mime mail or HMTL mail module.
  16  * When sending newsletters on regular cron (cron.php), it is important that
  17    the base url (settings.php, variable $base_url) is set correctly or links
  18    inside the newsletter will not work. See the Tips (13.) below.
  19  * Additionally when using Drush to start cron, it is important to use the
  20    argument --uri=http://www.example.com
  21
  22
  23 INSTALLATION
  24 ------------
  25
  26  1. CREATE DIRECTORY
  27
  28     Create a new directory "simplenews" in the sites/all/modules directory and
  29     place the entire contents of this simplenews folder in it.
  30
  31  2. ENABLE THE MODULE
  32
  33     Enable the module on the Modules admin page.
  34
  35  3. ACCESS PERMISSION
  36
  37     Grant the access at the Access control page:
  38       People > Permissions.
  39
  40  4. CONFIGURE SIMPLENEWS
  41
  42     Configure Simplenews on the Simplenews admin pages:
  43       Configuration > Simplenews.
  44
  45     Enable new content types to use as newsletter:
  46       Structure > edit content type > Publishing options
  47
  48     Add and configure newsletter categories:
  49       Structure > Web Services > Newsletters > Add newsletter category
  50       Structure > Web Services > Newsletters > edit newsletter category
  51
  52  5. ENABLE SIMPLENEWS BLOCK
  53
  54     With the Simplenews block users can subscribe to a newsletter.
  55
  56     Enable a Simplenews block per Newsletter category:
  57       Structure > Newsletters > edit newsletter category
  58
  59  6. CONFIGURE SIMPLENEWS BLOCK
  60
  61     Configure the Simplenews block on the Block configuration page. You reach
  62     this page from Block admin page (Structure > Blocks).
  63     Click the 'Configure' link of the appropriate simplenews block.
  64
  65     Permission "subscribe to newsletters" is required to view the subscription
  66     form in the simplenews block or to view the link to the subscription form.
  67
  68  7. SIMPLENEWS BLOCK THEMING
  69
  70     More control over the content of simplenews blocks can be achieved using
  71     the block theming. Theme your simplenews block by copying
  72     simplenews-block.tpl.php into your theme directory and edit the content.
  73     The file is self documented listing all available variables.
  74
  75     The newsletter block can be themed generally and per newsletter:
  76       simplenews-block.tpl.php (for all newsletters)
  77       simplenews-block.tpl--[tid].php (for newsletter series tid)
  78
  79  8. MULTILINGUAL SUPPORT
  80
  81     Simplenews supports multilingual newsletters for node translation,
  82     multilingual taxonomy and url path prefixes.
  83
  84     When translated newsletter issues are available subscribers receive the
  85     newsletter in their preferred language (according to account setting).
  86     Translation module is required for newsletter translation.
  87
  88     Multilingual taxonomy of 'Localized terms' and 'per language terms' is
  89     supported. 'per language vocabulary' is not supported.
  90     I18n-taxonomy module is required.
  91     Use 'Localized terms' for a multilingual newsletter. Taxonomy terms are
  92     translated and translated newsletters are each tagged with the same
  93     (translated) term. Subscribers receive the newsletter in the preferred
  94     language set in their account settings or in the site default language.
  95     Use 'per language terms' for mailing lists each with a different language.
  96     Newsletters of different language each have their own tag and own list of
  97     subscribers.
  98
  99     Path prefixes are added to footer message according to the subscribers
 100     preferred language.
 101
 102     The preferred language of anonymous users is set based on the interface
 103     language of the page they visit for subscription. Anonymous users can NOT
 104     change their preferred language. Users with an account on the site will be
 105     subscribed with the preferred language as set in their account settings.
 106
 107     The confirmation mails can be translated by enableding the Simplenews
 108     variables at:
 109       Home > Administration > Configuration > Regional and language > Multilingual settings > Variables
 110     Afterwards, the mail subject and body can be entered for every enabled
 111     language.
 112
 113 9.  NEWSLETTER THEMING
 114
 115     You can customize the theming of newsletters. Copy any of the *.tpl.php
 116     files from the simplenews module directory to your theme directory. Both
 117     general and by-newsletter theming can be performed.
 118     Theme newsletter body:
 119       simplenews-newsletter-body.tpl.php (for all newsletters)
 120       simplenews-newsletter-body--[tid].tpl.php
 121       simplenews-newsletter-body--[view mode].tpl.php
 122       simplenews-newsletter-body--[tid]--[view mode].tpl.php
 123
 124       [tid]: Machine readable name of the newsletter category
 125       [view mode]: 'email-plain', 'email-html', 'email-textalt'
 126       Example:
 127         simplenews-newsletter-body--1--email-plain.tpl.php
 128
 129     Theme newsletter footer:
 130       simplenews-newsletter-footer.tpl.php (for all newsletters)
 131       simplenews-newsletter-footer--[tid].tpl.php
 132       simplenews-newsletter-footer--[view mode].tpl.php
 133       simplenews-newsletter-footer--[tid]--[view mode].tpl.php
 134
 135       [tid]: Machine readable name of the newsletter category
 136       [view mode]: 'email-plain', 'email-html', 'email-textalt'
 137       Example:
 138         simplenews-newsletter-footer--1--email-plain.tpl.php
 139
 140     The template files are self documented listing all available variables.
 141     Depending on how the mails are sent (e.g. how cron is triggered), either the
 142     default or the admin theme might be used, if one has been configured.
 143     To prevent this, Simplenews supports the mail theme setting from the
 144     mailsystem module (http://drupal.org/project/mailsystem). Install it, choose
 145     the mail theme and the newsletter templates from that theme will be used no
 146     matter which other themes are enabled.
 147
 148     Using the fields Display settings each field of a simplenews newsletter can
 149     be displayed or hidden in 'plain text', 'HTML' and 'HTML text alternative'
 150     format. You find these settings at:
 151       Structure > Content types > Manage display
 152     Enable the view modes you want to configure and configure their display.
 153
 154 10. SEND MAILING LISTS
 155
 156     Cron is required to send large mailing lists.
 157     If you have a medium or large size mailing list (i.e. more than 500
 158     subscribers) always use cron to send the newsletters.
 159
 160     To use cron:
 161      * Check the 'Use cron to send newsletters' checkbox.
 162      * Set the 'Cron throttle' to the number of newsletters send per cron run.
 163        Too high values may lead to mail server overload or you may hit hosting
 164        restrictions. Contact your host.
 165
 166     Don't use cron:
 167      * Uncheck the 'Use cron to send newsletters' checkbox.
 168        All newsletters will be sent immediately when saving the node. If not
 169        all emails can be sent within the available php execution time, the
 170        remainder will be sent by cron. Therefore ALWAYS enable cron.
 171
 172     These settings are found on the Newsletter Settings page under
 173     'Send mail' options at:
 174       Administer > Configuration > Web Services > Newsletters > Settings > Send mail.
 175
 176 11. (UN)SUBSCRIBE CONFIRMATION
 177
 178     By default the unsubscribe link will direct the user to a confirmation page.
 179     Upon confirmation the user is directed to the home page, where a message
 180     will be displayed. On the Simplenews subscription admin page you can
 181     specify an alternative destination page.
 182       Structure > Configuration > Web Services > Newsletters > edit newsletter category > Subscription settings
 183
 184     To skip the confirmation page you can add parameters to the subscription URL.
 185       Example: [simplenews-subscribe-url]/ok
 186     When an alternative destination page has been defined the extra parameters
 187     will be added to the destination URL.
 188       Example: [simplenews-subscriber:subscribe-url]/ok
 189       Destination: node/123
 190       Destination URL: node/123/ok
 191
 192  12. SINGLE OR DOUBLE OPT-IN AND OPT-OUT
 193
 194     Every newsletter can be set to be double opt-in/out (default), single
 195     opt-in/out, or hidden.
 196
 197     Double: A confirmation email is sent to confirm the (un)subscribe action.
 198             No confirmation is sent when a user is (un)subscribed by the
 199             administrator or when the user subscribes when creating an account.
 200     Single: No confirmation email is sent. (un)subscribe is immediately.
 201     Hidden: The newsletter is not listed in newsletter lists. Use this for
 202     mandatory newsletters. Only administrators or modules can add a user to this
 203     mailing list.
 204
 205     Note that single opt-in/out or hidden (forced) subscription is in some
 206     countries forbidden by law.
 207
 208     SECURITY NOTICE: a newsletter set to be single opt-in or opt-out is
 209     vulnerable to Cross Site Request Forgeries. Email addresses may be
 210     (un)subscribed without a notice. Do not use this setting in uncontrolled
 211     environments (like the internet!).
 212
 213  13. TIPS
 214     A subscription page is available at: /newsletter/subscriptions
 215
 216     The Elysia Cron module (http://drupal.org/project/elysia_cron) can be used
 217     to start the simplenews cron hook more often than others, so that newsletter
 218     are sent faster without decreasing site performance due to long-running cron
 219     hooks.
 220
 221     If your unsubscribe URL looks like:
 222       http://newsletter/confirm/remove/8acd182182615t632
 223     instead of:
 224       http://www.example.com/newsletter/confirm/remove/8acd182182615t632
 225     You should change the base URL in the settings.php file from
 226       #  $base_url = 'http://www.example.com';  // NO trailing slash!
 227     to
 228       $base_url = 'http://www.example.com';  // NO trailing slash!
 229
 230
 231 RELATED MODULES
 232 ------------
 233
 234  * Elysia Cron
 235    Allows fine grained control over cron tasks.
 236    http://http://drupal.org/project/elysia_cron
 237  * Mailsystem
 238    Extends drupal core mailystem wirh Administrative UI and Developers API.
 239    http://drupal.org/project/mailsystem
 240  * Maillog
 241    Captures outgoing mails, helps users debugging simplenews.
 242    http://drupal.org/project/maillog
 243
 244
 245 DOCUMENTATION
 246 -------------
 247 More help can be found on the help pages: example.com/admin/help/simplenews
 248 and in the drupal.org handbook: http://drupal.org/node/197057