File/program/main_index.php

Description

/program/main_index.php - workhorse for visitor interface

This file deals with the visitor interface. It is included and called from /index.php.

The work is done in main_index().

Parameters are passed like index.php?parm=val. Here is an overview of recognised global parameters that are handled here (and not in a module).

  • logout - used to end a user's session (no need for a value, just the param is enough)
  • login=i - step i of the login procedure
  • area=a - indicates which area to access; if specified it should match the node, if that is specified
  • node=n - indicates which node to access; if specified it should match the area, if that is specified
  • language=xx - indicates the language to use; xx is a valid language code like 'en', 'de', 'fr' or 'nl'

  • author: Peter Fokker <peter@berestijn.nl>
  • version: $Id: main_index.php,v 1.15 2016/03/23 09:28:32 peter Exp $
  • copyright: Copyright (C) 2008-2016 Ingenieursbureau PSD/Peter Fokker
  • todo: add the performance results in a HTML-comment if not CFG->debug, in sight otherwise
  • license: GNU AGPLv3+Additional Terms
Functions
calculate_area (line 284)

try to retrieve a valid area record based on values of requested area and requested node

this determines which area to use. If the user specifies nothing (no area, no node), we simply go for the default area or the first available area. If the user does specify an area and/or a node, we use that information to get to the area. Note that if the user specifies both area and node, the two should match. That is: you cannot specify a node from area X and also request area Y: that yields no results. If only a node is specified, the area is calculated from the area to which the node belongs.

We let the database do most of the work by constructing and executing an appropriate SQL-statement.

  • return: FALSE on error/not found, otherwise an array with a complete area record from database
  • uses: $DB
bool|array calculate_area (int|null $requested_area, int|null $requested_node)
  • int|null $requested_area: the area the user specified or NULL if no area specifically requested
  • int|null $requested_node: the node the user specified or NULL if no node specifically requested
calculate_default_page (line 377)

try to find a default page within a subtree of pages and sections

this walks the tree $tree starting at $subtree_id looking for a default page. We give it three tries. First we look for a default node in the section of which $subtree_id is the first node. If we find a page, we're done, if we find a section we descend into that subsubtree. If there still is no default page, we go look for any page in the initial set of nodes. If that too doesn't yield a page, we descend into the subsubtrees. If THAT doesn't yield a page we give up and return FALSE, indicating no page to be found.

  • return: FALSE if no page is to be found, the $node_id of the page otherwise
bool|int calculate_default_page (array &$tree, int $subtree_id)
  • array &$tree: a reference to the complete tree in the area of interest
  • int $subtree_id: the place where we need to start looking (usually the first_child_id of the parent)
calculate_node_id (line 344)

calculate and validate the node_id to display

this tries to determine a valid node to display based on the node the user requested and the area that the user may or may not have requested.

Basic assumption is that the visitor has indeed view access to area $area_id. This means that the user is allowed to see the nodes in this area that are not under embargo (and not expired). We do have a complete overview of all nodes in this area in the array $tree. (See tree_build() for more information about the tree structure)

The parameter $requested_node is either an integer, indicating the user explicitly specified a node number in the page request, or null, indicating that the user did not explicitly specify a node. In the latter case the user may or may not have explicitly requested an area.

There are several cases we need to handle - if no node is explicitly requested, we need to identify the default page in the area - if the node is under embargo the node does not exist (from the POV of the user) - if the requested node is a section, we need to identify the default page in that section

  • return: FALSE if no suitable node found or a valid $node_id
bool|int calculate_node_id (array &$tree, int $area_id, int|null $requested_node)
  • array &$tree: a reference to the complete tree in area $area_id
  • int $area_id: the area where we are looking for a node
  • int|null $requested_node: the node_id the user requested or NULL if none was specified
main_index (line 50)

main program for visitors

this routine is called from /index.php. It is the main program for visitors.

  • return: page sent to the browser
  • todo: cleanup login/logout-code
void main_index ()
module_load_view (line 479)

load the visitor/view interface of a module in core

this includes the 'view'-part of a module via 'require_once()'. This routine first figures out if the view-script file actually exists before the file is included. Also, we look at a very specific location, namely: /program/modules/<modulename>/<module_view_script> where <modulename> is retrieved from the modules table in the database.

Note that if modulename would somehow be something like "../../../../../../etc/passwd\x00", we could be in trouble...

  • return: FALSE on error or an array with the module record from the modules table
  • todo: should we sanitise the modulename here? It is not user input, but it comes from the modules table in the database. However, if a module name would contain sequences of "../" we might be in trouble
bool|array module_load_view (int $module_id)
  • int $module_id: indicates which module to load
module_view (line 436)

call the routine that generates the view (content) of module $module_id

this loads the file containing the visitor interface for module $module_id in core and subsequently calls the routine responsible for displaying the content (function modulename_view()). The routine module_view() is supposed to deposit any output into the $theme via the appropriate methods such as $theme->add_content().

  • return: FALSE on error, return value of modulename_view() otherwise
bool module_view (array &$theme, int $area_id, int $node_id, int $module_id)
  • array &$theme: a reference to the output object
  • int $area_id: the area where we are looking for a node
  • int $node_id: the node we are working with
  • int $module_id: the module connected to the node we are working with
update_statistics (line 516)

update all statistics for the view of page $node_id

this is a place for future extension. This routine is called once for every page view. It can be used to record relevant data in a table, for future reference, e.g.

  • the IP-address of the visitor
  • the $node_id
  • the current date/time
  • the number of views of node $node_id from the visitor's IP-address
  • etc. etc.
Note that the table holding this information can quickly become very large. That requires some form of logrotate or condensing the data. This feature has yet to be developed.

  • return: we assume that everything goes well and if it doesn't: too bad.
  • todo: maybe extend this routine to actually store more statistics information in a separate table
void update_statistics (int $node_id)
  • int $node_id: the page (node) that was viewed
update_view_count (line 529)

update the view count for page $node_id

  • return: we assume that everything goes smooth, and if it doesn't: too bad.
void update_view_count (int $node_id)
  • int $node_id: the page (node) that need its view_count incremented with 1

Documentation generated on Tue, 28 Jun 2016 19:10:29 +0200 by phpDocumentor 1.4.0