Methods to access properties of an area
Located in /program/lib/area.class.php (line 42)
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.
determine if an area is private or public
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.
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.
determine which node in which area to show
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.
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.
determine existence of area
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.
fetch breadcrumb trail for a node
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.
get the link_href property of a node
This retrieves the link_href property of the specified $node_id or the default node.
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.
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.
determine the theme to use
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).
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.
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.
Documentation generated on Wed, 11 May 2011 23:44:52 +0200 by phpDocumentor 1.4.0