You are here

README.txt in Simplenews 3.x

DESCRIPTION
-----------

Simplenews publishes and sends newsletters to lists of subscribers. Both
anonymous and authenticated users can opt-in to different mailing lists.
HTML email can be sent by adding Mime mail module.


REQUIREMENTS
------------

 * For large mailing lists, cron is required.
 * HTML-format newsletters and/or newsletters with file attachments require the
   mime mail or HMTL mail module.
 * When sending newsletters on regular cron (cron.php), it is important that
   the base url (settings.php, variable $base_url) is set correctly or links
   inside the newsletter will not work. See the Tips (13.) below.
 * Additionally when using Drush to start cron, it is important to use the
   argument --uri=http://www.example.com


INSTALLATION
------------

 1. CREATE DIRECTORY

    Create a new directory "simplenews" in the sites/all/modules directory and
    place the entire contents of this simplenews folder in it.

 2. ENABLE THE MODULE

    Enable the module on the Modules admin page.

 3. ACCESS PERMISSION

    Grant the access at the Access control page:
      People > Permissions.

 4. CONFIGURE SIMPLENEWS

    Configure Simplenews on the Simplenews admin pages:
      Configuration > Simplenews.

    Enable new content types to use as newsletter:
      Structure > edit content type > Publishing options

    Add and configure newsletter categories:
      Structure > Web Services > Newsletters > Add newsletter category
      Structure > Web Services > Newsletters > edit newsletter category

 5. ENABLE SIMPLENEWS BLOCK

    With the Simplenews block users can subscribe to a newsletter.

    Enable a Simplenews block per Newsletter category:
      Structure > Newsletters > edit newsletter category

 6. CONFIGURE SIMPLENEWS BLOCK

    Configure the Simplenews block on the Block configuration page. You reach
    this page from Block admin page (Structure > 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.

 7. SIMPLENEWS BLOCK THEMING

    More control over the content of simplenews blocks can be achieved using
    the block theming. Theme your simplenews block by copying
    simplenews-block.html.twig into your theme directory and edit the content.
    The file is self documented listing all available variables.

    The newsletter block can be themed generally and per newsletter:
      simplenews-block.html.twig (for all newsletters)
      simplenews-block.tpl--[tid].php (for newsletter series tid)

 8. MULTILINGUAL SUPPORT

    Simplenews supports multilingual newsletters for node translation and url
    path prefixes.

    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.

    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
    subscribed with the preferred language as set in their account settings.

    The confirmation mails can be translated by enableding the Simplenews
    variables at:
      Home > Administration > Configuration > Regional and language > Multilingual settings > Variables
    Afterwards, the mail subject and body can be entered for every enabled
    language.

9.  NEWSLETTER THEMING

    You can customize the theming of newsletters. Copy the file
    simplenews-newsletter-body.html.twig from the simplenews module directory
    to your theme directory. Both general and by-newsletter theming can
    be performed.

      simplenews-newsletter-body.html.twig (for all newsletters)
      simplenews-newsletter-body--[newsletter_id].html.twig
      simplenews-newsletter-body--[view mode].html.twig
      simplenews-newsletter-body--[newsletter_id]--[view mode].html.twig

      [newsletter_id]: Machine readable name of the newsletter category
      [view mode]: 'email-plain', 'email-html'
      Example:
        simplenews-newsletter-body--1--email-plain.html.twig

    The template files are self documented listing all available variables.
    Depending on how the mails are sent (e.g. how cron is triggered), either the
    default or the admin theme might be used, if one has been configured.
    To prevent this, Simplenews supports the mail theme setting from the
    mailsystem module (http://drupal.org/project/mailsystem). Install it, choose
    the mail theme and the newsletter templates from that theme will be used no
    matter which other themes are enabled.

    Using the fields Display settings each field of a simplenews newsletter can
    be displayed or hidden in 'plain text', 'HTML' and 'HTML text alternative'
    format. You find these settings at:
      Structure > Content types > Manage display
    Enable the view modes you want to configure and configure their display.

10. SEND MAILING LISTS

    Cron is required to send large mailing lists.
    If you have a medium or large size mailing list (i.e. more than 500
    subscribers) always use cron to send the newsletters.

    To 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 may lead to mail server overload or you may hit hosting
       restrictions. Contact your host.

    Don't use cron:
     * Uncheck the 'Use cron to send newsletters' checkbox.
       All newsletters will be sent immediately when saving the node. If not
       all emails can be sent within the available php execution time, the
       remainder will be sent by cron. Therefore ALWAYS enable cron.

    These settings are found on the Newsletter Settings page under
    'Send mail' options at:
      Administer > Configuration > Web Services > Newsletters > Settings > Send mail.

11. (UN)SUBSCRIBE CONFIRMATION

    By default the unsubscribe link will direct the user to a confirmation page.
    Upon confirmation the user is directed to the home page, where a message
    will be displayed. On the Simplenews subscription admin page you can
    specify an alternative destination page.
      Structure > Configuration > Web Services > Newsletters > edit newsletter category > Subscription settings

    To skip the confirmation page you can add parameters to the subscription
    URL.
      Example: [simplenews-subscribe-url]/ok
    When an alternative destination page has been defined the extra parameters
    will be added to the destination URL.
      Example: [simplenews-subscriber:subscribe-url]/ok
      Destination: node/123
      Destination URL: node/123/ok

 12. ACCESS

    Every newsletter has an 'access' setting that determines whether subscribe
    and unsubscribe are available on newsletter forms.

    Default: Any user with 'Subscribe to newsletters' permissions can subscribe
      and unsubscribe.
    Hidden: Subscription is mandatory or handled programmatically by adding
      manual code.

    Note that mandatory subscription is restricted by law in some countries.

    Moreover, note that subscribers can be added to the spool of a newsletter
    issue through "Recipient Handlers" (missing documentation - see code in
    RecipientHandlerInterface and examples in the demo sub-module) even when
    subscribers don't have a subscription to the newsletter type corresponding
    to the issue. This can be useful for the newsletter types with access set
    to 'hidden'. Note that manual recipient handling is separate from manual
    subscription handling — these are two separate concepts!

 13. TIPS
    A subscription page is available at: /newsletter/subscriptions

    The Elysia Cron module (http://drupal.org/project/elysia_cron) can be used
    to start the simplenews cron hook more often than others, so that newsletter
    are sent faster without decreasing site performance due to long-running cron
    hooks.

    If your unsubscribe URL looks like:
      http://newsletter/confirm/remove/8acd182182615t632
    instead of:
      http://www.example.com/newsletter/confirm/remove/8acd182182615t632
    You should change the base URL in the settings.php file from
      #  $base_url = 'http://www.example.com';  // NO trailing slash!
    to
      $base_url = 'http://www.example.com';  // NO trailing slash!


RELATED MODULES
------------

 * Elysia Cron
   Allows fine grained control over cron tasks.
   http://http://drupal.org/project/elysia_cron
 * Mailsystem
   Extends drupal core mailystem wirh Administrative UI and Developers API.
   http://drupal.org/project/mailsystem
 * Maillog
   Captures outgoing mails, helps users debugging simplenews.
   http://drupal.org/project/maillog


DOCUMENTATION
-------------
More help can be found on the help pages: example.com/admin/help/simplenews
and in the drupal.org handbook: http://drupal.org/node/197057

File

README.txt
View source
  1. DESCRIPTION
  2. -----------
  3. Simplenews publishes and sends newsletters to lists of subscribers. Both
  4. anonymous and authenticated users can opt-in to different mailing lists.
  5. HTML email can be sent by adding Mime mail module.
  6. REQUIREMENTS
  7. ------------
  8. * For large mailing lists, cron is required.
  9. * HTML-format newsletters and/or newsletters with file attachments require the
  10. mime mail or HMTL mail module.
  11. * When sending newsletters on regular cron (cron.php), it is important that
  12. the base url (settings.php, variable $base_url) is set correctly or links
  13. inside the newsletter will not work. See the Tips (13.) below.
  14. * Additionally when using Drush to start cron, it is important to use the
  15. argument --uri=http://www.example.com
  16. INSTALLATION
  17. ------------
  18. 1. CREATE DIRECTORY
  19. Create a new directory "simplenews" in the sites/all/modules directory and
  20. place the entire contents of this simplenews folder in it.
  21. 2. ENABLE THE MODULE
  22. Enable the module on the Modules admin page.
  23. 3. ACCESS PERMISSION
  24. Grant the access at the Access control page:
  25. People > Permissions.
  26. 4. CONFIGURE SIMPLENEWS
  27. Configure Simplenews on the Simplenews admin pages:
  28. Configuration > Simplenews.
  29. Enable new content types to use as newsletter:
  30. Structure > edit content type > Publishing options
  31. Add and configure newsletter categories:
  32. Structure > Web Services > Newsletters > Add newsletter category
  33. Structure > Web Services > Newsletters > edit newsletter category
  34. 5. ENABLE SIMPLENEWS BLOCK
  35. With the Simplenews block users can subscribe to a newsletter.
  36. Enable a Simplenews block per Newsletter category:
  37. Structure > Newsletters > edit newsletter category
  38. 6. CONFIGURE SIMPLENEWS BLOCK
  39. Configure the Simplenews block on the Block configuration page. You reach
  40. this page from Block admin page (Structure > Blocks).
  41. Click the 'Configure' link of the appropriate simplenews block.
  42. Permission "subscribe to newsletters" is required to view the subscription
  43. form in the simplenews block or to view the link to the subscription form.
  44. 7. SIMPLENEWS BLOCK THEMING
  45. More control over the content of simplenews blocks can be achieved using
  46. the block theming. Theme your simplenews block by copying
  47. simplenews-block.html.twig into your theme directory and edit the content.
  48. The file is self documented listing all available variables.
  49. The newsletter block can be themed generally and per newsletter:
  50. simplenews-block.html.twig (for all newsletters)
  51. simplenews-block.tpl--[tid].php (for newsletter series tid)
  52. 8. MULTILINGUAL SUPPORT
  53. Simplenews supports multilingual newsletters for node translation and url
  54. path prefixes.
  55. When translated newsletter issues are available subscribers receive the
  56. newsletter in their preferred language (according to account setting).
  57. Translation module is required for newsletter translation.
  58. Path prefixes are added to footer message according to the subscribers
  59. preferred language.
  60. The preferred language of anonymous users is set based on the interface
  61. language of the page they visit for subscription. Anonymous users can NOT
  62. change their preferred language. Users with an account on the site will be
  63. subscribed with the preferred language as set in their account settings.
  64. The confirmation mails can be translated by enableding the Simplenews
  65. variables at:
  66. Home > Administration > Configuration > Regional and language > Multilingual settings > Variables
  67. Afterwards, the mail subject and body can be entered for every enabled
  68. language.
  69. 9. NEWSLETTER THEMING
  70. You can customize the theming of newsletters. Copy the file
  71. simplenews-newsletter-body.html.twig from the simplenews module directory
  72. to your theme directory. Both general and by-newsletter theming can
  73. be performed.
  74. simplenews-newsletter-body.html.twig (for all newsletters)
  75. simplenews-newsletter-body--[newsletter_id].html.twig
  76. simplenews-newsletter-body--[view mode].html.twig
  77. simplenews-newsletter-body--[newsletter_id]--[view mode].html.twig
  78. [newsletter_id]: Machine readable name of the newsletter category
  79. [view mode]: 'email-plain', 'email-html'
  80. Example:
  81. simplenews-newsletter-body--1--email-plain.html.twig
  82. The template files are self documented listing all available variables.
  83. Depending on how the mails are sent (e.g. how cron is triggered), either the
  84. default or the admin theme might be used, if one has been configured.
  85. To prevent this, Simplenews supports the mail theme setting from the
  86. mailsystem module (http://drupal.org/project/mailsystem). Install it, choose
  87. the mail theme and the newsletter templates from that theme will be used no
  88. matter which other themes are enabled.
  89. Using the fields Display settings each field of a simplenews newsletter can
  90. be displayed or hidden in 'plain text', 'HTML' and 'HTML text alternative'
  91. format. You find these settings at:
  92. Structure > Content types > Manage display
  93. Enable the view modes you want to configure and configure their display.
  94. 10. SEND MAILING LISTS
  95. Cron is required to send large mailing lists.
  96. If you have a medium or large size mailing list (i.e. more than 500
  97. subscribers) always use cron to send the newsletters.
  98. To use cron:
  99. * Check the 'Use cron to send newsletters' checkbox.
  100. * Set the 'Cron throttle' to the number of newsletters send per cron run.
  101. Too high values may lead to mail server overload or you may hit hosting
  102. restrictions. Contact your host.
  103. Don't use cron:
  104. * Uncheck the 'Use cron to send newsletters' checkbox.
  105. All newsletters will be sent immediately when saving the node. If not
  106. all emails can be sent within the available php execution time, the
  107. remainder will be sent by cron. Therefore ALWAYS enable cron.
  108. These settings are found on the Newsletter Settings page under
  109. 'Send mail' options at:
  110. Administer > Configuration > Web Services > Newsletters > Settings > Send mail.
  111. 11. (UN)SUBSCRIBE CONFIRMATION
  112. By default the unsubscribe link will direct the user to a confirmation page.
  113. Upon confirmation the user is directed to the home page, where a message
  114. will be displayed. On the Simplenews subscription admin page you can
  115. specify an alternative destination page.
  116. Structure > Configuration > Web Services > Newsletters > edit newsletter category > Subscription settings
  117. To skip the confirmation page you can add parameters to the subscription
  118. URL.
  119. Example: [simplenews-subscribe-url]/ok
  120. When an alternative destination page has been defined the extra parameters
  121. will be added to the destination URL.
  122. Example: [simplenews-subscriber:subscribe-url]/ok
  123. Destination: node/123
  124. Destination URL: node/123/ok
  125. 12. ACCESS
  126. Every newsletter has an 'access' setting that determines whether subscribe
  127. and unsubscribe are available on newsletter forms.
  128. Default: Any user with 'Subscribe to newsletters' permissions can subscribe
  129. and unsubscribe.
  130. Hidden: Subscription is mandatory or handled programmatically by adding
  131. manual code.
  132. Note that mandatory subscription is restricted by law in some countries.
  133. Moreover, note that subscribers can be added to the spool of a newsletter
  134. issue through "Recipient Handlers" (missing documentation - see code in
  135. RecipientHandlerInterface and examples in the demo sub-module) even when
  136. subscribers don't have a subscription to the newsletter type corresponding
  137. to the issue. This can be useful for the newsletter types with access set
  138. to 'hidden'. Note that manual recipient handling is separate from manual
  139. subscription handling — these are two separate concepts!
  140. 13. TIPS
  141. A subscription page is available at: /newsletter/subscriptions
  142. The Elysia Cron module (http://drupal.org/project/elysia_cron) can be used
  143. to start the simplenews cron hook more often than others, so that newsletter
  144. are sent faster without decreasing site performance due to long-running cron
  145. hooks.
  146. If your unsubscribe URL looks like:
  147. http://newsletter/confirm/remove/8acd182182615t632
  148. instead of:
  149. http://www.example.com/newsletter/confirm/remove/8acd182182615t632
  150. You should change the base URL in the settings.php file from
  151. # $base_url = 'http://www.example.com'; // NO trailing slash!
  152. to
  153. $base_url = 'http://www.example.com'; // NO trailing slash!
  154. RELATED MODULES
  155. ------------
  156. * Elysia Cron
  157. Allows fine grained control over cron tasks.
  158. http://http://drupal.org/project/elysia_cron
  159. * Mailsystem
  160. Extends drupal core mailystem wirh Administrative UI and Developers API.
  161. http://drupal.org/project/mailsystem
  162. * Maillog
  163. Captures outgoing mails, helps users debugging simplenews.
  164. http://drupal.org/project/maillog
  165. DOCUMENTATION
  166. -------------
  167. More help can be found on the help pages: example.com/admin/help/simplenews
  168. and in the drupal.org handbook: http://drupal.org/node/197057