Class Area

Description

Methods to access properties of an area

  • todo: refactor/change the way the default node and area are calculated from the requested node and area. We now go the the database too often.

Located in /program/lib/area.class.php (line 42)


	
			
Variable Summary
Method Summary
 void Area ([ $requested_area = NULL], [ $requested_node = NULL], int|null $area_id, int|null $node_id)
 bool area_is_private ()
 bool build_tree_of_nodes ( &$records, array $records)
 bool|int calculate_default_descendant_node_id (int $area_id, int|null $subtree_id,  &$node_cache, array $node_cache)
 bool|int calculate_node_id ($requested_area $requested_area, $requested_node $requested_node, $node_cache &$node_cache)
 bool|int calculate_validate_default_node_id ($requested_area $requested_area, $node_cache &$node_cache)
 bool|int calculate_validate_node_id ($requested_area $requested_area, $requested_node $requested_node, $node_cache &$node_cache)
 bool exists ()
 string get_area_title ()
 bool|array get_breadcrumb_anchors ([int $node_id = NULL], [array|null $attributes = NULL])
 array get_childeren (int $node_id, [int $show_hidden_too = FALSE])
 string get_node_link_href ([int|null $node_id = NULL])
 bool|array get_node_record ([int $node_id = NULL])
 bool|string get_node_title ([int $node_id = NULL])
 int get_theme_id ()
 string node2anchor (array $node_record, [array $attributes = NULL], [bool $textonly = FALSE])
 void retrieve_nodes_from_database (int $area_id)
 bool subtree_is_hidden (int $node_id,  &$tree, array $tree)
Variables
bool $area_exists = FALSE (line 65)
  • var: FALSE if area uninitialised/not found, otherwise TRUE
int $area_id = NULL (line 50)
  • var: the actual area id, calculated from $requested_area and $requested_node
array $area_record = FALSE (line 62)
  • var: cached area record from database
the $module = NULL (line 75)
  • var: module that actually provides the content
array $nodes = array() (line 56)
  • var: list of cached node records keyed with node_id
int $node_id = NULL (line 53)
  • var: the actual node id, calculated from $requested_area and $requested_node
int|null $requested_area = NULL (line 44)
  • var: the requested area or NULL if not specified
int|null $requested_node = NULL (line 47)
  • var: the requested node or NULL if not specified
string $table_areas_prefix (line 68)
  • var: the name of the areas table including table prefix
string $table_nodes_prefix (line 71)
  • var: the name of the nodes table including table prefix
array $tree = array() (line 59)
  • var: list of arrays acting as a tree structure of all nodes in the area
Methods
Constructor Area (line 91)

construct an Area object

This initialises the Area by calculating the correct node_id (of a page to show) and area_id. If all goes well, initialisation continues with retrieving _all_ node records in an (ordered) array $this->nodes and subsequently constructing the complete navigation tree from the retrieved node records, taking 'hidden' pages/sections into account. If all is well, the module referenced by the node $node_id is initialised. Success is indicated by setting the variable $this->exists to TRUE.

  • return: the constructor returns nothing but $this->exists is set to TRUE on success
  • uses: $DB
void Area ([ $requested_area = NULL], [ $requested_node = NULL], int|null $area_id, int|null $node_id)
  • int|null $area_id: the number of the area the user requested (or NULL if none specified)
  • int|null $node_id: the number of the node to display (or NULL if none specified)
  • $requested_area
  • $requested_node
area_is_private (line 150)

determine if an area is private or public

  • return: TRUE if area is private, FALSE otherwise
bool area_is_private ()
build_tree_of_nodes (line 664)

construct a complete tree from node records (including 'hidden' nodes)

This iterates through all node records $records and constructs a tree. Nodes/sections without childeren are automatically set to 'hidden'. If all childeren of a node/section are hidden, that node/section is also hidden.

The resulting tree is actually an array keyed with the node_id (and with an additional 'node' 0, see notes below). The order of the array is not relevant because any node can be accessed directly via the key. However, the order is the same as the order of the incoming $records array but with 'node' 0 prepended.

Note 1 It is essential that the incoming array $record is properly ordered, i.e. all nodes first grouped by parent_id and after that sorted by sort_order. This way it is possible to easily construct a linked list of siblings in the correct sort order.

Note 2 The root node of the whole tree has node_id 0. The value 0 is also used to indicate the end of a linked list. Note that there is no node with node_id 0 in the database; the first node has node_id = 1 so there are no conflicts here.

Note 3 The root node in the tree structure has node_id 0. In order to have the top level nodes (ie. nodes directly under the root node) have their parent_id's set to 0 instead of to their own node_id. The reason to use parent_id = node_id is that referential integrity requires that a the parent_id field should have a valid node_id and 0 is not a valid node_id in the database.

  • return: TRUE on success, or FALSE on failure
bool build_tree_of_nodes ( &$records, array $records)
  • array $records: pointer to ordered array of node records (pointer to save stack space)
  • &$records
calculate_default_descendant_node_id (line 562)

calculate the default page in the subtree $subtree_id in area $area_id

This searches for the first default page in the subtree starting at node (of type section) $subtree_id. If $subtree_id is empty, the whole area is searched for a default page.

  • return: FALSE when no node found, the id of the node otherwise
  • uses: MAXIMUM_ITERATIONS - limits the number of levels to try to a sensibele maximum (no endless loops)
bool|int calculate_default_descendant_node_id (int $area_id, int|null $subtree_id,  &$node_cache, array $node_cache)
  • int $area_id: a valid indicator of the area to look at
  • int|null $subtree_id: the id of the starting node of the subtree to search OR null if searching whole area
  • array $node_cache: contains cached records, used to identify circular reference
  • &$node_cache
calculate_node_id (line 376)

determine which node in which area to show

  • return: the node_id of the node to show or FALSE if none available
bool|int calculate_node_id ($requested_area $requested_area, $requested_node $requested_node, $node_cache &$node_cache)
  • $requested_area $requested_area: integer|null the requested node number or null if none specified
  • $requested_node $requested_node: integer|null the requested area number or null if none specified
  • $node_cache &$node_cache: array this referenced variable holds the node records retrieved from the database
calculate_validate_default_node_id (line 400)

calculate and validate the default node from an area or the default area

This determines the default node in the specified area or in the default area if no area was explicitly requested. Returns the node_id OR FALSE if no suitable node can be found.

As a side-effect the node-records that are retrieved from the database in the process are cached in $node_cache, with the corresponding node_id as the key.

  • return: the node_id of the node to show or FALSE if none available
bool|int calculate_validate_default_node_id ($requested_area $requested_area, $node_cache &$node_cache)
  • $requested_area $requested_area: integer|null the requested area number or null if none specified
  • $node_cache &$node_cache: array this referenced variable holds the node records retrieved from the database
calculate_validate_node_id (line 455)

calculate and validate the node to display based on a node and an area or the default area

This determines whether the specified node (and area if specified) is a valid node. If the specified node is not a page (but a section), we descend into the subtree starting at that node until we find a (default) node that is also a page.

If no suitable node can be found, this routine returns FALSE. Otherwise the valid node_id of the page is returned, even if the requested node was a section. In other words: this routine may return another node_id that the one that was requested.

  • return: the node_id of the node to show or FALSE if none available
bool|int calculate_validate_node_id ($requested_area $requested_area, $requested_node $requested_node, $node_cache &$node_cache)
  • $requested_area $requested_area: integer|null the requested node number or null if none specified
  • $requested_node $requested_node: integer|null the requested area number or null if none specified
  • $node_cache &$node_cache: array this referenced variable holds the node records retrieved from the database
exists (line 132)

determine existence of area

  • return: FALSE if area does not exist or object not yet initialised, TRUE otherwise
bool exists ()
get_area_title (line 164)

fetch the title to be used in a HTML-title-tag in the head section

This tries to retrieve the area title. If that title is not defined (i.e. empty), the global title of the site is used.

  • return: title of area or global site title
  • uses: $CFG
string get_area_title ()
get_breadcrumb_anchors (line 240)

fetch breadcrumb trail for a node

  • return: FALSE on error, an ordered array with link information otherwise
bool|array get_breadcrumb_anchors ([int $node_id = NULL], [array|null $attributes = NULL])
  • int $node_id: indicates which node, NULL means the default node
  • array|null $attributes: NULL or an array of key-value-pairs to add to the anchors
get_childeren (line 275)

get an ordered array of node records with parent equal to $node_id

This returns an ordered array of all childeren (pages and sections) of node $node_id. If $node_id is itself a page, then an empty array is returned. Note that only the direct descendants are returned, not the grandchildren.

  • return: an ordered array with node records (can be empty)
array get_childeren (int $node_id, [int $show_hidden_too = FALSE])
  • int $node_id: the direct parent of the nodes that will be returned
  • int $show_hidden_too: if TRUE also the 'hidden' childeren are returned
get_node_link_href (line 297)

get the link_href property of a node

This retrieves the link_href property of the specified $node_id or the default node.

  • return: contents of link_href property
string get_node_link_href ([int|null $node_id = NULL])
  • int|null $node_id: indicates the node to look at or the default node if NULL
get_node_record (line 203)

get a node record, maybe from the cache

This retrieves a node record, either from the cache or otherwise from the database. If data is retrieved from the database it is added to the cache. The possible embargo is taken into account.

  • return: FALSE on error or an array with the node record
bool|array get_node_record ([int $node_id = NULL])
  • int $node_id: indicates the node record to retrieve
get_node_title (line 183)

fetch the title of a node

This tries to retrieve the title of the node. The result could be an empty string; there is no 'built-in' title such as 'page $node_id' or something.

  • return: FALSE on error or title of the node
bool|string get_node_title ([int $node_id = NULL])
  • int $node_id: indicates which node, NULL implies the default node
get_theme_id (line 141)

determine the theme to use

  • return: theme_id for this area
int get_theme_id ()
node2anchor (line 328)

construct an anchor from a node record

This constructs an array with key-value-pairs that can be used to construct an HTML anchor tag. At least the following keys are created in the resulting array: 'href', 'title' and 'anchor'. The latter is either the text or a referenct to an image that is supposed to go between the opening tag and closing tag. Furtermore an optional key is created: target. The contents of the input array $attributes is merged into the result.

If the parameter $textonly is TRUE the key 'anchor' is always text. If $textonly is NOT TRUE, the 'anchor' may refer to an image.

Note that the link text is always non-empty. If the node record has an empty link_text, the word 'node' followed by the node_id is returned. (Otherwise it will be hard to make an actual clickable link).

  • return: an HTML A-tag that links to the node OR to the external link (if any)
string node2anchor (array $node_record, [array $attributes = NULL], [bool $textonly = FALSE])
  • array $node_record: the node record to convert
  • array $attributes: optional attributes to add to the HTML A-tag
  • bool $textonly: if TRUE, no clickable images will be returned
retrieve_nodes_from_database (line 623)

get an array of all available node records in the selected area as assoc arrays

This yields an array of all available (i.e. visible and hidden) nodes in the area. The expired nodes and nodes under embargo are not retrieved; these are considered non-existing.

The array with nodes is ordered by parent_id and sort_order and keyed with the node_id. This sort order helps to create an ordered list of nodes per level.

void retrieve_nodes_from_database (int $area_id)
  • int $area_id: the area for which all nodes are to be retrieved
subtree_is_hidden (line 748)

recursively determine whether all childeren of a node are hidden

This walks the subtree starting at $node_id and returns TRUE if all childeren of this node are hidden or FALSE if at least 1 is not hidden. As a side-effect, a section/node is made hidden if all childeren are hidden, i.e. the results are recorded in the nodes in the $tree.

This recursive routine can be called at most MAXIMUM_ITERATIONS times, preventing endless loops. When this limit is reached, a message is logged (but only once).

Note that the results of subtrees are OR'ed with the is_hidden property of the current node. This means that IF a subtree has all nodes hidden, the node will be made hidden too. Hoever, if a subtree has at least one non-hidden node, the node will not be forced to be unhidden: if it was already hidden it stays that way.

  • return: TRUE if subtree is hidden, FALSE otherwise
bool subtree_is_hidden (int $node_id,  &$tree, array $tree)
  • int $node_id: start of the subtree
  • array $tree: a pointer to the tree (pointer to save stack space)
  • &$tree

Documentation generated on Wed, 11 May 2011 23:44:52 +0200 by phpDocumentor 1.4.0