File/program/modules/newsletter/newsletter_view.php

Description

/program/modules/newsletter/newsletter_view.php - interface to the view-part of the newsletter module

This file defines the interface with the newsletter-module for viewing content. The interface consists of this function:

    newsletter_view(&$output,$area_id,$node_id,$module)

This function is called from /index.php when the node to display is connected to this module.

Includes
 require_once (NEWSLETTER_DIRNAME."/newsletter_common.php") (line 38)
 require_once ($CFG->progdir."/lib/tokenlib.php") (line 41)
Constants
NEWSLETTER_DIRNAME = dirname(__FILE__) (line 37)
NEWSLETTER_REFERENCE = sha1(__FILE__.'":".__LINE__) (line 40)
Functions
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.

  • return: TRUE on success + output via $theme, FALSE otherwise
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).

  • return: TRUE on success + output via $theme, FALSE otherwise
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.

  • return: TRUE on success + output via $theme, FALSE otherwise
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

  • return: TRUE on success + output via $theme, FALSE otherwise
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.

  • return: dialog definition
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.

  • return: FALSE on error, non-0 identification of message on success
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.

  • return: TRUE on success + output via $theme, FALSE otherwise
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.

  • return: output writted to $theme
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

  • return: datadefinition
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.

  • return: output writted to $theme
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.

  • return: FALSE on error, TRUE on success + message sent
  • todo: extra validation of set_mailreplyto and set_subject?
  • todo: more available parameters in subject_line?
  • todo: make body of mail configuratble?
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()}.

  • return: output writted to $theme
  • todo: should we have an OK button at all???
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

  • return: TRUE on success + output via $theme, FALSE otherwise
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").

  • return: TRUE on success + output via $theme, FALSE otherwise
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)

  • return: TRUE on success + output via $theme, FALSE otherwise
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.

  • return: dialog definition
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

  • return: FALSE on error, TRUE on success
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.

  • return: TRUE on success + output via $theme, FALSE otherwise
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).

  • return: dialog definition
array newsletter_view_unsubscribe_get_dialogdef ()
newsletter_view_unsubscribe_send_code (line 474)

send a quasi-random unsubscribe confirmation code to $email

  • return: FALSE on error, TRUE on success
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

Documentation generated on Tue, 28 Jun 2016 19:11:02 +0200 by phpDocumentor 1.4.0