diff --git a/README.txt b/README.txt index 3beb7c6..0e99fc3 100644 --- a/README.txt +++ b/README.txt @@ -3,7 +3,7 @@ DESCRIPTION ----------- Simplenews publishes and sends newsletters to lists of subscribers. Both -anonymous and authenticated users can opt-in to different mailing lists. +anonymous and authenticated users can opt-in to different mailing lists. HTML email can be sent by adding Mime mail module. @@ -35,19 +35,19 @@ INSTALLATION 3. ACCESS PERMISSION Grant the access at the Access control page: - People > Permissions. + People > Permissions. 4. CONFIGURE SIMPLENEWS Configure Simplenews on the Simplenews admin pages: - Configuration > Simplenews. + Configuration > Web Services > Newsletters. Enable new content types to use as newsletter: Structure > edit content type > Publishing options Add and configure newsletter categories: - Structure > Newsletters > Add newsletter category - Structure > Newsletters > edit newsletter category + Structure > Web Services > Newsletters > Add newsletter category + Structure > Web Services > Newsletters > edit newsletter category 5. ENABLE SIMPLENEWS BLOCK @@ -59,16 +59,16 @@ INSTALLATION 6. CONFIGURE SIMPLENEWS BLOCK Configure the Simplenews block on the Block configuration page. You reach - this page from Block admin page (Structure > Blocks). + 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 + More control over the content of simplenews blocks can be achieved using + the block theming. Theme your simplenews block by copying simplenews-block.tpl.php into your theme directory and edit the content. The file is self documented listing all available variables. @@ -77,7 +77,7 @@ INSTALLATION simplenews-block.tpl--[tid].php (for newsletter series tid) 8. MULTILINGUAL SUPPORT - + Simplenews supports multilingual newsletters for node translation, multilingual taxonomy and url path prefixes. @@ -95,7 +95,7 @@ INSTALLATION Use 'per language terms' for mailing lists 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. @@ -111,37 +111,44 @@ INSTALLATION general and by-newsletter theming can be performed. Theme newsletter body: simplenews-newsletter-body.tpl.php (for all newsletters) - simplenews-newsletter-body--[category machine name].tpl.php + simplenews-newsletter-body--[tid].tpl.php simplenews-newsletter-body--[view mode].tpl.php - simplenews-newsletter-body--[category machine name]--[view mode].tpl.php + simplenews-newsletter-body--[tid]--[view mode].tpl.php - [category machine name]: Machine readable name of the newsletter category - [view mode]: 'email_plain', 'email_html', 'email_textalt' + [tid]: Machine readable name of the newsletter category + [view mode]: 'email-plain', 'email-html', 'email-textalt' Example: - simplenews-newsletter-body--drupal--email_plain.tpl.php + simplenews-newsletter-body--1--email-plain.tpl.php Theme newsletter footer: simplenews-newsletter-footer.tpl.php (for all newsletters) - simplenews-newsletter-footer--[category machine name].tpl.php + simplenews-newsletter-footer--[tid].tpl.php simplenews-newsletter-footer--[view mode].tpl.php - simplenews-newsletter-footer--[category machine name]--[view mode].tpl.php + simplenews-newsletter-footer--[tid]--[view mode].tpl.php - [category machine name]: Machine readable name of the newsletter category - [view mode]: 'email_plain', 'email_html', 'email_textalt' + [tid]: Machine readable name of the newsletter category + [view mode]: 'email-plain', 'email-html', 'email-textalt' Example: - simplenews-newsletter-footer--drupal--email_plain.tpl.php + simplenews-newsletter-footer--1--email-plain.tpl.php 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 > Email + 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. Cron jobs can be triggered - by Poormanscron or any other cron mechanism such as crontab. + 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. @@ -159,7 +166,7 @@ INSTALLATION These settings are found on the Newsletter Settings page under 'Send mail' options at: - Administer > Site configuration > Simplenews > Send mail. + Administer > Configuration > Web Services > Newsletters > Settings > Send mail. 11. (UN)SUBSCRIBE CONFIRMATION @@ -167,13 +174,13 @@ INSTALLATION 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 > Newsletters > edit newsletter category > Subscription settings + 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-subscribe-url]/ok + Example: [simplenews-subscriber:subscribe-url]/ok Destination: node/123 Destination URL: node/123/ok @@ -215,6 +222,21 @@ INSTALLATION 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 diff --git a/simplenews.module b/simplenews.module index a0271bb..37bc061 100644 --- a/simplenews.module +++ b/simplenews.module @@ -2548,6 +2548,7 @@ function simplenews_theme() { 'language' => NULL, ), 'path' => $path . '/theme', + 'mail theme' => TRUE, ), 'simplenews_newsletter_footer' => array( 'variables' => array( @@ -2558,6 +2559,7 @@ function simplenews_theme() { 'language' => NULL, ), 'path' => $path . '/theme', + 'mail theme' => TRUE, ), 'simplenews_filter_form' => array( 'render element' => 'form', @@ -2712,8 +2714,9 @@ function theme_simplenews_field($variables) { * Process variables to format the simplenews newsletter body. * * $variables contains: - * - $node - * - $language + * - $node: newsletter node object + * - $language: language object + * - $simplenews_theme: path to the configured simplenews theme * * @see simplenews-newsletter-body.tpl.php * @see theme_simplenews_newsletter_body(). @@ -2723,6 +2726,9 @@ function template_preprocess_simplenews_newsletter_body(&$variables) { unset($variables['build']['links']); unset($variables['build']['comments']); + $theme = function_exists('mailsystem_get_mail_theme') ? mailsystem_get_mail_theme() : path_to_theme(); + $variables['simplenews_theme'] = drupal_get_path('theme', $theme); + $variables['title'] = check_plain($variables['build']['#node']->title); // Add specific suggestions that can override the default implementation. @@ -2749,7 +2755,7 @@ function theme_simplenews_newsletter_body($variables) { * - $node: newsletter node object * - $language: language object * - $key: email key [node|test] - + * - $simplenews_theme: path to the configured simplenews theme * * @see simplenews-newsletter-footer.tpl.php */ @@ -2758,6 +2764,9 @@ function template_preprocess_simplenews_newsletter_footer(&$variables) { unset($variables['build']['links']); unset($variables['build']['comments']); + $theme = function_exists('mailsystem_get_mail_theme') ? mailsystem_get_mail_theme() : path_to_theme(); + $variables['simplenews_theme'] = drupal_get_path('theme', $theme); + $variables['unsubscribe_text'] = t('Unsubscribe from this newsletter', array(), array('langcode' => $variables['language'])); $variables['test_message'] = t('This is a test version of the newsletter.', array(), array('langcode' => $variables['language'])); diff --git a/theme/simplenews-newsletter-body.tpl.php b/theme/simplenews-newsletter-body.tpl.php index a77df85..785c062 100644 --- a/theme/simplenews-newsletter-body.tpl.php +++ b/theme/simplenews-newsletter-body.tpl.php @@ -14,8 +14,7 @@ * Available variables: * - $build: Array as expected by render(). * - $title: Node title - * - $language: Language object - * - $view_mode: Active view mode. + * - $simplenews_theme: Contains the path to the configured simplenews theme. * * @see template_preprocess_simplenews_newsletter_body() * @see theme_simplenews_newsletter_body() diff --git a/theme/simplenews-newsletter-footer.tpl.php b/theme/simplenews-newsletter-footer.tpl.php index a51e7c3..fd58b6f 100644 --- a/theme/simplenews-newsletter-footer.tpl.php +++ b/theme/simplenews-newsletter-footer.tpl.php @@ -10,12 +10,13 @@ * * @todo Update the available variables. * Available variables: - * - $build: Array as expected by render(). + * - $build: Array as expected by render() * - $language: language object * - $key: email key [node|test] * - $format: newsletter format [plain|html] * - $unsubscribe_text: unsubscribe text * - $test_message: test message warning message + * - $simplenews_theme: path to the configured simplenews theme * * Available tokens: * - [simplenews-subscriber:unsubscribe-url]: unsubscribe url to be used as link