Class AreaManager

Description

Methods to access properties of an area

This class is used to manage areas. The following functions are supplied

  • add a new area (requires PERMISSION_SITE_ADD_AREA)
  • set default area (requires PERMISSION_AREA_EDIT_AREA)
  • delete existing area (requires PERMISSION_SITE_DROP_AREA)
  • edit area properties (requires PERMISSION_AREA_EDIT_AREA)
  • view list of areas (requires permissions for add, edit, delete or ACL_ROLE_INTRANET_ACCESS)
The default action is to show a list of existing areas for which the user has some form of permission. This could be either one of the permissions mentioned above or the permission to view the area (intranet).

  • todo: we need to take care of spurious spaces in inputs (or do we?)

Located in /program/lib/areamanager.class.php (line 62)


	
			
Variable Summary
 array $areas
 object|null $output
Method Summary
 AreaManager AreaManager (object &$output)
 void area_add ()
 void area_delete ()
 void area_edit (int $area_id)
 void area_edittheme ()
 void area_overview ()
 void area_resettheme ()
 void area_save ()
 void area_savenew ()
 void area_setdefault ()
 array a_param (string $chore, [int|null $area_id = NULL])
 int count_existing_theme_properties (int $area_id, int $theme_id)
 array get_dialogdef_edit_area (int $area_id)
 void get_dialog_data (array &$dialogdef, array $record)
 string get_icon_delete (int $area_id)
 string get_icon_edit (int $area_id)
 string get_icon_home (int $area_id, array &$areas)
 array|bool get_theme_records ([bool $forced = FALSE])
 TRUE reset_theme_defaults (int $area_id, int $theme_id)
 void show_edit_menu (int $area_id, [string $current_chore = ''])
 int sort_order_new_area ([bool $at_begin = FALSE])
Variables
array $areas = array() (line 67)
  • var: list of cached area records keyed with area_id
object|null $output = NULL (line 64)
  • var: collects the html output
bool $show_parent_menu = FALSE (line 70)
  • var: if TRUE the calling routing is allowed to use the menu area (e.g. show config mgr menu)
Methods
Constructor AreaManager (line 79)

construct an AreaManager object

This initialises the AreaManager and also dispatches the chore to do.

  • uses: $CFG
AreaManager AreaManager (object &$output)
  • object &$output: collects the html output
area_add (line 287)

present a dialog where the user can enter minimal properties for a new area

this displays a dialog where the user can enter the minimal necessary properties of a new area. These properties are:

  • name
  • public or private
  • the theme to use
Other properties will be set to default values and can be edited lateron, by editing the area.

The new area is saved via performing the 'chore' AREAMANAGER_CHORE_SAVE_NEW.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
void area_add ()
area_delete (line 403)

delete an area from ths site after confirmation

this either presents a confirmation dialog to the user OR deletes an area. First the user's permissions are checked and also there should be no nodes left in the area before anything is done. Only allowing deletion of an empty area is safety measure: we don't want to accidently delete many many nodes from an area in one go (see also task_node_delete()). Also, we don't want to introduce orphaned node records (by deleting the area record without deleting nodes).

Note that this routine could have been split into two routines, with the first one displaying the confirmation dialog and the second one 'saving the changes'. However, I think it is counter-intuitive to perform a deletion of data under the name of 'saving'. So, I decided to use the same routine for both displaying the dialog and acting on the dialog.

  • return: results are returned as output in $this->output
  • todo: since multiple tables are involved, shouldn't we use transaction/rollback/commit? Q: How well is MySQL suited for transactions? A: Mmmmm.... Which version? Which storage engine?
  • uses: $USER
void area_delete ()
area_edit (line 710)

show the basic properties edit dialog and the edit menu

Note that this dialog does NOT allow every area property to be edited: the path to the datafiles is readonly. It feels too complicated to allow the user to actually change the path because in that case we need to move all existing files to the new location, etc. etc. I did consider to allow the GURU to perform that task (ie editing the path), but eventually decided against it: it is simply not worth it. However, if you know the way to the database and manually edit the path field you can do so, but in that case you're on your own... The user can see the path but not touch it.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
void area_edit (int $area_id)
  • int $area_id: indicates which area to edit
area_edittheme (line 550)

show the theme/area configuration dialog and the edit menu

this displays the list of configurable properties of the theme currently associated with this area in a dialog so that the user can modify the values. Since the area-theme configuration is a more or less 'standard' list of properties, we can use the generic configuration manipulator contained in the ConfigAssistant class.

  • return: results are returned as output in $this->output
  • uses: ConfigAssistant
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
void area_edittheme ()
area_overview (line 198)

display list of areas with edit/delete icons etc. and option to add an area

this constructs the heart of the area manager: an optional link to add an area followed by a list of links for all areas to which the user has access. From here the user can set the default area, attempt to delete an area and edit the basic and advanced properties of an area. All actions that manipulate an area return here eventually.

Note that the calling routine (the configuration manager) is allowed to display a menu because we set the parameter show_parent_menu to TRUE here.

The constructed list looks something like this:

                 Add an area [H] [D] [E] (public) Exemplum Primary School (1, 10) [ ] [D] [E] (private) Exemplum Intranet (2, 20) [ ] [D] [E] (public) Exemplum Inactive (3, 30) (inactive) ...

The clickable icons [H] and [ ] manipulate the default area The clickable icons [D] lead to a Delete area confirmation dialog The clickable icons [E] lead to the Edit area (theme parameters) The clickable titles lead to the Edit area (basic parameters) The clickable link 'Add an area' leads to the add new area dialog.

The area titles are dimmed (grayed-out) if the user is able to see these areas (because they're public or the user has at most intranet acces for that area). Private areas for which the user has no access at all don't show up in the list. If the user has Edit-permissions, the area title is not dimmed and the area can be edited.

  • return: results are returned as output in $this->output
  • todo: should we add a paging function to the list of areas? Currently all areas are shown in a single list...
  • todo: should we make two categories: 'public' and 'private' in the list of areas? Maybe handy when there are many manu areas, but it would be inconsistend with the page manager menu which simply lists the areas in the sort order. Easy way out: the user is perfectly capable to set the sort order in such a way that the sort order already groups the public and private areas. Oh well....
  • uses: $WAS_SCRIPT_NAME
  • uses: $CFG
  • uses: $USER
void area_overview ()
area_resettheme (line 617)

reset the theme configuration to the factory defaults

this is a two-step process: we either show a confirmation dialog or we actually overwrite the existing theme configuration with the default values.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $DB
  • uses: $CFG
void area_resettheme ()
area_save (line 753)

validate and save modified data to database

this saves data from both the edit and the edit theme dialog if data validates. If the data does NOT validate, the edit screen is displayed again otherwise the area overview is displayed again.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
void area_save ()
area_savenew (line 933)

save the newly added area to the database

This saves the essential information of a new area to the database, using sensible defaults for the other fields. Also, a data directory is created and the relative path is stored in the new area record.

If something goes wrong, the user can redo the dialog, otherwise we return to the area overview.

  • return: results are returned as output in $this->output
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
void area_savenew ()
area_setdefault (line 328)

make the selected area the default for the site

this sets a default area. First we check permissions and if the user

  • is allowed to set the default bit on the target area, AND
  • is allowed to reset the default bit on the current default area
We actually
  • reset the default bit from the current default (if there is one), AND
  • set the default bit for the selected node.
Note: if the user sets the default node on the current default node, the default is reset and subsequently set again (two trips to the database), This also updates the mtime of the record.

  • return: results are returned as output in $this->output
  • todo: should we send alerts? If so, can we use the routine to queue messages from pagemanager? A reason not to send alerts: the alerts will be sent as soon as a page is added to the new area, so why bother?
  • todo: should we acknowledge the changed default to the user or is it enough to see the icon 'move'?
  • uses: $USER
void area_setdefault ()
a_param (line 1531)

shorthand for the anchor parameters that lead to the area manager

  • return: ready-to-use array with parameters for constructing a-tag
array a_param (string $chore, [int|null $area_id = NULL])
  • string $chore: the next chore that could be done
  • int|null $area_id: the area of interest or NULL if none
count_existing_theme_properties (line 1634)

determine the number of existing properties for a theme in an area

  • return: number of existing properties
int count_existing_theme_properties (int $area_id, int $theme_id)
  • int $area_id
  • int $theme_id
get_dialogdef_add_area (line 1086)

construct the add area dialog

this constructs an add area dialog definition with the bare minimal fields.

  • return: contains the dialog definition
array get_dialogdef_add_area ()
get_dialogdef_delete_area (line 1343)

construct the delete area dialog

this is basically two buttons and a CSRF token

  • return: contains the dialog definition
array get_dialogdef_delete_area ()
get_dialogdef_edit_area (line 1151)

construct the edit area basic properties dialog

Note that this dialog makes the private/public flag readonly; this field is only displayed. Also note that the datadirectory path is shown readonlye too. It is simply too much hassle to allow the user to change this path because that would imply that the existing files should move along. We'll keep it simple. However, it must be possible to look up the name of the data dir, so therefore we do display it.

  • return: contains the dialog definition
array get_dialogdef_edit_area (int $area_id)
  • int $area_id: indicates for which area
get_dialog_data (line 1239)

fill the dialog with current area data from the database

Note that area_path is no longer a part of the dialogdef (see also get_dialogdef_edit_area()) but if it were, the data would still be fetched.

  • return: &$dialogdef is filled with data from the record
void get_dialog_data (array &$dialogdef, array $record)
  • array &$dialogdef: contains dialog definition that requires the data
  • array $record: conveniently holds a copy of the area record
get_icon_delete (line 1477)

construct a clickable icon to delete this area

  • return: ready-to-use A-tag
  • todo: should we check to see if the area is empty before showing delete icon? Or is it soon enough to refuse deletion when the user already clicked the icon? I'd say the latter. For now...
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
string get_icon_delete (int $area_id)
  • int $area_id: the area to delete
get_icon_edit (line 1505)

construct a clickable icon to edit theme properties of this area (edit advanced)

  • return: ready-to-use A-tag
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
string get_icon_edit (int $area_id)
  • int $area_id: the area to edit
get_icon_home (line 1421)

construct a clickable icon to set the default area

the 'default' icon is displayed for the default area, the 'non-default' icon for all others. The user is allowed to make the area the default area if the user has edit permissions for both the old and the new default area.

  • return: ready-to-use A-tag
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
string get_icon_home (int $area_id, array &$areas)
  • int $area_id
  • array &$areas: records with area information of all areas
get_options_themes (line 1283)

fetch a list of themes available for an area

this retrieves a list of themes that can be used as a list of options in a listbox or radiobuttons. Only the active themes are considered. The names of the themes that are displayed in the list are translated (retrieved from the themes language files). The list is ordered by that translated theme name.

  • return: ready for use as an options array in a listbox or radiobuttons
array get_options_themes ()
get_theme_records (line 1324)

retrieve a list of all available theme records

this returns a list of active theme-records or FALSE if none are are available The list is cached via a static variable so we don't have to go to the database more than once for this. Note that the returned array is keyed with theme_id.

  • return: FALSE if no themes available or an array with theme-records
array|bool get_theme_records ([bool $forced = FALSE])
  • bool $forced: if TRUE forces reread from database (resets the cache)
reset_theme_defaults (line 1587)

reset the theme properties of an area to the default values

this deletes any existing properties for the combination of $area_id and $theme_id from the properties table. After that, a copy of the defaults of the theme $theme_id is inserted in the areas-themes properties table. _Eventually_ this may exhaust the available primary keys in the area-theme-properties table. Oh well: with a handful of properties each time you need a lot of resets...

This routine returns TRUE on success or FALSE on error. In the latter case either we were not able to delete old values OR we were not able to insert a copy of the default properties.

  • return: on success, FALSE on failure
TRUE reset_theme_defaults (int $area_id, int $theme_id)
  • int $area_id
  • int $theme_id
show_edit_menu (line 1368)

display the edit menu via $this->output

This displays a clickable menu on in the menu area.

  • return: results are returned as output in $this->output
void show_edit_menu (int $area_id, [string $current_chore = ''])
  • int $area_id: the area currently being edited
  • string $current_chore: the currently selected edit screen (used to emphasize the option in the menu)
show_parent_menu (line 140)

allow the caller to use the menu area (or not)

this routine tells the caller if it is OK to use the menu area (TRUE returned) or not (FALSE returned).

  • return: TRUE if menu area is available, FALSE otherwise
bool show_parent_menu ()
sort_order_new_area (line 1554)

determine the value for the sort order of a new area

this calculates a new sort order value based on the existing minimum or maximum values of existing areas (if any).

Note The default sort order for areas differs from that of pages and sections: we assume that the person managing areas knows where to find the newly added area (at the bottom) whereas for a page/section maintainer it is probably more convenient to have a new page/section added at the top of the (perhaps very long) list.

  • return: ready-to-use value for sort order of a new record
int sort_order_new_area ([bool $at_begin = FALSE])
  • bool $at_begin: if TRUE the new area is placed before all others, otherwise it is added at the end

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