Generating the Newsletter
SunMailer generates the newsletter by first creating XML containing the contents of the newsletter. This XML contains some basic information about each node selected by the view and also the rendered value of any fields associated with that node. SunMailer also has three alter hooks for the XML:
- hook_sunmailer_xml_newsletter_alter($newsletter_node, $dom)
- hook_sunmailer_xml_section_alter($section_node, $dom, $section)
- hook_sunmailer_xml_content_alter($content_node, $dom, $node)
The arguments for these hooks are the XML node for the newsletter/section/content, the DOMDocument the XML node is associated with, and for the latter two hooks, the contents of the associated section or node. These hooks run after the given node has been generated and give the developer a chance to add additional children to the node. If you are adding HTML, be sure to enclose it in a <![CDATA[tag]]>.
For each newsletter design, SunMailer uses an XSL file associated with that design to generate the text or HTML that subscribers see. Two XSL files come with SunMailer, one for a text design (text-default.xsl) and one for an HTML design (html-default.xsl). For the text design and any text format, it will strip out HTML tags after the XSLT transformation. These XSL files only use the basic information associated with each node, not any rendered fields or the XML added via the alter hooks.
Redesigning the Newsletter
To modify the existing two designs, do not modify text-default.xsl and html-default.xsl. Create a new XSL file instead, using the provided XSL files as a starting point or a guideline. Once they are ready, go to:
Administer > Site configuration > SunMailer > Configure SunMailer > Newsletter formats
If you merely plan to redesign the existing text or HTML design, simply upload the XSL file for that format and submit the form. You can revert back to the original XSL file later if necessary. Subscribers using that format will now see the redesigned format in the future.
SunMailer must always contain one default text and one default HTML section. These two formats cannot be deleted; they can only be modified. The default text format is also used as the alternate text body for HTML emails.
You can also add new formats as well. Each format will either be a text or an HTML format. Once you create the format, you cannot switch from text to HTML or vice-versa, to avoid springing an unexpected surprise on subscribers using that format. If you delete a format, subscribers using that format will switch to the default text or HTML format, depending on whether the deleted format was a text or an HTML format.
Tips
You should definitely examine the two existing XSL files before creating one of your own. While XSL is not hard to learn, there are a few things you should be aware of. Here are some tips:
- For a text format, use for a new line
- For an HTML format, use the disable-output-escaping attribute for <xsl:value-of> tags
- Google GMail does not support <style> tags; all your styles must be inline styles
- CampaignMonitor has a good guide to CSS support in email clients