File/program/modules/confab/confab_admin.php

Description

/program/modules/confab/confab_admin.php - management interface for confab-module

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

    confab_disconnect(&$output,$area_id,$node_id,$module) confab_connect(&$output,$area_id,$node_id,$module) confab_show_edit(&$output,$area_id,$node_id,$module,$viewonly,$edit_again,$href,$option) confab_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__)."/confab_common.php") (line 39)
Functions
confab_config_dialog_validate (line 1145)

validation of configuration dialog + rewriting passcode (no trailing/leading spaces)

  • return: if valid, FALSE otherwise (+messages in dialogdef)
TRUE confab_config_dialog_validate (array &$dialogdef)
  • array &$dialogdef: the dialog to check
confab_connect (line 85)

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 'confabs' record linked to node_id via confab_id.

  • return: TRUE on success, FALSE otherwise
  • uses: $USER
bool confab_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
confab_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 all tables relating to 'confabs*' using node_id == confab_id. Note the order in which the tables are emptied (to satisfy the FK constraints).

  • return: TRUE on success, FALSE otherwise
bool confab_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
confab_get_conversations (line 1354)

retrieve all conversations in reverse chronological order

if something goes wrong, we return an empty array but we do write to the logger

  • return: with conversations keyed by conversation_id
array confab_get_conversations (int $confab_id)
  • int $confab_id
confab_get_dialogdef_configuration (line 934)

construct a dialog definition for the main confab configuration

  • return: dialog definition
array confab_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 confab
confab_get_dialogdef_moderation (line 1158)

construct the moderation dialog

  • return: dialog definition
array confab_get_dialogdef_moderation (array &$participants, bool $viewonly)
  • array &$participants: contains all participants in this conversation
  • bool $viewonly: if TRUE, editing and hence saving is not allowed
confab_get_dialogdef_report (line 1221)

construct the dialog for the reporting tool

  • return: ready to use dialog definition
array confab_get_dialogdef_report (array &$conversations)
  • array &$conversations: ordered list of conversations holds data for list box
confab_save (line 209)

dispatcher for save routines

We use different subroutines for clarity.

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

validate and save the modified confab 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
  • uses: $USER
bool confab_save_configuration (object &$output, int $node_id, bool $viewonly, bool &$edit_again)
  • 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
confab_save_moderation (line 676)

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

this is just a dummy routine to tell the caller that we want to return to confab_show_edit_moderation() 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 confab_show_edit_report(). We do set the edit_again flag.

  • return: always FALSE to indicate we need to return to confab_show_edit_report(), always
bool confab_save_moderation (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
confab_save_report (line 917)

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 confab_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 confab_show_edit_report(). We do set the edit_again flag.

  • return: always FALSE to indicate we need to return to confab_show_edit_report(), always
bool confab_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
confab_show_content (line 161)

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 confab_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
confab_show_edit (line 136)

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 confab (main confabs record) ($option=configuration) - moderation: show current with option to PM users or close the conversation ($option=moderation) - report: a list of _all_ messages in a conversation in this confab ($option=report)

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

show a simple edit screen for the confab configuration

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

present the user with one of two dialogs for moderation of confab posts at node $node_id

the moderation functionality is split into two different dialogs.

The Messagelist dialog looks like this:

[Refresh] [Intervene] [Cancel]
Message N
Message N-1
...
Message 1

The Refresh button updates the list with messages. The Intervene button leads to the second dialog (see below). The Cancel button returns to the overarching Content dialog.

The Intervention-dialog Show a dialog to the user (the moderator) where she can break into the conversation and send (personal) messages to participants OR remove a participant OR remove _all_ participants from the conversation (or end the conversation).

The dialog looks a bit like this:

Action
( ) ~Send a message
( ) ~Remove from conversation
Participant
{listbox-with-participants}
~Message:
[____________] 
[~OK] [~Cancel]
--------------
(list of _all_ messages in reverse order (latest at the top)

The OK button performs the selected action (~Send or ~Remove) with the select Participant (or All participants). If the Message input is not empty, that message is added to the conversation.

The possible scenarios are as follows: - Send the message in 'Message:' to All (using [OK]) - Send the message in 'Message:' to the participant selected in {listbox} (using [OK]) - Remove the selected participant from the conversation (using [OK]) - Effectively end the conversation by removing All participants (using [OK]) - [Cancel] takes the moderator back to the Messagelist dialog screen

The list of messages is ordered in reverse chronological order. The moderator sees _all_ messages, including personal messages The moderator is NOT visible for the regular participants; the name does not show up in the userlist

A moderator can send a personal message to a participant; the participant cannot talk back other than by using a message to all. The moderation only works on the current conversation. Removing all participants from the conversation bumps the conversation too

  • return: TRUE on success + output stored via $output, FALSE otherwise
  • todo: this routine is too long
bool confab_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
confab_show_edit_moderation_list (line 577)

show a button bar and list of messages in the selected conversation

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool confab_show_edit_moderation_list (object &$output, int $confab_id, int $conversation_id, bool $viewonly, string $href)
  • object &$output: collects the html output (if any)
  • int $confab_id
  • int $conversation_id
  • 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
confab_show_edit_moderation_messages (line 614)

create a list of all message in chronological order descending

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool confab_show_edit_moderation_messages (object &$output, int $confab_id, int $conversation_id)
  • object &$output: collects the html output (if any)
  • int $confab_id
  • int $conversation_id
confab_show_edit_report (line 725)

present the user with a dialog for creating reports on confab conversations at node $node_id

This is basically the following dialog followed by the results of the constructed query based on the previous dialog contents:

Con~versation
[listbox with conversations]

Fields:
[ ] ~Message ID
[ ] ~Author
[ ] ~Remote address
[ ] ~Date
[ ] ~Text
Messages from:
( ) ~System
( ) ~User
( ) ~Both
Messages to:
( ) ~Group
( ) ~Individual
( ) Bot~h

[~OK] [~Cancel]

The fields checkboxes determine which data is displayed. The two radio buttons are added to the selection criteria (AND'ed together). If the selections yield no data, message is displayed, otherwise all checked fields of the selected records are displayed.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool confab_show_edit_report (object &$output, int $node_id, array $module, 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 $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

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