File/program/modules/althing/althing_admin.php

Description

/program/modules/althing/althing_admin.php - management interface for althing-module

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

    althing_disconnect(&$output,$area_id,$node_id,$module) althing_connect(&$output,$area_id,$node_id,$module) althing_show_edit(&$output,$area_id,$node_id,$module,$viewonly,$edit_again,$href,$option) althing_save(&$output,$area_id,$node_id,$module,$viewonly,&$edit_again,$option)

These functions are called from pagemanagerlib.php whenever necessary.

Includes
 require_once (dirname(__FILE__)."/althing_common.php") (line 39)
Functions
althing_config_dialog_validate (line 1691)

validation of configuration dialog + rewriting the lists of email addresses as a side effect

  • return: if valid, FALSE otherwise (+messages in dialogdef)
TRUE althing_config_dialog_validate (array &$dialogdef)
  • array &$dialogdef: the dialog to check
althing_connect (line 84)

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 'althings' record linked to node_id via althing_id.

  • return: TRUE on success, FALSE otherwise
bool althing_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
althing_disconnect (line 54)

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 all tables 'althings*' using node_id == althing_id. Note the order in which the tables are emptied (to satisfy the FK constraints).

  • return: TRUE on success, FALSE otherwise
bool althing_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
althing_get_dialogdef_configuration (line 1298)

construct a dialog definition for the main althing configuration

  • return: dialog definition
  • uses: $USER, - $CFG
array althing_get_dialogdef_configuration (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 althing
althing_get_dialogdef_moderation (line 1482)

construct the moderation dialog

  • return: dialog definition
array althing_get_dialogdef_moderation (array &$record, bool $viewonly)
  • array &$record: contains the information about this post
  • bool $viewonly: if TRUE, editing and hence saving is not allowed
althing_get_dialogdef_report (line 1705)

construct the dialog for the reporting tool

  • return: ready to use dialog definition
array althing_get_dialogdef_report ()
althing_get_post_records (line 1631)

retrieve the information about all posts in an array

this routine retrieves all relevant information of all posts in this althing in a single assoc array. We do this in 1 go, which makes for a crafted piece of SQL. However, basically we are simply SELECTing all posts in this althing, in the order indicated by $sort. As a service we also COUNT() the number of moderations a post has had AND we fetch the full name of the moderator that last changed the post.

Note that the result is cached in a local static variable, this might save some time after the user presses a button to move from post-view to list-view.

Sort order #3 is a little special: we sort on the # of moderations, allowing the user to show the 'hottest' posts re: moderation to show at the top of the list.

Sort order #4 is an attempt to order the posts by visibility. We need the CASE WHEN construct because it is hard to sort by boolean.

  • return: FALSE on error, array with data on success
array|bool althing_get_post_records (int $node_id, int $sort, [bool $forced = FALSE])
  • int $node_id: indicates the althing we are working with
  • int $sort: is the desired sort order
  • bool $forced: if TRUE the data is retrieved from DB even if it was cached
althing_moderation_dialog_validate (line 1582)

validation of moderation dialog

this validates the the moderation dialog. Special issue here is the contents of the remark-field: if there are no changes in the visibility and the marbles, a remark is not necessary and should not trigger an error message. We already have the limit set to 0 in the dialogdef, but we _do_ check for the length in case of changes.

  • return: if valid, FALSE otherwise (+messages in dialogdef)
TRUE althing_moderation_dialog_validate (array &$dialogdef)
  • array &$dialogdef: the dialog to check
althing_report_dialog_validate (line 1792)

validate the report selection dialog, correct the list of posts if necessary

  • return: TRUE if all fields are valid, FALSE otherwise + messages in dialogdef
bool althing_report_dialog_validate (array &$dialogdef, array &$posts)
  • array &$dialogdef: to check
  • array &$posts: all posts keyed by display_id (not by post_id)
althing_save (line 211)

dispatcher for save routines

We use different subroutines for clarity.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_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
althing_save_configuration (line 284)

validate and save the modified althing configuration linked to node $node_id

this validates and saves the data that was submitted by the user.

If validation fails, the flag $edit_again is set to TRUE and the return value is FALSE.

If the user has cancelled the operation, the flag $edit_again is set to FALSE and the return value is also FALSE.

If the modified data is stored successfully, the return value is TRUE. The flag edit_again is set to TRUE if the user saved via the [Save] button, and to FALSE if the user saved via the [Done] button.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_save_configuration (object &$output, int $node_id, bool $viewonly, bool &$edit_again, int $area_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 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
althing_save_moderation (line 759)

validate and save the modified althing configuration linked to node $node_id

this validates and saves the data that was submitted by the user.

If validation fails, the flag $edit_again is set to TRUE and the return value is FALSE.

If the user has cancelled the operation, the flag $edit_again is set to FALSE and the return value is also FALSE.

If the modified data is stored successfully, the return value is TRUE. The flag edit_again is set to TRUE if the user saved via the [Save] button, and to FALSE if the user saved via the [Done] button.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_save_moderation (object &$output, int $area_id, int $node_id, bool $viewonly, bool &$edit_again, 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 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
althing_save_report (line 1279)

a dummy routine that pretends to "save" the report selections

this is just a dummy routine to tell the caller that we want to return to althing_show_edit_report() which is where the actual work is done. It is not even necessary to check for either Cancel or OK because that too is done in althing_show_edit_report(). We do set the edit_again flag.

  • return: always FALSE to indicate we need to return to althing_show_edit_report(), always
bool althing_save_report (object &$output, bool $viewonly,  &$edit_again, bool $edit_again)
  • object &$output: collects the html output (if any)
  • 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
althing_save_viewlog (line 1131)

almost a dummy routine but it must exist to handle the lone [Cancel] button

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_save_viewlog (object &$output, bool $viewonly, bool &$edit_again, int $node_id)
  • object &$output: collects the html output (if any)
  • int $node_id: the node to which the content is connected
  • 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
althing_show_content (line 163)

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 althing_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
althing_show_edit (line 133)

dispatcher for showing various dialog screens

there are a few dialogs that are accessed via this routine: - overview: a simple introduction to this module (via $option==NULL) - configuration: all properties of the althing (main althings record) ($option=configuration) - moderation: a list of postings OR an individual post ($option=moderation) - logmessages: a list of all moderation messages for this althing ($option=viewlog)

This routine only handles the main overview dialog, the rest is done in subroutines.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_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
althing_show_edit_configuration (line 245)

show a simple edit screen for the althing configuration

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_show_edit_configuration (object &$output, int $node_id, array $module, bool $viewonly, bool $edit_again, string $href)
  • 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
  • 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
althing_show_edit_moderation (line 414)

present the user with a dialog for moderation of althing posts at node $node_id

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

The following dialogs exist here.

#1. Posts overview

Id Date             E V M Name     Subject
d1 yyyy-mm-dd hh:mm 1 V 0 Nickname Subject
d2 yyyy-mm-dd hh:mm 0 V 0 Nickname Subject
d3 yyyy-mm-dd hh:mm 1 H 0 Nickname Subject
d4 yyyy-mm-dd hh:mm 0 V 0 Nickname Subject
d5 yyyy-mm-dd hh:mm 0 V 0 Nickname Subject
d6 yyyy-mm-dd hh:mm 0 U 0 Nickname Subject

[Cancel]

E=Number of edits, V=Visibility:Visible/Hidden/Unpublished, M=Marbles

#2. Moderation of an individual posting

Prev Up Next

ID: dd (ppp)
Date: yyyy-mm-dd hh:mm:ss
From: Nickname  (registered)
Subject: Subject
IP-address: 127.0.0.1
Xx xx xx xxxxx xx xxxx xx xxxxx xx xxxx

Status: ( ) Unpublished (X) Published
Visible: ( ) Hidden (X) Visible
Marbles:  _____
Remarks:
____________________
____________________
____________________
[Save] [Done] [Cancel]

Prev Up Next

There are some complex interactions between these screens and the corresponding save routine althing_save_moderation(). The effects we try to achieve are as follows.

The listing in dialog #1 shows all posts. Every post ID is a link to dialog #2. The [Cancel] button in dialog #1 ends the editing of this node; ie. returns to Page Manager.

Dialog #2 can be used to change the visibility of a post or to modify the number of marbles. The contents of the remarks field eventually ends up in the log file. The [Cancel] button here bring the user back to dialog #1. In effect this is a kind of zoom function: you can zoom in on a post and go back to the list without leaving this node, etc. etc. Note that the link Up also takes you back to the list in dialog #1, be it that in that case we use afragment to arrive at the correct position in the list. The [Done] button saves the modified post (and the remarks) and also return to dialog #1. The [Save] button always has the meaning "save the data and continue editing".

Note that saving an unchanged record does not yield a message in the log because that would only add noise.

As a service there are simple links Prev, Up and Next which allow for quickly stepping through the posts in detail without having to go back to the list in dialog #1.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_show_edit_moderation (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
althing_show_edit_moderation_list (line 472)

show a tabular overview of all posts in this althing

this shows the main moderation screen: a list of all posts in a user-defined sort order. Re-ordering can be done by clicking the column header. Click twice to reverse the order. Due to space constraints the contents of the moderations column, visibility column and marbles column are just a single character. The explanation of these ad hoc codes is given in the title. Note that the name column also shows the email address via a mouse over (again, to save valuable space).

The list ends with a [Cancel] button which ends the complete edit of this node (i.e. returns to Page Manager).

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_show_edit_moderation_list (object &$output, array &$records, int $node_id, int $sort_index, string $href)
  • object &$output: collects the html output (if any)
  • array &$records: is the ordered array with all posts in this althing
  • int $node_id: the node to which this module is connected
  • int $sort_index: indicates the currently selected sort order
  • string $href: the action property of the HTML-form, the place where data will be POST'ed
althing_show_edit_moderation_post (line 600)

show a single post and allow for moderation of this post

this shows the current contents of the post and allows the moderator to change the visibility and the number of marbles assigned to this post. The moderator is encouraged to add a remark to every moderation action.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_show_edit_moderation_post (object &$output,  &$record, int $node_id, int $sort_index, bool $viewonly, bool $edit_again, array &$records)
  • object &$output: collects the html output (if any)
  • array &$records: is the ordered array with all posts in this althing
  • int $node_id: the node to which this module is connected
  • int $sort_index: indicates the currently selected sort order
  • 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
  • &$record
althing_show_edit_report (line 1147)
void althing_show_edit_report ( &$output,  $node_id,  $module,  $edit_again,  $href)
  • &$output
  • $node_id
  • $module
  • $edit_again
  • $href
althing_show_edit_viewlog (line 980)

show a list of moderation messages to the user

This is basicly a dump of the althing_log_messages table. However, we have tried to jazz it up a little.

The features are as follows. You can arrive here via de link in the submenu. In that case we simply show the available records (all available records) in ascending order, grouped by post_id. This dump consists of a single row in the HTML-table with essential information about the posting to which the messages belong, That row is followed by two rows per logmessage, containinf the date of moderation, the moderator name, the remark and the action.

An additional feature is the link in the header line (the 1st column: ID): clicking that link reverses the order of the list. Also every posting has their own link (via the ID). This link leads to the moderation screen (dialog #2) where this posting can be edited. In that individual post dialog there is a link back to here. However, in this case the output of this routine is limited to the selected posting.

There is also a link in the moderation list (in the moderations column) which yields the messages for a single posting.

The layout of the table is more or less as follows:

    ID Date             Name               Subject/remark 10 yyyy-mm-dd hh:mm Anonymous Coward 4 Re: Chocolate galore    yyyy-mm-dd hh:mm Maria Montessori   Remark of Maria    here-comes-the-action-text-spanning-three-columns

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool althing_show_edit_viewlog (object &$output, int $node_id, array $module, string $href)
  • 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
  • string $href: the action property of the HTML-form, the place where data will be POST'ed

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