newsletter_view (line
74)
display the content of the newsletter linked to node $node_id
this routine is basically a dispatcher. First we decide which policies are in place for this visitor (who might be a user):
- flag_a: the newsletter archive is available
- flag_c: the visitor is allowed to contribute
- flag_s: the visitor is allowd to subscribe/unsubscribe
After that we decide which routine to perform based on the parameters that are specified. The following combinations are recognised:
- archive: volume=v and number=n; shows 0, 1 or more old newsletters
- contribution: contribution=c: handle a visitor contribution
- subscribe: subscribe=s or unsubscribe=u: handle subscriptions
If none of those are applicable, the default page is displayed, possibly with the latest newsletter (if policy allows it).
The actual work is done in subroutines. The values of these flags are added to the config record which is passed to the subroutines.
bool
newsletter_view
(object &$theme, int $area_id, int $node_id, array $module)
-
object
&$theme: collects the (html) output
-
int
$area_id: identifies the area where $node_id lives
-
int
$node_id: the node to which this module is connected
-
array
$module: the module record straight from the database
newsletter_view_add_navbar (line
172)
add a navigation bar to the output
if the corresponding policy allows this creates links to the archive, the contribution dialog and the subscribe/unsubscribe logic. We also (optionally) show a link to display the specified issue 'stand-alone' (in a new window).
bool
newsletter_view_add_navbar
(object &$theme, array $config, [int $issue_id = NULL])
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$issue_id: identify issue to show 'stand-alone' or NULL for none
newsletter_view_archive (line
260)
display two levels of newsletter issues: volumes+number or numbers+toc
if $volume == 0 we show all available volumes with clickable links to the numbers (including a print link) as nested lists. If $volume == V we show all numbers in volume V (+print link) AND the clickable ToC of every number. We keep everything in at most two nested lists to prevent cluttering.
bool
newsletter_view_archive
(object &$theme, array $config, int $node_id, int $volume, int $number)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
-
int
$volume: is the volume number > 0 or a wildcard (<= 0)
-
int
$number: is the issue number > 0 or a wildcard (<= 0)
newsletter_view_confirm (line
571)
handle the confirmation code for subscribing/unsubscribing
bool
newsletter_view_confirm
(object &$theme, array $config, int $node_id, [ $code = 1])
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
-
$code
newsletter_view_confirm_get_dialogdef (line
619)
construct a dialog definition for confirm code
this constructs a dialog definition which presents the user with a 1-field dialog where she can enter the oncecode that was emailed to her earlier.
array
newsletter_view_confirm_get_dialogdef
()
newsletter_view_confirm_process_code (line
650)
process a code confirming a subscribe or unsubscribe action
we arrive here with a code that has the action to perform embedded. It consists of a quasi-random string, the action to perform ('d' means unsubscribe, 'a' means subscribe) and finally a uniquemaker based on a subscriber_id.
bool
newsletter_view_confirm_process_code
( $theme, array $config, string $code, object &$theme)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
string
$code: the oncecode entered by the user
-
$theme
newsletter_view_contribution (line
987)
handle user contribution of articles
this eventually yields a user contribution in the form of a text-only article added to the list of UNselected articles in the database. we use the logic from tokenlib as we did in mailpage_view.php. Data entry is a two-step process: one screen with editable text and a preview-button, another screen with uneditable text and a submit-button This makes it impossible to simply keep submitting a story; the first screen provides a token, and the second screen only works after a minimum delay.
bool
newsletter_view_contribution
(object &$theme, array $config, int $node_id, int $value)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
-
int
$value: indicates the phase in the contribution process
newsletter_view_contribution_form (line
1172)
display the contribution form
this displays the contribution form.
void
newsletter_view_contribution_form
(object &$theme, array $config, array $dialogdef)
-
object
&$theme: collects the (html) output
-
array
$dialogdef: array that defines the input fields
-
array
$config: mnewsletter configuration data
newsletter_view_contribution_get_dialogdef (line
1088)
construct a dialog definition for the visitor's contribution form
array
newsletter_view_contribution_get_dialogdef
(array $config, string $token_key)
-
array
$config: newsletter configuration
-
string
$token_key
newsletter_view_contribution_preview (line
1198)
show a preview of the message to the visitor
this shows a preview of the article to the visitor. Nothing is editable, it is view-only. The only option is to either press the Send-button to actually submit the messate OR to press the Edit button to go back to the editable form.
Sending a message is a two-step procedure by design.
void
newsletter_view_contribution_preview
(object &$theme, array $config, array $dialogdef, string $ip_addr)
-
object
&$theme: collects the (html) output
-
array
$dialogdef: array that defines the input fields
-
string
$ip_addr: the originating IP-address
-
array
$config: newsletter configuration data
newsletter_view_contribution_send (line
1250)
add the contribution to the list of unselected articles and mail the admins
In order to get a feeling for the time a visitor needs, we also record the delay (in seconds) next to the visitor's IP address.
bool
newsletter_view_contribution_send
(object &$theme, array $config, array $dialogdef, string $ip_addr, int $delay)
-
object
&$theme: collects the (html) output and provides queue_alert()
-
array
$config: mailpage configuration data in a (nested) array
-
array
$dialogdef: array that defines the data fields including values
-
string
$ip_addr: the originating IP-address
-
int
$delay: the # of seconds since time=t0
newsletter_view_contribution_thankyou (line
1343)
thank the visitor for the article and show a text copy too
Almost the same as {@see newsletter_view_contribution_preview()}.
void
newsletter_view_contribution_thankyou
(object &$theme, array $config, array $dialogdef, string $ip_addr)
-
object
&$theme: collects the (html) output
-
array
$dialogdef: array that defines the input fields
-
string
$ip_addr: the originating IP-address
-
array
$config: mailpage configuration data in a (nested) array
newsletter_view_home (line
129)
display the default page, possibly with the latest newsletter embedded
bool
newsletter_view_home
(object &$theme, array $config, int $node_id)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
newsletter_view_issue (line
223)
show a 'stand-alone' version of the newsletter
this is almost the same routine as newsletter_publish_show_preview() and newsletter_compose_show_preview(). The difference is that we look for a specific issue in the archives (could be the latest issue). However, the issue must be in the archive as indicated by the status. If this issue was sent by mail only, we exit with fatal error 099. We assume we have our own window (arrived here via target="_blank").
bool
newsletter_view_issue
(object &$theme, array $config, int $node_id, int $issue_id)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
-
int
$issue_id: explicit issue to show 'stand-alone'
newsletter_view_subscribe (line
777)
show and process a subscription request (phase 1)
bool
newsletter_view_subscribe
(object &$theme, array $config, int $node_id)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
newsletter_view_subscribe_get_dialogdef (line
838)
construct a dialog definition for subscribing
this constructs a dialog definition which presents the user with a 2 or 3 field dialog where she can enter her email-address, full name and perhaps additional remarks to subscribe.
array
newsletter_view_subscribe_get_dialogdef
(bool $show_remarks)
-
bool
$show_remarks: if TRUE we show the remarks field too
newsletter_view_subscribe_send_code (line
886)
send a quasi-random subscribe confirmation code to $email
bool|string
newsletter_view_subscribe_send_code
(object &$theme, array $config, string $email, $full_name, $remarks)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
string
$email: destination email address
-
$full_name
-
$remarks
newsletter_view_unsubscribe (line
393)
handle unsubscriptions (phase 1)
this routine shows the dialog where the subscriber can enter her email address to unsubscribe OR processes the same dialog. In the latter case, if the oncecode was sent successfully, the phase 2 dialg (confirm) is displayed.
The email that is sent contains the oncecode which can be entered in that dialog. The email also contains a convenient clickable link.
bool
newsletter_view_unsubscribe
(object &$theme, array $config, int $node_id)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
int
$node_id: the node to which this module is connected
newsletter_view_unsubscribe_get_dialogdef (line
449)
construct a dialog definition for unsubscribing
this constructs a dialog definition which presents the user with a 1-field dialog where she can enter her email-address (to unsubscribe).
array
newsletter_view_unsubscribe_get_dialogdef
()
newsletter_view_unsubscribe_send_code (line
474)
send a quasi-random unsubscribe confirmation code to $email
bool|string
newsletter_view_unsubscribe_send_code
(object &$theme, array $config, string $email)
-
object
&$theme: collects the (html) output
-
array
$config: newsletter configuration + a few policy-flags
-
string
$email: destination email address