Class AdminOutput

Description

conveniently collect output

This class allows for a convenient way to temporarily store output, in random order and still being able to output to the browser in the correct order (eg. headers() first, etc.).

This class 'knows' everything about the structure of a generated page. Most of this knowledge is contained in $this-get_html(); The actual layout is defined in the corresponding stylesheets, e.g. admin_base.css.

Typical use of this object is to add HTML-code to various parts of the page via the add_*() methods and finally sending the collected output to the user's browser with $this->send_output(). That's it.

  • todo: carefully check if we need more headers in html-head section of document, see AdminOutput().
  • todo: add a 'funnel mode': disable all distracting links that could seduce the user to leave and leave locked records (eg. nodes)

Located in /program/main_admin.php (line 618)


	
			
Variable Summary
Method Summary
 void AdminOutput ([ $skin = 'base'], [string $title = ''], [string $subtitle = ''])
 void add_breadcrumb (string $href, [string|array $params = NULL], [string|array $attributes = NULL], [string $anchor = NULL])
 void add_content (string|array $content)
 void add_html_header (string $headerline)
 void add_http_header (string $headerline)
 void add_menu (string $menuline)
 void add_message (string|array $message)
 void add_meta (array $meta)
 void add_meta_http_equiv (array $meta)
 int add_pagination (string $href, array $base_params, int $num_records, int $limit, int $current_offset, int $num_links)
 void add_pagination_item (string $href, [string|array $params = NULL], [string|array $attributes = NULL], [string $anchor = NULL])
 void add_popup_bottom (string|array $message)
 void add_popup_top (string|array $message)
 void add_stylesheet (string $url)
 string get_address ([string $m = ''])
 string get_bottomline ([string $m = ''])
 string get_breadcrumbs ([string $m = ''])
 string get_content ([string $m = ''])
 string get_div_messages (bool $bullets, [string $m = ''])
 string get_html ()
 string get_html_head ([string $m = ''])
 string get_lines ( $a, [string $m = ''])
 void get_lmth ()
 string get_logo ([string $m = ''])
 string get_menu ([string $m = ''])
 string get_navigation ([string $m = ''], [bool $textonly = FALSE])
 string get_pagination ([string $m = ''])
 string get_popups (array $messages, [string $m = ''])
 string get_quickbottom ([string $m = ''])
 string get_quicktop ([string $m = ''])
 void send_headers ()
 void send_output ()
 bool set_funnel_mode (bool $funnel_mode)
 string set_helptopic (string $topic)
 bool set_suppress_output ( $suppress_output, bool $suppress)
Variables
array $breadcrumbs = array() (line 659)
  • var: a list URL components etc. identifying the path that leads to the current screen
array $content = array() (line 638)
  • var: collection of items/lines that are part of the content area
string $dtd = <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> (line 620)
  • var: the standard doctype (default: HTML 4.01 Transitional)
bool $funnel_mode = FALSE (line 665)
  • var: if TRUE, the display should be in funnel-mode, ie. distracting links should be non-working
string $helptopic (line 656)
  • var: the additional parameter to add to the help link in the navigation
array $html_head = array() (line 632)
  • var: collection of items/lines that will be output as part of the HTML-head section
array $http_headers = array() (line 629)
  • var: collection of individual httP-headers that are to be sent _before_ any HTML is sent
array $menu = array() (line 635)
  • var: collection of items/lines that are part of the menu (could be empty)
array $messages_bottom = array() (line 647)
  • var: collection of messages that are to be displayed via a javascript alert() at END of page
array $messages_inline = array() (line 641)
  • var: collection of messages that are to be displayed just below the navigation bar
array $messages_top = array() (line 644)
  • var: collection of messages that are to be displayed via a javascript alert() at START of page
array $pagination = array() (line 662)
  • var: a list URL components etc. comprising a list of links to paginated display of lists
AdminSkin $skin (line 653)
  • var: the currently selected skin
string $subtitle (line 626)
  • var: a subtitle displayed in the generated page (for the time being it is empty or has a &nbsp;)
bool $suppress_output = FALSE (line 668)
  • var: if TRUE, no output should be sent whatsoever
bool $text_only = FALSE (line 650)
  • var: this switches the navigation between image-based and text-based
string $title (line 623)
  • var: the title to display in both the title tag and in the page itself (usually the sitename)
Methods
Constructor AdminOutput (line 682)

constructor

This sets up the object and adds the title and subtitle.

  • todo: is it really wise to add a base header? It interferes with the session cookie whenever you login at another URL than the base+'admin.php'... Comment it out for now
  • todo: do we need a link rel="shortcut icon" type of header too?
  • todo: do we really need more meta-headers?
void AdminOutput ([ $skin = 'base'], [string $title = ''], [string $subtitle = ''])
  • string $title: the title to display in both the title tag and inside the document
  • string $subtitle: the text to display underneath the title in the document (or &nbsp; if empty)
  • $skin
add_breadcrumb (line 1565)

add a breadcrumb to the breadcrumb trail

this stores information about a crumb in the breadcrumb trail into the breadcrumbs array. We store this information in pieces that are readily usable with html_a(). However, by constructing the links at the latest possible time, we are able to suppress the real links, by replacing the href + parameters with a bare "#". This trick can be used to keep the user focussed on the task at hand (in 'funnel-mode').

void add_breadcrumb (string $href, [string|array $params = NULL], [string|array $attributes = NULL], [string $anchor = NULL])
  • string $href: holds the hypertext reference
  • string|array $params: holds the parameters to add to the $href
  • string|array $attributes: holds the attributes to add to the tag
  • string $anchor: the text that identifies the breadcrumb
add_content (line 1522)

add a line or array of lines to the content part of the document

void add_content (string|array $content)
  • string|array $content: the line(s) of text to add
add_html_header (line 1436)

add a header to the HTML head part of the document

void add_html_header (string $headerline)
  • string $headerline: headerline to add
add_http_header (line 1427)

add an HTTP-header

void add_http_header (string $headerline)
  • string $headerline: headerline to add
add_menu (line 1535)

add a line to the menu part of the document

void add_menu (string $menuline)
  • string $menuline: the line of text to add
add_message (line 1474)

add a message to the list of inline messages, part of the BODY of the document

void add_message (string|array $message)
  • string|array $message: message(s) to add inline
add_meta (line 1499)

add a line with meta-information to the HTML head part of the document

void add_meta (array $meta)
  • array $meta: an array with name-value-pairs that should be added to the HTML head part
add_meta_http_equiv (line 1511)

add a line with http-equiv meta-information to the HTML head part of the document

void add_meta_http_equiv (array $meta)
  • array $meta: an array with name-value-pairs that should be added to the HTML head part
add_pagination (line 1623)

add a pagination navigation bar to the output

this adds a pagination navbar to the output making it easier to step through a long listing of items a screen at a time

Features:

  • the 'Prev' and 'Next' buttons do wrap: whenever we hit the begin/end of the list, we start again at the end/begin.
  • if there are more screens to show than $num_links, we show at most $num_links links whenever we are NOT at the start of the list, the smallest link is displayed differently (via translation), e.g. via a left bracket '&lt;' or three dots '...'
  • the same trick is used at the end of the list to indicate there's more (via a different translation), e.g. via a right bracket '&gt;' or three dots '...'
This function returns the number of screens that is required to show all the items in screesn of at most $limit items. The number of screens is at least 1.

  • return: number of screens (n >= 1) and output added to $this->pagination[]
int add_pagination (string $href, array $base_params, int $num_records, int $limit, int $current_offset, int $num_links)
  • string $href: the script to call
  • array $base_params: the necessary parameters to land on the correct page
  • int $num_records: the total length of the list
  • int $limit: the preferred size of the screen to show
  • int $current_offset: the record that starts the current screen
  • int $num_links: the maximum number of pages to show in the navbar (excluding Prev/Next/All)
add_pagination_item (line 1589)

add a link to screen of a paginated list to the existing list

this stores information about a screen in the paginated display of a list. We store this information in pieces that are readily usable with html_a(). However, by constructing the links at the latest possible time, we are able to suppress the real links, by replacing the href + parameters with a bare "#". This trick can be used to keep the user focussed on the task at hand (in 'funnel-mode').

void add_pagination_item (string $href, [string|array $params = NULL], [string|array $attributes = NULL], [string $anchor = NULL])
  • string $href: holds the hypertext reference
  • string|array $params: holds the parameters to add to the $href
  • string|array $attributes: holds the attributes to add to the tag
  • string $anchor: the text that identifies the link
add_popup_bottom (line 1460)

add a message to the list of popup-messages at the BOTTOM of the document

void add_popup_bottom (string|array $message)
  • string|array $message: message(s) to add
add_popup_top (line 1446)

add a message to the list of popup-messages at the TOP of the document

void add_popup_top (string|array $message)
  • string|array $message: message(s) to add
add_stylesheet (line 1488)

add a link to a stylesheet to the HTML head part of the document

void add_stylesheet (string $url)
  • string $url: url of the stylesheet
get_address (line 1356)

return the reconstructed URL in a single (indented) line

actual code moved to waslib; keep this wrapper for compatibility

  • return: reconstructed URL as text
string get_address ([string $m = ''])
  • string $m: left margin for increased readability
get_bottomline (line 1335)

report basic performance indicators in a single line

This calculates the execution time of the script and the number of queries. Note a special trick: we retrieve the translated string in a dummy variable before calculating the number of queries because otherwise we might miss one or more query from the language/translation subsystem.

Note that the message containing the performance indicators is only generated when debug is TRUE; the information is not that interesting for ordinary users.

  • return: performance report
string get_bottomline ([string $m = ''])
  • string $m: left margin for increased readability
get_breadcrumbs (line 1371)

retrieve/construct a list of 0 or more clickable breadcrumbs

this reads the breadcrumbs-array and constructs the breadcrumb trail If $this->funnel_mode is TRUE, the links are still clickable but the href-part is replaced with a "#" instead of the 'real' href + parameters.

  • return: constructed HTML implementing the breadcrumb trail
string get_breadcrumbs ([string $m = ''])
  • string $m: left margin for increased readability
get_content (line 926)

get all lines in the content DIV in a single properly indented string

  • return: generated HTML-code
string get_content ([string $m = ''])
  • string $m: left margin for increased readability
get_div_messages (line 983)

get a perhaps bulleted list of messages in a DIV

This constructs an unordered list with messages, if there are any If there is no message at all, an empty string is returned (without DIV). Previously, if there was a single message, no bullet was added to the message. If there were two or more messages, bullets were added. We now (april 2012) have a boolean parameter $bullets which modifies this behaviour as follows. If $bullets is TRUE, bullets are added to every message, even when there is only one. This makes this list more predictable for vision impaired users. Note that we also added an H2 with the phrase 'Messages' to make it even easier to identify this div. This phrase can be visually suppressed via a style sheet.

Note that this routine is an exception with respect to the DIV-tags: this helper routine DOES generate its own DIVs whenever there is at least 1 message. This means that there is no DIV at all when there are no messages.

  • return: constructed HTML with message(s) or empty string if no messages
string get_div_messages (bool $bullets, [string $m = ''])
  • bool $bullets: if TRUE then _all_ messages get a bullet
  • string $m: left margin for increased readability
get_html (line 783)

construct an output page in HTML

This constructs a full HTML-page, starting at the DTD and ending with the html closing tag.

The page is constructed using nested DIVs, the layout is taken care of in a separate style sheet. All knowledge about the structure of the page is contained in this routine.

The performance of the script (# of queries, execution time) is calculated as late as possible, to catch as much as we can. Therefore the construction is done in two parts and performance is calculated last.

The contents of the various DIVs is constructed in various helper routines in order to make this routine easy to read (by humans that is). The various helper routines all are called with a string of space characters; this should improve the the readability of the page that is generated eventually.

Note that the routine $this->get_div_messages() does in fact generate its own DIV tags. This is done in order to completely get rid of the message DIV, we do not even want to see an empty DIV if there are no message.

  • return: complete HTML-page, ready for output
string get_html ()
get_html_head (line 916)

get all lines in the HTML head section in a single properly indented string

  • return: generated HTML-code
string get_html_head ([string $m = ''])
  • string $m: left margin for increased readability
get_lines (line 949)

get lines from an array in a single properly indented string

This is a workhorse to convert an array of lines to a properly indented block of text.

  • return: properly indented block of text
string get_lines ( $a, [string $m = ''])
  • string $m: left margin for increased readability
  • $a
get_lmth (line 845)

proof of concept for braille-skin

void get_lmth ()
get_logo (line 1052)

construct an image tag with the W

  • return: constructed image tag
string get_logo ([string $m = ''])
  • string $m: left margin for increased readability
get_menu (line 936)

get all lines in the menu DIV in a single properly indented string

  • return: generated HTML-code
string get_menu ([string $m = ''])
  • string $m: left margin for increased readability
get_navigation (line 1188)

construct a navigation bar for various jobs the user is allowed to do

This constructs an unordered list (UL) with items, where each item is a clickable link to one of the various 'managers' (e.g. page manger, file manager, etc.).

There are several different 'modes' for this function. The type of output not only depends on the $textonly flag, but also on the user's permissions for the various 'managers'. This information is retrieved from the global $USER object.

The list of available options is stored in an array of arrays. This should make it easier to add a new 'manager' in the future: simply add another element to the $items array below (and of course the necessary changes in the dispatcher in main_admin() above).

A a rule the links are presented to the user in the form of clickable images (icons) as provided by the currently selected skin. If the optional flag $textonly is set, all links are displayed as a text-link (using the alt text from the image).

Depending on the user's privileges, access to some 'managers' is denied. This is visualised by displaying either a black/white image (instead of the coloured one) or by adding the class 'dimmed' to the text-based anchor tags. This makes it possible to show 'dimmed' or 'greyed out' text if the user has no access. Note, however, that these 'forbidden' links are not suppressed: the W@S philosophy says that everything should be transparent as possible and that rules out the option to suppress the things the user is not supposed to do. If the user does follow the 'dimmed' links, an error message is displayed (see the code in the dispatcher in main_admin() above). One last note on this issue of denying access in a transparent way: the mousover already indicate that access will be denied. That should provide an extra clue to the user.

The list of items contains a link to the start centre (the first link) and also a link to the documentation (the last link). Both items are goverend by the same privilege mask: JOB_PERMISSION_STARTCENTER. Basically it means that everyone with minimal administrator privileges has access to both the start centre and the help function. Effectively this is everyone that has access to admin.php so the images startcenter-bw.gif and help-bw.gif do not really make sense, but for completeness sake...

Note that we rely on the fact the the names of the black/white navigation images are systematically derived from the base name by appending '-bw' to the image name.

  • return: constructed navigation bar
string get_navigation ([string $m = ''], [bool $textonly = FALSE])
  • string $m: left margin for increased readability
  • bool $textonly: if TRUE, no images are used to construct navigation links
get_pagination (line 1404)

retrieve/construct a list of 0 or more clickable links to paginated screens

this reads the pagination-array and constructs a list of links to individual screens of a paginated display of a list.

Even when $this->funnel_mode is TRUE, the links are still operational.

  • return: constructed HTML implementing the links to the screens
string get_pagination ([string $m = ''])
  • string $m: left margin for increased readability
get_popups (line 1019)

construct javascript alerts for messages

This constructs a piece of HTML that yields 0 or more calles to the javascript alert() function, once per message. If no messages need to be displayed an empty string is returned.

  • return: generated HTML-code with Javascript or empty string
string get_popups (array $messages, [string $m = ''])
  • string $m: left margin for increased readability
  • array $messages: @messages a collection of message to display via alert()
get_quickbottom (line 1127)

construct a list of quicklinks for botton of page

This creates HTML-code for a few links that can be displayed at the bottom of the page. Currently this list is has 1 link. Possible links are

  • a logout link (which will end the user's session)
  • a link to the main site (i.e. /index.php without any addition parameters)
  • a link to the version checker on the project's home page
(see also get_quicktop()).

  • return: constructed list of clickable links
string get_quickbottom ([string $m = ''])
  • string $m: left margin for increased readability
get_quicktop (line 1083)

construct a list of quicklinks for top of page, including logout link

This creates HTML-code for a few links that can be displayed at the top of the page. These links are:

  • a logout link (which will end the user's session)
  • a link to the main site (i.e. /index.php without any addition parameters)
  • a link to the version checker on the project's home page
Note that the latter opens in a smallish new window that can be easily dismissed without 'losing' the main page.

  • return: constructed list of clickable links
string get_quicktop ([string $m = ''])
  • string $m: left margin for increased readability
send_headers (line 719)

send collected HTTP-headers to user's browser

This sends the headers that still need to be sent. These are collected in the array $this->http_headers. If headers are already sent, this fact is logged (and the collected headers are not sent).

void send_headers ()
send_output (line 748)

send collected output to user's browser

This first sends any pending HTTP-headers and subsequently outputs the page that is constructed by $this->get_html() However, if the flag suppress_output is set then nothing is sent, not even a header. This allows for routines that interact directly with the user, e.g. a function to download a file.

void send_output ()
set_funnel_mode (line 1698)

manipulate the funnel mode

  • return: the old value of the $funnel_mode
bool set_funnel_mode (bool $funnel_mode)
  • bool $funnel_mode: if TRUE, funnel mode is switched on and distracting navigation links rendered inactive
set_helptopic (line 1544)

set the additional help topic to show when user clicks help button

  • return: the old help topic
string set_helptopic (string $topic)
  • string $topic: the topic in the help function
set_suppress_output (line 1710)

manipulate output suppression

  • return: the old value of the $suppress_output
bool set_suppress_output ( $suppress_output, bool $suppress)
  • bool $suppress: if TRUE, the actual output is suppressed (effectively disables send_output())
  • $suppress_output

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