Merge pull request #100 from SparkPost/template-attachment-doc

add templates/attachment related comments/docs

Author: rajumsys

admin.widget.class.php

@@ -245,9 +245,10 @@ public function render_template_field()
                value="<?php echo $this->settings['template']; ?>"/><br/>
         <small>
             <ul>
-                <li>- Please see <a href="https://support.sparkpost.com/customer/portal/articles/2409547-using-templates-with-the-sparkpost-wordpress-plugin">this article</a> for detailed information about using templates with this plugin.</li>
+                <li>- Please see <a href="https://support.sparkpost.com/customer/portal/articles/2409547-using-templates-with-the-sparkpost-wordpress-plugin" target="_blank">this article</a> for detailed information about using templates with this plugin.</li>
                 <li>- Templates can only be used with the HTTP API.</li>
-                <li>- Leave this field blank to disable use of a template.</li>
+                <li>- <a href="https://github.com/SparkPost/wordpress-sparkpost/blob/master/docs/templates-attachments.md" target="_blank">Does not work with attachment</a>.
+                <li>- Leave this field blank to disable use of a template or use it dynamically (i.e. <a href="https://github.com/SparkPost/wordpress-sparkpost/blob/master/docs/hooks.md" target="_blank">using hooks</a>).</li>
             </ul>
         </small>
     <?php

docs/templates-attachments.md

@@ -0,0 +1,27 @@
+# Sending Attachments with Template
+
+Currently, you [can't send attachments](https://support.sparkpost.com/customer/portal/articles/2458261-can-attachments-be-sent-when-using-templates-) if you are you using a template. There are [technical work arounds](https://www.sparkpost.com/blog/advanced-email-templates/) but this is not still supported by SparkPost plugin yet.
+
+## Interim solution
+If all of your emails has attachments, easiest solution is not to use any template at all (i.e. Keep `Template` field empty).
+
+However, if some of your emails use template (and they do not have attachments), you can specify a template ID in settings and then use the hook to remove the template just before creating that email that has attachment(s).
+
+Here is an example:
+
+```
+function remove_template() {
+  return false;
+}
+
+//register the filter
+add_filter('wpsp_template_id', remove_template);
+
+// call wp_mail with attachments
+remove_filter('wpsp_template_id', remove_template); //so other emails use template as usual.
+```
+
+## Change in future
+In future SparkPost may support sending attachments with Templates. Also, we can consider the implementing the alternative that is mentioned above directly inside this plugin.
+
+Track [this issue](https://github.com/SparkPost/wordpress-sparkpost/issues/97) to know the latest regarding this.