File/program/modules/mailpage/mailpage_admin.php

Description

/program/modules/mailpage/mailpage_admin.php - management interface for mailpage-module

This file defines the administrative interface to this module. The interface consists of the following four functions.

    mailpage_disconnect(&$output,$area_id,$node_id,$module) mailpage_connect(&$output,$area_id,$node_id,$module) mailpage_show_edit(&$output,$area_id,$node_id,$module,$viewonly,$edit_again,$href,$option) mailpage_save(&$output,$area_id,$node_id,$module,$viewonly,&$edit_again,$option)

These functions are called from pagemanagerlib.php whenever necessary.

Functions
mailpage_connect (line 78)

connect this module to a node

this makes the link between the node $node_id in area $area_id and this module. In this case we create a single 'mailpages' record linked to node_id. Any addresses can be added later as desired and records in 'mailpages_addresses' will be created as necessary.

  • return: TRUE on success, FALSE otherwise
bool mailpage_connect (object &$output, int $area_id, int $node_id, array $module)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which we need to connect
  • array $module: the module record straight from the database
mailpage_dialog_validate_address (line 695)

validate the data entered by the user

Other than the standard validation we check for at least 1 @-sign in the email field As a side effect, the dialogdef is filled with the POST'ed values.

  • return: TRUE if valid, else FALSE + messages added to $dialogdef
bool mailpage_dialog_validate_address (object &$dialogdef)
  • object &$dialogdef: defines the dialog and will hold POSTed values
mailpage_disconnect (line 55)

disconnect this module from a node

this breaks the link between the node $node_id in area $area_id and this module. For now we simply delete the records in 'mailpages' and 'mailpages_addresses' linked to node node_id. Note that the order is not important (in this case) because there are no FK constraints between the two tables. However, there are FK constraints with the nodes table. The db_delete() here is a simple best effort.

  • return: TRUE on success, FALSE otherwise
bool mailpage_disconnect (object &$output, int $area_id, int $node_id, array $module)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node from which we need to disconnect
  • array $module: the module record straight from the database
mailpage_get_addresses (line 943)

retrieve current list of addresses in an array (could be empty)

this retrieves the addresses associated with $node_id from the database. As an important side effect all entries' sort order values are renumbered. This means that we always have a neat set of sort order numbers 10, 20, ...

On error we return an empty array as a sort of best effort. The error is logged though.

  • return: records from the database with sort order renumbered OR an empty array
array mailpage_get_addresses (int $node_id)
  • int $node_id: indicates page
mailpage_get_dialogdef_address (line 806)

construct a dialog definition for a mailpage destination address (add/edit)

this constructs a dialog definition which handles adding and editing destination addresses. In the case of adding a new address we start with empty fields (mostly), otherwise we attempt to load the existing data from the DB.

  • return: dialog definition
array mailpage_get_dialogdef_address (object &$output, int $viewonly, int $node_id, int $address_id, [int $sort_order = 10])
  • object &$output: collects the html output (if any)
  • int $viewonly: if TRUE the Save button is not displayed and config values cannot be changed
  • int $node_id: identifies the current mailpage
  • int $address_id: identifies the address, 0 for a new one
  • int $sort_order: is the next available sort order for new records
mailpage_get_dialogdef_config (line 721)

construct a dialog definition for the main mailpage configuration

this constructs the dialogdef and also fills it with data from the DB (if any)

  • return: dialog definition
array mailpage_get_dialogdef_config (object &$output, int $viewonly, int $node_id)
  • object &$output: collects the html output (if any)
  • int $viewonly: if TRUE the Save button is not displayed and config values cannot be changed
  • int $node_id: identifies the current mailpage
mailpage_get_dialogdef_delete (line 918)

construct a dialog definition for deletion of a destination address

this constructs a dialog definition which handles deleting of a destination address. There is not much to do: the address_id to delete is conveyed via $_GET[].

  • return: dialog definition
array mailpage_get_dialogdef_delete (int $viewonly)
  • int $viewonly: if TRUE the Save button is not displayed and config values cannot be changed
mailpage_get_icon_delete (line 987)

construct a delete button for deletion of a destination address

this constructs a clickable icon/button that leads to the delete confirmation dialog. We use the same code as does the Page Manager (picking up the icon from the current skin et al). This makes that the icon automagically adapts to the skin, eg. the textonly skin.

  • return: dialog definition
array mailpage_get_icon_delete (object &$output, int $node_id, int $viewonly, int $address_id,  $aparams, int $aparms)
  • object &$output: collects the html output (if any)
  • int $node_id: identifies the current mailpage
  • int $viewonly: if TRUE the Save button is not displayed and config values cannot be changed
  • int $address_id: identifies the address, 0 for a new one
  • int $aparms: contains values to substitute in translations, e.g. {ADDRESS_ID}
  • $aparams
mailpage_save (line 202)

dispatcher for save routines

We use different subroutines for clarity.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_save (object &$output, int $area_id, int $node_id, array $module, bool $viewonly, bool &$edit_again, string $option)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which the content is connected
  • array $module: the module record straight from the database
  • bool $viewonly: if TRUE, editing and hence saving is not allowed
  • bool &$edit_again: set to TRUE if we need to edit the content again, FALSE otherwise
  • string $option: the selected submenu option or NULL if user used the 'Content' option to get here
mailpage_save_configuration (line 259)

save the modified configuration data of this mailpage linked to node $node_id

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_save_configuration (object &$output, int $area_id, int $node_id, array $module, bool $viewonly, bool &$edit_again)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which the content is connected
  • array $module: the module record straight from the database
  • bool $viewonly: if TRUE, editing and hence saving is not allowed
  • bool &$edit_again: set to TRUE if we need to edit the content again, FALSE otherwise
mailpage_save_destinations (line 570)

process the POSTed destination address data

this is another complex routine to fit saving of three different dialogs into one. See also the comprehensive documentation in function mailpage_show_edit_destinations().

Basically this routine handles all database operations like inserting new addresses, editing or deleting existing ones. We arrive here because the user has either pressed [Save] or [Done], indicating that the data should be stored, or [Cancel], indicating the wish to end the adding/editing/deleting operation (dialogs #2 and #3 as we called them in function mailpage_show_edit_destinations()).

However, there is one other [Cancel] button: the one in the destinations addresses overview (dialog #1). This button ends the editing of the node alltogether and returns to the Page Manager. This specific situation is indicated by returning FALSE after setting $edit_again to FALSE. All other cases always return FALSE with $edit_again set to TRUE.

This means that we do have to check for the validity of the dialog data in show_edit() again, because we abuse the returned value to stay in the overview screen (dialog #1). This is ugly, and I am sorry about that.

Here too we distinguish between add/edit and delete via address_id and delete_id respectively (linked to $_GET['address'] and $_GET['delete']). We do check for invalid address_id's: if we don't recognise the address_id/delete_id we simply do nothing (but send a message to the log nevertheless).

  • return: TRUE on success, FALSE otherwise (but see documentation above)
bool mailpage_save_destinations (object &$output, int $area_id, int $node_id, array $module, bool $viewonly,  &$edit_again, bool $edit_again)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which this module is connected
  • array $module: the module record straight from the database
  • bool $viewonly: if TRUE, editing is not allowed (but simply showing the content is allowed)
  • bool $edit_again: if TRUE start with data from $_POST, else use data from database
  • &$edit_again
mailpage_show_content (line 154)

show the main content screen (in fact documentation only)

this displays the simple overview screen with documentation. It ends with a cancel button that ends the whole edit operation for this node.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_show_content (object &$output, int $node_id, array $module)
  • object &$output: collects the html output (if any)
  • int $node_id: the node to which this module is connected
  • array $module: the module record straight from the database
mailpage_show_edit (line 124)

dispatcher for presenting the user with one of the mailpage dialogs

this routine looks at $option to see which dialog is requested and subsequently displays that dialog.

There are three possibilities:

- $option == NULL: an overview/help screen basically pointing the user to the submenu items - $option == 'configuration': main configuration via table 'mailpages' - $option == 'destinations': destination addresses config via 'mailpages_addresses'

We use different subroutines for clarity.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_show_edit (object &$output, int $area_id, int $node_id, array $module, bool $viewonly, bool $edit_again, string $href, string $option)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which this module is connected
  • array $module: the module record straight from the database
  • bool $viewonly: if TRUE, editing is not allowed (but simply showing the content is allowed)
  • bool $edit_again: if TRUE start with data from $_POST, else use data from database
  • string $href: the action property of the HTML-form, the place where data will be POST'ed
  • string $option: the selected submenu option or NULL if user used the 'Content' option to get here
mailpage_show_edit_configuration (line 232)

present the user with the main configuration dialog for mailpage at node $node_id

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_show_edit_configuration (object &$output, int $area_id, int $node_id, array $module, bool $viewonly, bool $edit_again, string $href)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which this module is connected
  • array $module: the module record straight from the database
  • bool $viewonly: if TRUE, editing is not allowed (but simply showing the content is allowed)
  • bool $edit_again: if TRUE start with data from $_POST, else use data from database
  • string $href: the action property of the HTML-form, the place where data will be POST'ed
mailpage_show_edit_destinations (line 388)

present the user with a dialog for mailpage destination addresses at node $node_id

this is a complex routine that is responsible for constructing and showing the dialogs associated with destination addresses.

The following dialogs exist.

#1. Mailpage Destinations Overview

Add a new destination address
[D] Principal (10)
[D] Webmaster (20)
[Cancel]

#2. Add new destination address/Edit existing destination address

Name:        __________
E-Mail:      __________
Description: __________
Thankyou:    __________
Sort order:  ____
[Save] [Done] [Cancel]

#3. Delete address confirmation

[Delete] [Cancel]

There are some complex interactions between these screens and the corresponding save routine mailpage_save_destinations(). The effects we try to achieve are as follows. The link 'Add a new destination address' leads to dialog #2 with address_id = 0 The links 'Principal' and 'Webmaster' lead also to dialog #2 with valid, existing address_id != 0 The delete button '[D]' leads to dialog #3 with valid, existing delete_id != 0

The [Cancel] button in dialog #1 ends the editing of this node; ie. returns to Page Manager. The other [Cancel] buttons bring the user back to dialog #1. In effect this is a kind of zoom function: you can zoom in on an address and go back to the list without leaving this node, etc. etc.

The [Done] and [Delete] buttons perform an action (saving or deleting a destination) and also return to dialog #1.

The [Save] button always has the meaning "save the data and continue editing". For the Edit dialog #2 this works perfect. For the Add dialog #2 there is a slight problem, because the Add dialog received address_id = 0 and saving the new address changes that: the address_id should now be the last_id as inserted in the database instead of 0. Unfortuinately there is no clean way to convey this fact via the module interface with Page Manager. In order to provide a smooth user experience I had to use an ugly hack in the form of a global variable called $mailpage_new_address_id. This variable is usually set to NULL, but after successful insertion into the DB of the new address, the new address_id is stored here (from the save() routine). We pick it up here and use that value instead of the value 0 and present the user with an Edit dialog #2 for the newly added address when she presses the [Save] button. This magic works because we know that after Page Manager calls the save() routine, which sets the $edit_again flag, Page Manager will call show_view() again. Ugly, but it works. Sorry.

Note that we also take $viewonly into account: if this flag is set, there is no 'Add a destination' link because $viewonly does not allow anything to be changed in the node configuration, including adding (and editing and deleting) destinations.

Note: the parameter that holds the address_id is called $_GET['address'] in case of adding or editing an address. If we are deleting we use $_GET['delete'] in order to distinguish these cases. I use the variable name $delete_id to keep things separated.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_show_edit_destinations (object &$output, int $area_id, int $node_id, array $module, bool $viewonly, bool $edit_again, string $href)
  • object &$output: collects the html output (if any)
  • int $area_id: the area in which $node_id resides
  • int $node_id: the node to which this module is connected
  • array $module: the module record straight from the database
  • bool $viewonly: if TRUE, editing is not allowed (but simply showing the content is allowed)
  • bool $edit_again: if TRUE start with data from $_POST, else use data from database
  • string $href: the action property of the HTML-form, the place where data will be POST'ed
mailpage_show_edit_destinations_overview (line 490)

show a screen with a links to add/edit/delete destination addresses

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool mailpage_show_edit_destinations_overview (object &$output, int $node_id, bool $viewonly, string $href, array $records)
  • object &$output: collects the html output (if any)
  • int $node_id: the node to which this module is connected
  • bool $viewonly: if TRUE, editing is not allowed (but simply showing the content is allowed)
  • string $href: the action property of the HTML-form, the place where data will be POST'ed
  • array $records: the currently defined destination adresses

Documentation generated on Tue, 28 Jun 2016 19:10:12 +0200 by phpDocumentor 1.4.0