File/program/modules/althing/althing_common.php

Description

/program/modules/althing/althing_common.php - code shared between admin and view

This file defines various constants and subroutines used from both and althing_view.php.

Constants
ALTHING_DEFAULT_VISIBILITY = ALTHING_DEFAULT_VISIBILITY_HIDDEN (line 38)
ALTHING_DEFAULT_VISIBILITY_HIDDEN = 0 (line 34)
ALTHING_DEFAULT_VISIBILITY_REGISTERED = 1 (line 35)
ALTHING_DEFAULT_VISIBILITY_VISIBLE = 2 (line 36)
ALTHING_HARVEST_LIMIT = 10 (line 39)
ALTHING_MARBLES_LIMIT = 10 (line 40)
ALTHING_STATUS_CLOSED = 2 (line 32)
ALTHING_STATUS_FROZEN = 1 (line 31)
ALTHING_STATUS_OPENED = 0 (line 30)
Functions
althing_get_emails (line 58)

create a neat array with email-addresses from a (possibly messy) text

this routine converts a (messy) list of email addresses to an array with a single address per array element. If there are no addresses, an empty array is returned. The addresses are supposed to be comma-delimited and/or newline and/or space delimited. Note that we expect only plain email addresses, no readable names etc. (KISS)

  • return: with one email address per element (or an empty array)
array althing_get_emails (string $buffer)
  • string $buffer: holds the messy list of email addresses
althing_send_alerts (line 113)

send an alert message to every email address in $emails

this routine sends an individual message to each of the addresses in the array $emails notifying the receiver about the new post. Relevant information (headers) are taken from the $post-record. Note that we attempt to leak as less information as is possible, eg. we don't show email addresses of posters, or the contents, or other information like the name of the page (which could be in a private area) or the title of the althing.

There are several combinations flags that yield different mails to be sent. Here is a truth-table:

    Visible Moderator Private Message            Subject  FALSE   FALSE    FALSE   public_published   [nn] Public post #xx is now published  FALSE   FALSE     TRUE   private_published  [nn] Private post #xx is now published  FALSE   TRUE     FALSE   moderation         [nn] Moderation request for post #xx  FALSE   TRUE      TRUE   moderation         [nn] Moderation request for post #xx   TRUE   FALSE    FALSE   public_visible     [nn] New public post #xx   TRUE   FALSE     TRUE   private_visible    [nn] New private post #xx   TRUE   TRUE     FALSE   public_visible     [nn] New public post #xx   TRUE   TRUE      TRUE   private_visible    [nn] New private post #xx

Note that most messages contain a warning about the need to login first (either for accessing the private area OR for accessing the admin interface for moderation). In total there are 5 different messages. These can be adapted via the Translate Tool.

Note that the messages 'public_published' and 'private_published' are to be sent once a moderator publishes an unpublished post (ie. makes the post visible for the first time). This means that in that case we are called from althing_admin.php at moderation time rather than from althing_view.php at submit-time.

Note: the URL in the mail now uses the new parameter 'post' to select a single message for display (see also althing_show_overview() in althing_view.php). By showing only a single post, the user is not distracted by other messages that were already there (July 2014).

  • return: TRUE on success + messages mailed out, FALSE if an error occurred
bool althing_send_alerts (array $emails, bool $moderator, bool $private, bool $visible, int $area_id, array $post)
  • array $emails: holds all email addresses to send an alert to
  • bool $moderator: TRUE if emails are of moderators, FALSE means subscribers
  • bool $private: TRUE if the althing lives in a private area
  • bool $visible: TRUE if post already published, FALSE if still unpublished
  • int $area_id: holds the page with this althing
  • array $post: the information about the post
bbcode2html (line 232)

convert valid BBCode to valid HTML

this routine more or less replaces BBCode tags with the HTML equivalent. We assume that the BBCode is validated before. If you are unsure, you can use bbcode_validate() to double check (at a cost of processing time).

Strategy here is to

  • get rid of any superfluous CR's and CR+LF's
  • defuse any HTML-tricks via htmlspecialchars() (note that this also converts the " in [url="path"]...[/url])
  • convert the 'simple' tags via a cheap routine str_replace()
  • convert the tags with parameters (path, name) via the more expensive preg_replace
Since we probably need to use this routine over and over again in a single call, we buffer the preg search and replace arrays on the first call, speeding up subsequent calls, at a cost of a single if (is_null()). The plain search and replace arrays are so static that we simply declare them static from the start.

Note 1: We do get rid of a single newline after [quote] or [quote=...] because that would otherwise ruin the display with an extra blank line in the quote div. If you really want to have a blank line, use two newlines in a row.

Note 2: We do take into consideration the friendly URL feature and also an option for fully qualified domain names.

string bbcode2html (string $bbcode, [bool $q = FALSE])
  • string $bbcode: the BBCode-string to translate
  • bool $q: TRUE means any URLs are fully qualified, FALSE uses the short variety
bbcode_callback (line 283)

handle advanced BBCode search/replace specifically for encoding filenames

we use this callback routine to perform the regex-based search/replace so we get a chance to encode the URLs and also deal with the procy-friendly style of servind files via file.php.

Note that we are transparent about 'hidden' URLs: if the user uses the format [url=path]anchor[/url] we show the path in plain text too, like so: <a href="path">anchor</a> (anchor) No surprises with deceiving links..

string bbcode_callback (array $m, [bool $q = FALSE])
  • array $m: holds complete matched code + all individual sub-matches
  • bool $q: TRUE means any URLs are fully qualified, FALSE uses the short variety
bbcode_callback_q (line 265)

one-line wrapper to allow for fully qualified URLs

string bbcode_callback_q (array $m)
  • array $m: holds complete matched code + all individual sub-matches
bbcode_help (line 569)

show a table illustrating the possible BBCode

this routine is a help function. If JS is enabled, the information is hidden and the user can make it visible by clicking on the title.

  • return: output added to $theme
void bbcode_help (object &$theme)
  • object &$theme: collects (html) output
bbcode_validate (line 344)

validate the BBCode in the dialogdef item

* Simple tags always should match in pairs, without overlap: [b] [/b] [u] [/u] [i] [/i] [s] [/s] [code] [/code]

The more complicated constructs with opening/closing tags are: [url=path]anchor[/url] [url]path[/url] [img]path[/img] [quote]text[/quote] [quote=author]text[/quote] [quote="author"]text[/quote]

There is one single tag, ie without closing tag:

[img=path]

Path should be a path relative to the data root, e.g. '/areas/exemplum/snapshots/cyanara.jpg'. This limits the URLs and the IMGs to files on this server.

Note that we also validate the specified path via which also checks permissions of the current user. The prevents leaking of files via pupils from the teachers private intranet.

  • return: TRUE if no validation errors, FALSE otherwise + errors in $item[]
bool bbcode_validate (array &$item)
  • array &$item: an element of a dialogdef that supposedly holds BBCode
bbcode_valid_path (line 501)

validate a filename for existence and access

this routine checks to see if the current user is allowed to access the file $filename and also that it actually exists. We return FALSE if access is denied or the cleaned up path if all is well.

  • return: FALSE on access denied/non-existent, clean path otherwise
bool|string bbcode_valid_path (string $filename)
  • string $filename: the file to check, relative to CFG->datadir

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