File/program/modules/snapshots/snapshots_install.php

Description

/program/modules/snapshots/snapshots_install.php - installer of the snapshots module

This file contains the snapshots module installer. The interface consists of these functions:

    snapshots_install(&$messages,$module_id) snapshots_upgrade(&$messages,$module_id) snapshots_uninstall(&$messages,$module_id) snapshots_demodata(&$messages,$module_id,&$config,$manifest)

These functions can be called from the main installer and/or admin.php.

Note You cannot be sure about the environment from which these routines are called. If the caller is the Install Wizard, you do not have all subroutines available. However, it IS possible to manipulate the database via the db_*() routines and/or the global $DB object. Therefore you have to keep the install routine extremly simple. You also have no option to interact with the user; the install has to be a silent install; you can only indicate success (TRUE) or failure (FALSE) and maybe an error message in $messages[] but that's it. Good luck.

Functions
snapshots_demodata (line 184)

add demonstration data to the system

this routine adds to the existing set of demonstration data as specified in $config. Here we add a node as follows:

'snapshots': a page in section 'showcase' acting as an example set of snapshots

The page 'snapshots' is added at the bottom of the demo-section 'showcase' in the MyPage section. This is our (new) place to show off new modules.

Note If the module is installed via the Install Wizard, this routine is called. However, if a module is installed as an additional module after installation, the {$module}_demodata() routine is never called. This is because the only time you know that demodata is installed is when the Install Wizard runs. If we're called from admin.php, the webmaster may have already deleted existing (core) demodata so you never can be sure what to expect. To put it another way: it is hard to re-construct $config when we're NOT the Instal Wizard.

The array $config contains the following information.

    $config['language_key']   => install language code (eg. 'en') $config['dir']            => path to CMS Root Directory (eg. /home/httpd/htdocs) $config['www']            => URL of CMS Root Directory (eg. http://exemplum.eu) $config['progdir']        => path to program directory (eg. /home/httpd/htdocs/program) $config['progwww']        => URL of program directory (eg. http://exemplum.eu/program) $config['datadir']        => path to data directory (eg. /home/httpd/wasdata/a1b2c3d4e5f6) $config['user_username']  => userid of webmaster (eg. wblader) $config['user_full_name'] => full name of webmaster (eg. Wilhelmina Bladergroen) $config['user_email']     => email of webmaster (eg. w.bladergroen@exemplum.eu) $config['user_id']        => numerical user_id (usually 1) $config['demo_salt']      => password salt for all demodata accounts $config['demo_password']  => password for all demodata accounts $config['demo_areas']     => array with demo area data $config['demo_groups']    => array with demo group data $config['demo_users']     => array with demo user data $config['demo_nodes']     => array with demo node data $config['demo_string']    => array with demo strings from /program/install/languages/LL/demodata.php $config['demo_replace']   => array with search/replace pairs to 'jazz up' the demo strings

With this information, we can add a demonstration configuration for the public area, which shows off the possibilities. Note that we add our own additions to the array &$config so other modules and themes can determine the correct status quo w.r.t. the demodata nodes etc.

Update June 2016: we now add a second demo page, in the main tree under 'News' - 'Archives' called 'snapshots2'. This is basically a copy of the first snapshots demo but showing a different variant (just for fun).

  • return: TRUE on success + output via $messages, FALSE otherwise
bool snapshots_demodata (array &$messages, int $module_id, array &$config, array $manifest)
  • array &$messages: collects the (error) messages
  • int $module_id: the key for this module in the modules table
  • array &$config: pertinent data for the new website + demodata foundation
  • array $manifest: a copy of the manifest for this module
snapshots_install (line 63)

install the module

this routine installs the module. For this module there is nothing to install, so we simply return success. The appropriate table is already created based on the tabledefs); see install/snapshots_tabledefs.php.

Note that the record for this module is already created in the modules table; the pkey is $module_id.

  • return: TRUE on success + output via $messages, FALSE otherwise
bool snapshots_install (array &$messages, int $module_id)
  • array &$messages: collects the (error) messages
  • int $module_id: the key for this module in the modules table
snapshots_uninstall (line 121)

uninstall the module

this is a hook for future extensions of Website@School. For now we simply return success. Any real code could look like this: DELETE FROM snapshots; to delete all existing data (but who would want that). For now this is simpky a nop.

Note that bluntly deleting from the snapshots table might lead to nodes without a valid module. The better way to do it would be something like this:

    SELECT count(node_id) AS number_of_nodes FROM snapshots; if ($number_of_nodes > 0) then     $messages[] = 'There are still $number_of_nodes nodes with a snapshots';     return FALSE;
which in fact means that the table should already be empty before we can empty it. Oh well...

  • return: TRUE on success + output via $messages, FALSE otherwise
bool snapshots_uninstall (array &$messages, int $module_id)
  • array &$messages: collects the (error) messages
  • int $module_id: the key for this module in the modules table
snapshots_upgrade (line 91)

upgrade the module

this routine performs an upgrade to the installed module. Note that this minimalistic 'snapshots' module does not need any upgrade at all because there never was an earlier version.

However, if there was to be a newer version of this module, this routine is THE place to bring the database up to date compared with the existing version. For example, if an additional field 'snapshots_extension' was to be added to the snapshots-table, it could be added using a suitable (default) value, e.g. an empty string or whatever

Any existing snapshots could then be updated here to fill the new field with data, e.g.

UPDATE snapshots SET snapshots_extension = '';

etcetera. For now this routine is a nop.

  • return: TRUE on success + output via $messages, FALSE otherwise
bool snapshots_upgrade (array &$messages, int $module_id)
  • array &$messages: collects the (error) messages
  • int $module_id: the key for this module in the modules table

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