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 549)


	
			
Variable Summary
Method Summary
 void AdminOutput ([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 ([string $m = ''])
 string get_html ()
 string get_html_head ([string $m = ''])
 string get_lines ( $a, [string $m = ''])
 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 587)
  • var: a list URL components etc. identifying the path that leads to the current screen
array $content = array() (line 569)
  • 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 551)
  • var: the standard doctype (default: HTML 4.01 Transitional)
bool $funnel_mode = FALSE (line 593)
  • var: if TRUE, the display should be in funnel-mode, ie. distracting links should be non-working
string $helptopic (line 584)
  • var: the additional parameter to add to the help link in the navigation
bool $high_visibility = FALSE (line 581)
  • var: this switches the navigation between image-based and text-based
array $html_head = array() (line 563)
  • var: collection of items/lines that will be output as part of the HTML-head section
array $http_headers = array() (line 560)
  • var: collection of individual httP-headers that are to be sent _before_ any HTML is sent
array $menu = array() (line 566)
  • var: collection of items/lines that are part of the menu (could be empty)
array $messages_bottom = array() (line 578)
  • var: collection of messages that are to be displayed via a javascript alert() at END of page
array $messages_inline = array() (line 572)
  • var: collection of messages that are to be displayed just below the navigation bar
array $messages_top = array() (line 575)
  • var: collection of messages that are to be displayed via a javascript alert() at START of page
array $pagination = array() (line 590)
  • var: a list URL components etc. comprising a list of links to paginated display of lists
string $subtitle (line 557)
  • var: a subtitle displayed in the generated page (for the time being it is empty or has a &nbsp;)
bool $suppress_output = FALSE (line 596)
  • var: if TRUE, no output should be sent whatsoever
string $title (line 554)
  • var: the title to display in both the title tag and in the page itself (usually the sitename)
Methods
Constructor AdminOutput (line 610)

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 ([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)
add_breadcrumb (line 1452)

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 1409)

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 1323)

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 1314)

add an HTTP-header

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

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 1361)

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 1386)

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 1398)

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 1510)

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 1476)

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 1347)

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 1333)

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 1375)

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 1227)

return the reconstructed URL in a single (indented) line

This constructs the exact URL (including the GET-parameters) of the current script. This URL is returned as HTML so it can be displyed. It is NOT meant to be a clickable link, but as a documentation of the actual URL that was used. Note that this URL can be suppressed by an appropriate 'display:none' in the stylesheet, making it an item that only appears on a hardcopy (media="print") and not on screen.

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

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 1250)

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 778)

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 827)

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). If there is a single message, no bullet is added to the message. If there are two or more messages, bullets are added.

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 ([string $m = ''])
  • string $m: left margin for increased readability
get_html (line 705)

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 768)

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 801)

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_logo (line 895)

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 788)

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 1027)

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 dipatcher in main_admin() above).

A a rule the links are presented to the user in the form of clickable images (icons) of 32x32 pixels. If no image is specified, a text-link is used instead. If the optional flag $textonly is set, _all_ links are displayed as a text-link.

Depending on the user's privileges, access to some 'managers' is denied. This is visualised by displaying either a black/white 32x32 image (instead of the coloured icon) 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...

  • return: constructed navigation bar
  • todo: we need to clean up this code and properly implement the funnel mode (2009-12-18)
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 1285)

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.

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 links to the screens
string get_pagination ([string $m = ''])
  • string $m: left margin for increased readability
get_popups (line 862)

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 970)

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 926)

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 641)

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 670)

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 1585)

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 1431)

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 1597)

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 Wed, 11 May 2011 23:45:24 +0200 by phpDocumentor 1.4.0