Improved documentation and dropped support for the "template" tab of the module settings page. (6c046384) · Commits · project / htmlmail

README.html

0 → 100644

+213 −0

Original line number	Diff line number	Diff line
		<div id="html-mail"
		><h2
		>HTML Mail</h2
		><p
		>HTML Mail lets you theme your outgoing messages the same way you theme the rest of your website.</p
		><p
		>For a full description of the module, visit the <a href="http://drupal.org/project/htmlmail"
		>project page</a
		>.</p
		><p
		>To submit bug reports and feature suggestions, visit the <a href="http://drupal.org/project/issues/htmlmail"
		>issue queue</a
		>.</p
		></div
		><div id="requirements"
		><h2
		>Requirements</h2
		><p
		>HTML Mail requires the <a href="http://drupal.org/project/mailsystem"
		>Mail System</a
		> module.</p
		></div
		><div id="installation"
		><h2
		>Installation</h2
		><p
		>Install as usual; see <a href="http://drupal.org/node/895232"
		>Installing contributed modules (Drupal 7)</a
		> for further information.</p
		><p
		>The following additional modules, while not required, are highly recommended:</p
		><ul
		><li
		><p
		><a href="http://drupal.org/project/emogrifier"
		>Emogrifier</a
		></p
		></li
		><li
		><p
		><a href="http://drupal.org/project/pathologic"
		>Pathologic</a
		></p
		></li
		><li
		><p
		><a href="http://drupal.org/project/transliteration"
		>Transliteration</a
		></p
		><p
		><em
		>Requires a <a href="http://drupal.org/node/1095278#comment-4219530"
		>patch</a
		>.</em
		></p
		></li
		></ul
		></div
		><div id="theming"
		><h2
		>Theming</h2
		><p
		>The email message text goes through four transformations before sending:</p
		><ol style="list-style-type: decimal;"
		><li
		><p
		>The <em
		>Text format pre-filter</em
		> from the module settings page is applied. This should be the same text format that your website uses for contributed content such as comments or blog postings. For consistency and security, it should include the the <a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_htmlcorrector/7"
		>Correct faulty and chopped off HTML</a
		> from <a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/7"
		>filter.module</a
		>, or a better replacement such as <a href="http://drupal.org/project/htmlpurifier"
		>HTML Purifier</a
		> or <a href="http://drupal.org/project/htmlawed"
		>htmLawed</a
		>.</p
		></li
		><li
		><p
		>A theme template is applied. The default template is the included <em
		>htmlmail.tpl.php</em
		> file. You may copy this file to your theme directory and use it to customize the contents and formatting of your emails. The comments within the file contain complete documentation on its usage.</p
		></li
		><li
		><p
		>The message may be wrapped in a website theme selected on the module settings page. Creating an email-specific theme lets you use the full power of the <a href="http://drupal.org/documentation/theme"
		>drupal theme system</a
		> to format your emails.</p
		></li
		><li
		><p
		>The <em
		>Text format post-filter</em
		> from the module settings page is applied. For best results, this should be an email-specific input format containing the following text format filters:</p
		><ul
		><li
		><a href="http://drupal.org/node/1095278#comment-4219530"
		>Transliteration</a
		></li
		><li
		><a href="http://drupal.org/project/emogrifier"
		>Emogrifier</a
		></li
		><li
		><a href="http://drupal.org/project/pathologic"
		>Pathologic</a
		></li
		><li
		><a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_htmlcorrector/7"
		>Correct faulty and chopped off HTML</a
		></li
		></ul
		></li
		></ol
		></div
		><div id="related-modules"
		><h2
		>Related Modules</h2
		><dl
		><dt
		>Emogrifier</dt
		><dd
		><p
		>http://drupal.org/project/emogrifier</p
		></dd
		><dt
		>HTML Mail</dt
		><dd
		><p
		>http://drupal.org/project/htmlmail</p
		></dd
		><dt
		>HTML Purifier</dt
		><dd
		><p
		>http://drupal.org/project/htmlpurifier</p
		></dd
		><dt
		>htmLawed</dt
		><dd
		><p
		>http://drupal.org/project/htmlawed</p
		></dd
		><dt
		>Mail System</dt
		><dd
		><p
		>http://drupal.org/project/mailsystem</p
		></dd
		><dt
		>Pathologic</dt
		><dd
		><p
		>http://drupal.org/project/pathologic</p
		></dd
		><dt
		>Transliteration</dt
		><dd
		><p
		>http://drupal.org/project/transliteration</p
		></dd
		></dl
		></div
		><div id="documentation"
		><h2
		>Documentation</h2
		><dl
		><dt
		>filter.module</dt
		><dd
		><p
		>http://api.drupal.org/api/drupal/modules--filter--filter.module/7</p
		></dd
		><dt
		>Installing contributed modules (Drupal 7)</dt
		><dd
		><p
		>http://drupal.org/node/895232</p
		></dd
		><dt
		>Theming guide</dt
		><dd
		><p
		>http://drupal.org/documentation/theme</p
		></dd
		><dt
		>Standard filters</dt
		><dd
		><p
		>http://api.drupal.org/api/drupal/modules--filter--filter.module/group/standard_filters/7</p
		></dd
		></dl
		></div
		><div id="maintainers"
		><h2
		>Maintainers</h2
		><ul
		><li
		><p
		><a href="http://drupal.org/user/1171"
		>Chris Herberte</a
		></p
		></li
		><li
		><p
		><a href="http://drupal.org/user/36148"
		>Bob Vincent</a
		></p
		></li
		></ul
		></div
		>

README.markdown

0 → 100644

+106 −0

Original line number	Diff line number	Diff line
		## HTML Mail

		HTML Mail lets you theme your outgoing messages the same way you theme the rest
		of your website.

		For a full description of the module, visit the
		[project page](http://drupal.org/project/htmlmail).

		To submit bug reports and feature suggestions, visit the
		[issue queue](http://drupal.org/project/issues/htmlmail).

		## Requirements

		HTML Mail requires the [Mail System](http://drupal.org/project/mailsystem)
		module.

		## Installation

		Install as usual; see
		[Installing contributed modules (Drupal 7)](http://drupal.org/node/895232)
		for further information.

		The following additional modules, while not required, are highly recommended:

		* [Emogrifier](http://drupal.org/project/emogrifier)

		* [Pathologic](http://drupal.org/project/pathologic)

		* [Transliteration](http://drupal.org/project/transliteration)

		Requires a [patch](http://drupal.org/node/1095278#comment-4219530).

		## Theming

		The email message text goes through four transformations before sending:

		1. The Text format pre-filter from the module settings page is applied.
		This should be the same text format that your website uses for contributed
		content such as comments or blog postings. For consistency and security,
		it should include the the
		[Correct faulty and chopped off HTML](http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_htmlcorrector/7)
		from [filter.module](http://api.drupal.org/api/drupal/modules--filter--filter.module/7), or a better replacement such as
		[HTML Purifier](http://drupal.org/project/htmlpurifier) or
		[htmLawed](http://drupal.org/project/htmlawed).

		2. A theme template is applied. The default template is the included
		htmlmail.tpl.php file. You may copy this file to your theme directory
		and use it to customize the contents and formatting of your emails. The
		comments within the file contain complete documentation on its usage.

		3. The message may be wrapped in a website theme selected on the module settings
		page. Creating an email-specific theme lets you use the full power of the
		[drupal theme system](http://drupal.org/documentation/theme) to format your
		emails.

		4. The Text format post-filter from the module settings page is applied. For
		best results, this should be an email-specific input format containing the
		following text format filters:

		* [Transliteration](http://drupal.org/node/1095278#comment-4219530)
		* [Emogrifier](http://drupal.org/project/emogrifier)
		* [Pathologic](http://drupal.org/project/pathologic)
		* [Correct faulty and chopped off HTML](http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_htmlcorrector/7)

		## Related Modules

		Emogrifier
		: http://drupal.org/project/emogrifier

		HTML Mail
		: http://drupal.org/project/htmlmail

		HTML Purifier
		: http://drupal.org/project/htmlpurifier

		htmLawed
		: http://drupal.org/project/htmlawed

		Mail System
		: http://drupal.org/project/mailsystem

		Pathologic
		: http://drupal.org/project/pathologic

		Transliteration
		: http://drupal.org/project/transliteration

		## Documentation

		filter.module
		: http://api.drupal.org/api/drupal/modules--filter--filter.module/7

		Installing contributed modules (Drupal 7)
		: http://drupal.org/node/895232

		Theming guide
		: http://drupal.org/documentation/theme

		Standard filters
		: http://api.drupal.org/api/drupal/modules--filter--filter.module/group/standard_filters/7

		## Maintainers

		* [Chris Herberte](http://drupal.org/user/1171)

		* [Bob Vincent](http://drupal.org/user/36148)

README.txt

+104 −47

Original line number	Diff line number	Diff line
		HTML Mail
		---------

		HTML Mail empowers Drupal with the ability to send emails in HTML, providing
		formatting and semantic markup capabilities in email that are not available
		with plain text.
		HTML Mail lets you theme your outgoing messages the same way you theme
		the rest of your website.

		For a full description of the module, visit the project page:
		http://drupal.org/project/htmlmail
		For a full description of the module, visit the [1]project page.

		To submit bug reports and feature suggestions, visit the [2]issue
		queue.

		Requirements

		To submit bug reports and feature suggestions, or to track changes:
		http://drupal.org/project/issues/htmlmail
		HTML Mail requires the [3]Mail System module.

		Installation
		------------

		Install as usual; see http://drupal.org/node/895232 for further information.
		Install as usual; see [4]Installing contributed modules (Drupal 7) for
		further information.

		The following additional modules, while not required, are highly
		recommended:
		* [5]Emogrifier
		* [6]Pathologic
		* [7]Transliteration
		Requires a [8]patch.

		Theming
		-------

		The default "Theme to use for emails" is "No theme (use htmlmail.tpl.php)".
		To customize the appearance of your outgoing emails, you should copy the
		included "htmlmail.tpl.php" file to your theme directory and edit the
		contents.
		The email message text goes through four transformations before
		sending:
		1. The Text format pre-filter from the module settings page is
		applied. This should be the same text format that your website uses
		for contributed content such as comments or blog postings. For
		consistency and security, it should include the the [9]Correct
		faulty and chopped off HTML from [10]filter.module, or a better
		replacement such as [11]HTML Purifier or [12]htmLawed.
		2. A theme template is applied. The default template is the included
		htmlmail.tpl.php file. You may copy this file to your theme
		directory and use it to customize the contents and formatting of
		your emails. The comments within the file contain complete
		documentation on its usage.
		3. The message may be wrapped in a website theme selected on the
		module settings page. Creating an email-specific theme lets you use
		the full power of the [13]drupal theme system to format your
		emails.
		4. The Text format post-filter from the module settings page is
		applied. For best results, this should be an email-specific input
		format containing the following text format filters:
		+ [14]Transliteration
		+ [15]Emogrifier
		+ [16]Pathologic
		+ [17]Correct faulty and chopped off HTML

		Related Modules

		Emogrifier
		http://drupal.org/project/emogrifier

		HTML Mail
		http://drupal.org/project/htmlmail

		HTML Purifier
		http://drupal.org/project/htmlpurifier

		htmLawed
		http://drupal.org/project/htmlawed

		You may also create "htmlmail-MODULENAME.tpl.php" files to customize mail sent by
		a particular module. For instance, to customize the password reset emails sent
		by the user module, copy "htmlmail.tpl.php" to "htmlmail-user.tpl.php". Remember
		that you will need to put both files in your theme directory for this to work.
		Mail System
		http://drupal.org/project/mailsystem

		Template files are cached, so remember to clear cache (admin/settings/performance)
		after creating, copying, or editing any .tpl.php files.
		Pathologic
		http://drupal.org/project/pathologic

		If you prefer your emails to look just like your website pages, choose an
		available theme from the "Theme to use for emails" selection box.
		Transliteration
		http://drupal.org/project/transliteration

		The Emogrifier library (http://www.pelagodesign.com/sidecar/emogrifier/) may be
		used to convert stylesheets to inline style rules. A copy is provided with this
		module. If you would rather maintain a separately-updated copy, install the
		libraries module (http://drupal.org/project/libraries).
		Documentation

		For tips and resources on building HTML emails see:
		* http://www.campaignmonitor.com/css/
		* http://www.mailchimp.com/articles/email_marketing_guide/
		* http://css-tricks.com/using-css-in-html-emails-the-real-story/
		filter.module
		http://api.drupal.org/api/drupal/modules--filter--filter.module/
		7

		Important
		---------
		Installing contributed modules (Drupal 7)
		http://drupal.org/node/895232

		Remember that many email clients will not be happy with certain code. Your
		CSS may conflict with a web-mail provider's CSS, and HTML in email may expose
		security vulnerabilities. Beyond this, if you still really, really must have
		HTML in your email, you may find this module useful.
		Theming guide
		http://drupal.org/documentation/theme

		Standard filters
		http://api.drupal.org/api/drupal/modules--filter--filter.module/
		group/standard_filters/7

		Maintainers
		-----------

		Chris Herberte - http://drupal.org/user/1171
		Bob Vincent - http://drupal.org/user/36148
		* [18]Chris Herberte
		* [19]Bob Vincent

		References

		1. http://drupal.org/project/htmlmail
		2. http://drupal.org/project/issues/htmlmail
		3. http://drupal.org/project/mailsystem
		4. http://drupal.org/node/895232
		5. http://drupal.org/project/emogrifier
		6. http://drupal.org/project/pathologic
		7. http://drupal.org/project/transliteration
		8. http://drupal.org/node/1095278#comment-4219530
		9. http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_htmlcorrector/7
		10. http://api.drupal.org/api/drupal/modules--filter--filter.module/7
		11. http://drupal.org/project/htmlpurifier
		12. http://drupal.org/project/htmlawed
		13. http://drupal.org/documentation/theme
		14. http://drupal.org/node/1095278#comment-4219530
		15. http://drupal.org/project/emogrifier
		16. http://drupal.org/project/pathologic
		17. http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_htmlcorrector/7
		18. http://drupal.org/user/1171
		19. http://drupal.org/user/36148

htmlmail.admin.inc

+4 −33

Original line number	Diff line number	Diff line
		@@ -46,39 +46,6 @@ function htmlmail_admin_settings() {
		return system_settings_form($form);
		}

		/**
		* Builds a form for setting Header, Footer, and CSS content to be included in
		* sent emails.
		*/
		function htmlmail_template_settings() {
		$defaults = array('value' => '', 'format' => filter_default_format());
		$header = variable_get('htmlmail_header', $defaults);
		$form['htmlmail_header'] = array(
		'#type' => 'text_format',
		'#title' => t('Header HTML'),
		'#rows' => 6,
		'#default_value' => $header['value'],
		'#format' => $header['format'],
		'#description' => 'Extra HTML markup to add at the top of emails.',
		);
		$footer = variable_get('htmlmail_footer', $defaults);
		$form['htmlmail_footer'] = array(
		'#type' => 'text_format',
		'#title' => t('Footer HTML'),
		'#rows' => 6,
		'#default_value' => $footer['value'],
		'#format' => $footer['format'],
		'#description' => 'Extra HTML markup to add at the bottom of emails.',
		);
		$form['htmlmail_css'] = array(
		'#type' => 'textarea',
		'#title' => t('CSS'),
		'#default_value' => variable_get('htmlmail_css', ''),
		'#description' => 'Extra CSS rules to be added to emails.',
		);
		return system_settings_form($form);
		}

		/**
		* Builds a form for sending a test message.
		*/
		@@ -96,6 +63,10 @@ function htmlmail_test_form($form_values = NULL) {
		)
		);

		// Set the input format to be the same as the selected prefilter format.
		$defaults['body']['format'] =
		variable_get('htmlmail_prefilter', $default[s['body']['format']);

		$form['to'] = array(
		'#type' => 'textfield',
		'#title' => t('To'),

htmlmail.module

+10 −16

Original line number	Diff line number	Diff line
		@@ -34,15 +34,6 @@ function htmlmail_menu() {
		'type' => MENU_DEFAULT_LOCAL_TASK,
		'weight' => '-2'
		);
		$items['admin/config/system/htmlmail/template'] = array(
		'title' => 'Template',
		'page callback' => 'drupal_get_form',
		'page arguments' => array('htmlmail_template_settings'),
		'access arguments' => array('access administration pages'),
		'type' => MENU_LOCAL_TASK,
		'weight' => '-1',
		'file' => 'htmlmail.admin.inc',
		);
		$items['admin/config/system/htmlmail/test'] = array(
		'title' => 'Send Test',
		'page callback' => 'drupal_get_form',
		@@ -82,14 +73,17 @@ function htmlmail_theme() {
		* @see htmlmail.tpl.php
		*/
		function template_preprocess_htmlmail(&$variables) {
		$variables['path'] = url($variables['directory'], array('absolute' => TRUE));
		$header = variable_get('htmlmail_header', array('value' => '', 'format' => NULL));
		$variables['header'] = check_markup($header['value'], $header['format']);
		$footer = variable_get('htmlmail_footer', array('value' => '', 'format' => NULL));
		$variables['footer'] = check_markup($footer['value'], $footer['format']);
		$variables['css'] = variable_get('htmlmail_css', '');
		$variables['template_files'][] = 'htmlmail-' . $variables['module'];
		$variables['debug'] = variable_get('htmlmail_debug', '0');
		$variables['theme_url'] = url($variables['directory'], array('absolute' => TRUE));
		$variables['theme_hook_suggestions'][] = $last = 'htmlmail-' . $variables['module'];
		$parts = array_diff_assoc(
		explode('_', $variables['message_id'] = $variables['key']),
		explode('_', $variables['module'])
		);
		$variables['key'] = implode('_', $parts);
		foreach ($parts as $part) {
		$variables['theme_hook_suggestions'][] = $last .= '_' . $part;
		}
		}

		/**