/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.
These functions are called from pagemanagerlib.php whenever necessary.
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.
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.
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.
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.
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.
construct a dialog definition for the main mailpage configuration
this constructs the dialogdef and also fills it with data from the DB (if any)
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[].
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.
dispatcher for save routines
We use different subroutines for clarity.
save the modified configuration data of this mailpage linked to node $node_id
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).
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.
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.
present the user with the main configuration dialog for mailpage at node $node_id
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.
show a screen with a links to add/edit/delete destination addresses
Documentation generated on Tue, 28 Jun 2016 19:10:12 +0200 by phpDocumentor 1.4.0