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  * Taxonomy module
  14  * For large mailing lists, cron is required.
  15  * HTML-format newsletters and/or newsletters with file attachments require the
  16    Mime Mail module or HTML Mail module.
  17
  18 INSTALLATION
  19 ------------
  20
  21  1. CREATE DIRECTORY
  22
  23     Create a new directory "simplenews" in the sites/all/modules directory and
  24     place the entire contents of this simplenews folder in it.
  25
  26  2. ENABLE THE MODULE
  27
  28     Enable the module on the Modules admin page:
  29       Administer > Site building > Modules
  30
  31  3. ACCESS PERMISSION
  32
  33     Grant the access at the Access control page:
  34       Administer > User management > Access control.
  35
  36  4. CONFIGURE SIMPLENEWS
  37
  38     Configure Simplenews on the Simplenews admin pages:
  39       Administer > Site configuration > Simplenews.
  40
  41     Select the content type Simplenews uses for newsletters.
  42     Select the taxonomy term Simplenews uses to manage newsletter series.
  43
  44  5. ENABLE SIMPLENEWS BLOCKS
  45
  46     With the Simplenews block users can subscribe to a newsletter. If you
  47     select the multi-signup block, you can subscribe to several newsletters at
  48     once. Otherwise, for each newsletter one block is available.
  49     Enable the Simplenews blocks on the Administer blocks page:
  50       Administer > Site building > Blocks.
  51
  52  6. CONFIGURE SIMPLENEWS BLOCKS
  53
  54     Configure the Simplenews blocks on the Block configuration page. You reach
  55     this page from Block admin page (Administer > Site building > Blocks).
  56     Click the 'Configure' link of the appropriate simplenews block.
  57
  58     Permission "subscribe to newsletters" is required to view the subscription
  59     form in the simplenews block or to view the link to the subscription form.
  60
  61  7. SIMPLENEWS BLOCK THEMING
  62
  63     More control over the content of simplenews blocks can be achieved using
  64     the block theming. Theme your simplenews block by copying
  65     simplenews-block.tpl.php into your theme directory and edit the content.
  66     The file is self documented listing all available variables.
  67
  68     The newsletter block can be themed generally and per newsletter:
  69       simplenews-block.tpl.php (for all newsletters)
  70       simplenews-block.tpl--[tid].php (for newsletter series tid)
  71
  72  8. MULTILINGUAL SUPPORT
  73
  74     Simplenews supports multilingual newsletters for node translation,
  75     multilingual taxonomy and url path prefixes.
  76
  77     When translated newsletter issues are available subscribers receive the
  78     newsletter in their preferred language (according to account setting).
  79     Translation module is required for newsletter translation.
  80
  81     Multilingual taxonomy of 'Localized terms' and 'per language terms' is
  82     supported. 'per language vocabulary' is not supported.
  83     I18n-taxonomy module is required.
  84     Use 'Localized terms' for a multilingual newsletter. Taxonomy terms are
  85     translated and translated newsletters are each tagged with the same
  86     (translated) term. Subscribers receive the newsletter in the preferred
  87     language set in their account settings or in the site default language.
  88     Use 'per language terms' for mailing lists each with a different language.
  89     Newsletters of different language each have their own tag and own list of
  90     subscribers.
  91
  92     To use multilingual confirmation you must use the String translation module.
  93     Enter confirmation email title and body in ENGLISH at:
  94       Administer > Site configuration > Simplenews > Subscription.
  95     If required refresh the Simplenews text group at:
  96       Administer > Site building > Translate interface > Refresh.
  97     Enter translations of title and body text at:
  98       Administer > Site building > Translate interface > Search.
  99
 100     Path prefixes are added to footer message according to the subscribers
 101     preferred language.
 102
 103     The preferred language of anonymous users is set based on the interface
 104     language of the page they visit for subscription. Anonymous users can NOT
 105     change their preferred language. Users with an account on the site will be
 106     subscribed with the preferred language as set in their account settings.
 107
 108 9.  NEWSLETTER THEMING
 109
 110     You can customize the theming of newsletters. Copy any of the *.tpl.php
 111     files from the simplenews module directory to your theme directory. Both
 112     general and by-newsletter theming can be performed.
 113     Theme newsletter body:
 114       simplenews-newsletter-body.tpl.php (for all newsletters)
 115       simplenews-newsletter-body--[tid].tpl.php (for newsletter series tid;
 116       where [tid] is replaced by the term id of the newsletter taxonomy term.
 117     Theme newsletter footer:
 118       simplenews-newsletter-footer.tpl.php (for all newsletters)
 119       simplenews-newsletter-footer--[tid].tpl.php (for newsletter series tid)
 120     The files are self documented listing all available variables.
 121
 122     Using the Display fields settings each field of a simplenews newsletter can
 123     be displayed or hidden in plain text and/or HTML newsletters. You find
 124     these settings at:
 125       admin/content/node-type/my-node-type/display
 126
 127
 128 10. SEND MAILING LISTS
 129
 130     Cron is required to send large mailing lists. Cron jobs can be triggered
 131     by Poormanscron or any other cron mechanism such as crontab.
 132     If you have a medium or large size mailing list (i.e. more than 500
 133     subscribers) always use cron to send the newsletters.
 134
 135     To use cron:
 136      * Check the 'Use cron to send newsletters' checkbox.
 137      * Set the 'Cron throttle' to the number of newsletters send per cron run.
 138        Too high values may lead to mail server overload or you may hit hosting
 139        restrictions. Contact your host.
 140
 141     Don't use cron:
 142      * Uncheck the 'Use cron to send newsletters' checkbox.
 143        All newsletters will be sent immediately when saving the node. If not
 144        all emails can be sent within the available php execution time, the
 145        remainder will be sent by cron. Therefore ALWAYS enable cron.
 146
 147     These settings are found on the Newsletter Settings page under
 148     'Send mail' options at:
 149       Administer > Site configuration > Simplenews > Send mail.
 150
 151  11. (UN)SUBSCRIBE CONFIRMATION
 152
 153     By default the unsubscribe link will direct the user to a confirmation page.
 154     Upon confirmation the user is directed to the home page, where a message
 155     will be displayed. On the Simplenews subscription admin page you can
 156     specify an alternative destination page.
 157       Administer > Site configuration > Simplenews > Subscription
 158     To skip the confirmation page you can add parameters to the subscription URL.
 159       Example: [simplenews-subscribe-url]/ok
 160     When an alternative destination page has been defined the extra parameters
 161     will be added to the destination URL.
 162       Example: [simplenews-subscribe-url]/ok
 163       Destination: node/123
 164       Destination URL: node/123/ok
 165
 166  12. SINGLE OR DOUBLE OPT-IN AND OPT-OUT
 167
 168     Every newsletter can be set to be double opt-in/out (default), single
 169     opt-in/out, or hidden.
 170
 171     Double: A confirmation email is sent to confirm the (un)subscribe action.
 172             No confirmation is sent when a user is (un)subscribed by the
 173             administrator or when the user subscribes when creating an account.
 174     Single: No confirmation email is sent. (un)subscribe is immediately.
 175     Hidden: The newsletter is not listed in newsletter lists. Use this for
 176     mandatory newsletters. Only administrators or modules can add a user to this
 177     mailing list.
 178
 179     Note that single opt-in/out or hidden (forced) subscription is in some
 180     countries forbidden by law.
 181
 182     SECURITY NOTICE: a newsletter set to be single opt-in or opt-out is
 183     vulnerable to Cross Site Request Forgeries. Email addresses may be
 184     (un)subscribed without a notice. Do not use this setting in uncontrolled
 185     environments (like the internet!).
 186
 187  13. TIPS
 188
 189     A subscription page is available at: /newsletter/subscriptions
 190
 191     If your unsubscribe URL looks like:
 192       http://newsletter/confirm/remove/8acd182182615t632
 193     instead of:
 194       http://www.mysite.org/newsletter/confirm/remove/8acd182182615t632
 195     You should change the base URL in the settings.php file from
 196       #  $base_url = 'http://www.example.com';  // NO trailing slash!
 197     to
 198       $base_url = 'http://www.mysite.org';  // NO trailing slash!
 199
 200 DOCUMENTATION
 201 -------------
 202 More help can be found on the help pages: example.com/admin/help/simplenews
 203 and in the drupal.org handbook: http://drupal.org/node/197057