1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

UAS / Ninjitsu Hosting Newsletter


This is the How-To for the Ninjitsu / UAS drupal newsletter module. 

INDEX
Caveats
Setup
Installation
Module Configuration
Creating Newsletters
Working with Templates

==================
Caveats
==================

   1. This module uses Smarty for its templates, so that is what you will need to use as well.  In the future the architecture might be changed to accommodate other engines, but for now, that should suffice.

   2. There is no attempt made at int'l8n or recognizing int'l8n

   3. Nodes must be published to be included in the newsletter.

   4. newsletters are not archived.  one could easily write some pages that would allow for browsing the taxonomies for the newsletters, but that code is not included in this module at this time.



==================
Set Up
==================
Before enabling the module, do 4 things (you do not have to do things in this order, it just works out nicely)

   1. Setup the Newsletter Issue vocabulary and terms:

          * You can name the vocabulary anything you want. something like "Newsletter Issue" works well
          * Add some terms to the vocabulary.  These terms and nodes that are associated with them will act as the newsletter issues.

   2. Setup the Newsletter Section vocabulary and terms:

          * You can name the vocabulary anything you want. something like "Newsletter Section" works well
          * Add some terms to the vocabulary.  These terms represent the sections of a newsletter.

   3. Create a newsletter content type that will act as the main node for each newsletter and add it to the "Newsletter Issue" Vocabulary as an event type.
          * You will not be able to generate a newsletter issue until a node has been created and associated with a Newsletter Issue Term

   4. Add some node types to the "Newsletter Section" and "Newsletter Issue" vocabularies that you will be using for newsletter content like Page, Story, Event. Even your own custom node types will work.


==================
Installation
==================

   1. Install and enable the module per the normal installation procedure.  Once enabled you will be presented with some menu options for the admin settings and for "getting" the  prepared newsletter templates.  specifically, the URLs are as follows:
          * uas_newsletter/admin/settings - takes you to the configuration page for the uas_newsletter
          * uas_newsletter/generate - this page wll retrieve and present the prepared newsletter templates to you


==================
Module Configuration
==================

Now go to the configuration page located at uas_newsletter/admin/settings.  The settings should be described in full detail at this page.  basically this page will tell the nesletter module which vocabularies you are using for th newsletter issues and sections.  this page also lets you configure smarty if you need it.  also there is a template directory setting tha is where he html and text templates will be residing.  uploading and using different templates than the default is described below.

==================
Newsletter Creation
==================

   1. to create a newsletter, you will need to create drupal node content.  during the setup above you should have associated some node types with the vocabularies Newsletter Section Vocabulariy.    so either go to the existing nodes that you want to include in a newsletter and associate them with the appropriate Issues and Sections.  You can also create new content of the appropriate type and associate that with the appropriate issues and sections of the newsletter.

      THE NODES MUST BE PUBLISHED IN ORDER TO SHOW UP IN THE GENERATED / PREPARED NEWSLETTER

      When I say "associate" the node.  what should happen is that there should be two pick lists available in the edit node page that will allow you to choose Newsletter issues and Newsletter sections for this node.

   2. after you have chosen the nodes and are happy with the content, you can go to the

      uas_newsletter/generate

      url and you will be presented with three drop downs and two text areas.  The three drop downs will let you choose which newsletters and templates to use for generating the prepared newsletter.  The text areas are where the prepared newsletter templates will be located.  One will contain the HTML text, the other will contain the plain text newsletter.

   3. After you have generated the newsletters, you can copy and paste the content from the textareas into a file that will later be used in mailling program as a merge template.  specifically, we have CiviMail in mind  :)



==================
Working With Templates
==================

ONLY MODULES THAT HAVE NAMES THAT END WITH .tpl WILL BE RECOGNIZED BY THIS MODULE

    * This module uses the smarty engine for generating newsletters.  the smarty documentation can be found here:

      http://smarty.php.net/manual

    * The smarty engine locates its templates in whatever directory is configured in the newsletter module settings.  by default this path is the directory where the module is located.

    * The module will scan the template directory and present a list of files to the user

    * To add a new template to the system, simply name it with a .tpl extension and upload the new template to the template directory (the directory that is declared in the module settings) and it will automatically appear in the drop down list on the newsletter generation page.

    * To delete a template, simply remove it from the templates directory.


As we are working with a templating system this means that we need a data source for filling in all the parts of the template. 
We set the smarty template engine with the following data before we call fetch for processing the template.

    * $base_url - string - This is the base URL for the drupal installation.
    * $html - array that holds the html version of the newsletter node content
    * $text - array that holds the text version of the newsletter node content. (html that has been sripped and converted to plain text) The $html and $text arrays are identical in structure. The keys and values are described below.
          o main_node - is the node that was associated with the newsletter issue
          o nodes - an assoc array keyed off of node ids,  the values are the nodes of content that appear in the newsletter
          o sections - an assoc array that is keyed off of term ids of the terms that were chosen as newsletter sections.
            The values are term objects with an extra property called nodes that is an array which is keyed off of node_id, where the values are the nodes that belong to that section of the newsletter.


array(
  main_node => node object that is associated with the Newsletter Issue term

  nodes => array(
    node_id => node_object
    node_id => node_object
    node_id => node_object
  )

  sections => array(

    section_id (term id) => section node object (
                                       nodes => array(
                                          node_id => node_object
                                          node_id => node_object
                                          node_id => node_object
                                       )
                                     )

    section_id (term id) => section node object (
                                       nodes => array(
                                          node_id => node_object
                                          node_id => node_object
                                          node_id => node_object
                                       )
                                     )

  )
)