File/program/modules/althing/althing_view.php

Description

/program/modules/althing/althing_view.php - interface to the view-part of the althing module

This file defines the interface with the althing-module for viewing content. The interface consists of this function:

    althing_view(&$output,$area_id,$node_id,$module)

This function is called from /index.php when the node to display is connected to this module.

Includes
 require_once (ALTHING_DIRNAME."/althing_common.php") (line 38)
 require_once ($CFG->progdir."/lib/tokenlib.php") (line 41)
Constants
ALTHING_DIRNAME = dirname(__FILE__) (line 37)
ALTHING_REFERENCE = sha1(__FILE__.'":".__LINE__) (line 40)
Functions
althing_show_form (line 868)

show the form where the user/visitor can compose a new post

this routine displays the form where a registered user or an anonymous visitor can compose a new post. There is a difference between the two groups: - users cannot change their name + email; this is copied from $USER, - visitors are allowed to pick their own nicknames and email address Another difference is that only registered users (with sufficient permissions) have an additional link that leads to the file browser.

The file browser allows for inserting a full path into the message area, at the current cursor position. This way the user does not have to type the filename/path when inserting a URL or an IMG.

  • return: output added to $theme
void althing_show_form (object &$theme, array $config, array $dialogdef)
  • object &$theme: collects (html) output
  • array $config: holds the althing configration parameters
  • array $dialogdef: defines the various fields in the dialog
althing_show_overview (line 225)

display the althing information and all published posts OR a single post

this is the main screen that users/visitors usually see on arrival: the header/intro/question, a list of 0,1 or more published posts, and the conclusion and the footer. There are also buttons to [Post] a message or [Harvest] exiting messages.

However, this routine also takes care of requests for a single, individual post. This post is specified via the command line parameter 'post'. If it is specified AND if it identifies a valid (published) message within this Althing that single post is displayed, together with an OK-button. This function is used to direct subscribers and moderators to a specific single message. Note that most links from the single message (parents, children and even self) bring the visitor to the whole althing, ie. they then leave the single post view. (July 2014)

  • return: TRUE on success, FALSE if error retrieving data from DB
bool althing_show_overview (object &$theme, array $config)
  • object &$theme: collects (html) output
  • array $config: holds the althing configration parameters
althing_show_preview (line 959)

show a preview of the post to the user, including references to parents etc.

the user can either submit the post or go back to edit the post

  • return: FALSE if something went wrong, TRUE on succes + post data stored in $post
bool althing_show_preview (object &$theme, array $config,  $dialogdef, string $ip_addr, array $parents, array &$dialogdef)
  • object &$theme: collects (html) output
  • array $config: althing configuration record straight from althings table
  • array &$dialogdef: defines the dialog and will hold POSTed values
  • string $ip_addr: is the address the user/visitor is calling from
  • array $parents: contains parent_id's of this post
  • $dialogdef
althing_show_thankyou (line 1189)

display a thank-you message and the URL of the newly added post

  • return: TRUE to indicate success (always)
bool althing_show_thankyou (object &$theme, array $config, string $ip_addr,  $post, array &$post)
  • object &$theme: collects (html) output
  • array $config: althing configuration record straight from althings table
  • string $ip_addr: is the address the user/visitor is calling from
  • array &$post: a self-contained array returning all information about the post
  • $post
althing_submit_message (line 1040)

store the new post, add relations and send mail to moderators (and maybe subscribers too)

this routine takes care of storing the (validated) data in $data['dialogdef'] and $data['parents'] into the various tables in the database. If all goes well, we also send a mail to the moderators and, if the post was published immediately, the subscribers too. On success, the array $post is filled with the post data, including the newly assigned post_id. It is up to the caller to do something with this returned post data, e.g. display it or whatever.

Storing the data takes a few separate steps. First we need to calculate a display_id which is unique within this althing. Once we have that, we can store the actual post, which yields a fresh (unique) post_id. Subsequently we can use that post_id to store the parent-child-relations in the database.

If that all works out, we always inform the moderators and, if the post was published, also the subscribers. If the post is not visible, the subscribers will be sent a mail lateron, if and when the post is published by a moderator.

  • return: FALSE if something went wrong, TRUE on succes + post data stored in $post
bool althing_submit_message (object &$theme, array $config, array $data, string $ip_addr, int $delay, array &$post)
  • object &$theme: collects (html) output
  • array $config: althing configuration record straight from althings table
  • array $data: contains the (validated) dialogdef and also the post's parents if any
  • string $ip_addr: is the address the user/visitor is calling from
  • int $delay: the # of seconds since time=t0
  • array &$post: a self-contained array returning all information about the post
althing_view (line 52)

display the content of the althing linked to node $node_id

  • return: TRUE on success + output via $theme, FALSE otherwise
bool althing_view (object &$theme, int $area_id, int $node_id, array $module)
  • object &$theme: collects the (html) output
  • int $area_id: identifies the area where $node_id lives
  • int $node_id: the node to which this module is connected
  • array $module: the module record straight from the database
althing_view_dialog_validate (line 923)

validate the data entered by the user/visitor

Other than the standard validation we check for at least 1 @-sign in the email address. (It is non-trivial to validate an email address, it may not even be possible to do it in a single regular expression. See http://stackoverflow.com/questions/201323 for more information.) Note that we only check this field if it is not viewonly. Reason: the user is not able to edit a viewonly field, so an error there would be a fatal error. We don't want that.

Also, we validate the BBCode in the message.

  • return: TRUE if valid, else FALSE + messages added to dialogdef
bool althing_view_dialog_validate (array &$dialogdef)
  • array &$dialogdef: defines the dialog and will hold POSTed values
althing_view_get_dialogdef (line 628)

construct a dialog definition for the add a post form

This defines the add a post form.

  • return: datadefinition
array althing_view_get_dialogdef (array $config, string $token_key, [ $posts = NULL])
  • array $config: althing configuration record straight from althings table
  • string $token_key
  • $posts
althing_view_get_posts (line 559)

get all posts for this althing into an array for easy output

this retrieves data from the database in a specific order (if necessary). via $show=0 it is possible to actually suppress the output of the redacted posts

  • return: TRUE on success + data in &$posts, FALSE otherwise and &$posts == array()
bool althing_view_get_posts (object &$theme, int $althing_id, array &$posts, [int $sort = 1], [int $show = 1])
  • object &$theme: collects (html) output
  • int $althing_id: aka $node_id
  • array &$posts: receives all posts (could be empty array)
  • int $sort: is the sort order of the posts for display: 1=ascending, -1=descending
  • int $show: indicates actual visibility of redacted posts: 1=show redacted, 0=hide redacted.
althing_view_show_post (line 423)

output a single post via $theme

[ ] $author $datim (#$msgid) Subject: $subject Marbles: $marbles (reply to $msgid) In reply to: $p1 Replies: $c1, $c2, $c3 Harvests: $h1

bbcode2html(Content)

Note "In reply to: $p1" might also be 'Harvested from: $p2, $p3, $p4' depending on the post.

Note: preview mode means that the displayed post does not have links to elsewhere which would let the user leave the current page. This is handy for showing a preview of a message that is not yet posted.

Note: the parameter href (default '') is used in the single post display to make sure that the links to the "relations" (parent, children) are absolute, i.e. they link to the full althing page, including headers etc. etc. (the single post page shows only a single post, without the context of the althing).

  • return: TRUE on success + output via $theme, FALSE otherwise
bool althing_view_show_post (object &$theme, array &$post, [bool $visible = TRUE], [bool $frozen = FALSE], [bool $preview = TRUE], [string $odd_even = 'odd'], [string $href = ''])
  • object &$theme: collects the (html) output
  • array &$post: a self-contained array with all information about a single post
  • bool $visible: TRUE is show post, FALSE is show redacted post
  • bool $frozen: FALSE indicates if the althing is open for replies, TRUE means althing is frozen
  • bool $preview: TRUE indicates whether we show this post in preview mode, FALSE=not
  • string $odd_even: used to link CSS parameters to odd and even posts
  • string $href: links to this althing page, used to create absolute links to relations
check_add_reply_harvest (line 768)

check for user action indicating wish to add a post, reply to a post or harvest posts

this checks to see if the user has taken action to start adding a new post. This is the case if

  1. the user pressed the [Post] button
  2. the user clicks the reply-link in an existing post's header
  3. the user selected 0, 1 or more existing posts and pressed the [Harvest] button
If we find that the user does want to add/reply/harvest, we collect the 0, 1 or more posts in an array, keyed by post_id. This array is then returned. If the user does NOT want to add/reply/harvest, we return NULL. If the althing is currently closed or frozen (or rather not open), we tell the user about that and the return value is FALSE.

Note: In step 3A below we identify the checked posts by looking at the $_POST[] array. This is a shortcut, because usually we first setup a dialogdef and subsequently check all the elements in the $dialogdef for their values. We now sort of trust the data in the POST-array; an ordinary user will only be able to have just the checkboxes from the overview checked, leading to an element with key 'p' followed by the post_id (in decimal). An attacker might try to fool us by crafting a post with post_id's from another althing, eg. one hidden in a protected area. We mitigate that by explicitly requiring the althing_id in the WHERE-clause we will be constructing. Another possible danger is specifying many, many, many post_id's. We will limit that via the limit of posts that can be harvested in an althing (there must be a limit, somewhere, right?).

  • return: FALSE on error, NULL if no add/reply/harvest, $posts-array otherwise
bool|null|array check_add_reply_harvest (object &$theme, int $althing_id, int $status)
  • object &$theme: collects (html) output
  • int $althing_id: aka $node_id
  • int $status: tells us about Open/Frozen/Closed status of the althing

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