File/program/modules/snapshots/snapshots_admin.php

Description

/program/modules/snapshots/snapshots_admin.php - management interface for snapshots-module

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

    snapshots_disconnect(&$output,$area_id,$node_id,$module) snapshots_connect(&$output,$area_id,$node_id,$module) snapshots_show_edit(&$output,$area_id,$node_id,$module,$viewonly,$edit_again,$href,$option) snapshots_save(&$output,$area_id,$node_id,$module,$viewonly,&$edit_again,$option)

These functions are called from pagemanagerlib.php whenever necessary.

Functions
snapshots_check_path (line 389)

validate and massage the user-supplied data path

this checks the directory path the user entered, returns TRUE if the tests are passed.

There three places from which snapshots can be retrieved:

  • /areas/aaa
  • /users/uuu
  • /groups/ggg
That is: the path should at least contain 2 levels (and possibly more). In other words: a bare '/' is not enough and neither are bare '/areas', '/users' or '/groups'. And of course the directory should already exist in the file systen under $CFG->datadir.

Various tests are done: - the selected area directory must be active - if the selected area is private, $USER must have intranet access for this area, OR the selected area must be the same as the area in which $node_id resides - the selected user directory must be the $USER's, OR the $USER has access to the account manager (able to manipulate ALL users' directories) - the selected group directory must be from a group the $USER is a member of, OR the $USER has access to the account manager (able to manipulate ALL groups' directories)

If all tests succeed, we may want to warn the user in the case that the file location is in a different (and public) area than the node holding the snapshots module. However, this is a warning only.

Finally, we reconstruct the path in such a way that it starts with a slash and does NOT end with a slash. This is done by changing the content of the $item parameter.

  • return: TRUE if valid path, otherwise FALSE + messages in dialogdef
  • todo: should the user / group really be active here? If not, the images will fail in file.php but that may leak information about inactive users. Hmmm...
  • todo: we should use a different error message as soon as it is available in was.php, eg. 'validate_bad_directory' (much like 'validate_bad_filename').
bool snapshots_check_path (array &$item, int $area_id, int $node_id)
  • array &$item: holds the field definition from the $dialogdef for the snapshots_path
  • int $area_id: the area in which we are editing a snapshot module configuration
  • int $node_id: the node to which the snapshot module is connected (unused)
snapshots_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 simply link a single 'variant' parameter to node $node_id in a 1-to-1 relation.

Note that we set the parameter 'variant' to 1. This equates to the variant where the visitor starts with the title, the optional introductory text and the thumbnail overview. It is up to the user to configure the node to use other variants, eg. start at the first picture full-size or display a slide show. Also note that we start off with an (arbitrary) dimension for the full-size snapshots. This is a per-node setting (as opposed to the systemwide setting for thumbnail dimensions). Finally, we do a little heuristics here by plugging in the current directory from the filemanager. This is dirty, but we might assume that the user uploaded the files to a directory just before adding this snapshots node. In that case there is no need to change anything re: path. If the user did NOT upload files, we plug in the name of the directory which is associated with area $area_id.

  • return: TRUE on success, FALSE otherwise
bool snapshots_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
snapshots_disconnect (line 51)

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 record with the snapshots variant + introduction.

  • return: TRUE on success, FALSE otherwise
bool snapshots_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
snapshots_get_dialogdef (line 274)

construct a dialog definition for the snapshots configuration data

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

save the modified content data of this module linked to node $node_id

this validates and saves the data that was submitted by the user. If validation fails, or storing the data doesn't work, 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 and the value of $edit_again is based on the button used to save ([Save] or [Done]).

Here is a summary of return values.

$retval | $edit_again | Action
------- | ----------- | ------
FALSE   | FALSE       | [Cancel] Stop editing, unlock & return to tree view
FALSE   | TRUE        | [Save] or [Done] failed: redo the dialog and let user correct mistakes
TRUE    | FALSE       | [Done] pressed, everything saved succesfully, we're done
TRUE    | TRUE        | [Save] pressed, everything saved succesfully but continue editing

The parameter $option is not used in this module.

  • return: TRUE on success + output stored via $output, FALSE otherwise
bool snapshots_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: indicates which submenu-option was selected (NULL for none)
snapshots_show_edit (line 146)

present the user with a dialog to modify the snapshots that are connected to node $node_id

this prepares a dialog for the user filled with existing data (if any), possibly allowing the user to modify the content. If the flag $viewonly is TRUE, this routine should only display the content rather than let the user edit it. If the flag $edit_again is TRUE, the routine should use the data available in the $_POST array, otherwise it should read the data from the database (or wherever the data comes from). The parameter $href is the place where the form should be POST'ed.

The dialog should be added to the $output object. Useful routines are:

    $output->add_content($content): add $content to the content area $output->add_message($message): add $message to the message area (feedback to the user) $output->add_popup_bottom($message): popup $message in browser after loading the page (uses javascript) $output->add_popup_top($message): popup $message in browser before loading the page (uses javascript)

The parameter $option is not used in this module.

  • return: TRUE on success + output stored via $output, FALSE otherwise
  • todo: we might want to jazz up this dialog by adding some sort of 'directory browser' for the snapshots_path field using a pop-up window. Mmmmm.... future refinements...
bool snapshots_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: indicates which submenu-option was selected (NULL for none)

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