Overview

Packages

  • awl
    • AuthPlugin
    • AwlDatabase
    • Browser
    • classEditor
    • DataEntry
    • DataUpdate
    • EMail
    • iCalendar
    • MenuSet
    • PgQuery
    • Session
    • Translation
    • User
    • Utilities
    • Validation
    • vCalendar
    • vComponent
    • XMLDocument
    • XMLElement
  • None
  • PHP

Classes

  • Browser
  • BrowserColumn
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated
  • Todo

Class Browser

Start a new Browser, add columns, set a join and Render it to create a basic list of records in a table. You can, of course, get a lot fancier with setting ordering, where clauses totalled columns and so forth.

Package: awl\Browser
Copyright: Catalyst IT Ltd, Morphoss Ltd <http://www.morphoss.com/>
License: GNU GPL v2 or later
Author: Andrew McMillan <andrew@mcmillan.net.nz>
Located at classBrowser.php
Methods summary
public
# Browser( string $title = "" )

The Browser class constructor

The Browser class constructor

Parameters

$title
string
$title A title for the browser (optional).
public
# AddColumn( string $field, string $header = "", string $align = "", string $format = "", string $sql = "", string $class = "", string $datatype = "", mixed $hook = null )

Add a column to the Browser.

Add a column to the Browser.

This constructs a new BrowserColumn, appending it to the array of columns in this Browser.

Note that if the $format parameter starts with '<td>' the format will replace the column format, otherwise it will be used within '<td>...</td>' tags.

Parameters

$field
string
$field The name of the field.
$header
string
$header A column header for the field.
$align
string
$align An alignment for column values.
$format
string
$format A sprintf format for displaying column values.
$sql
string
$sql An SQL fragment for calculating the value.
$class
string
$class A CSS class to apply to the cells of this column.
$datatype
string
$hook The name of a global function which will preprocess the column value The hook function should be defined as follows: function hookfunction( $column_value, $column_name, $database_row ) { ... return $value; }
$hook

See

BrowserColumn
public
# AddHidden( string $field, string $sql = "" )

Add a hidden column - one that is present in the SQL result, but for which there is no column displayed.

Add a hidden column - one that is present in the SQL result, but for which there is no column displayed.

This can be useful for including a value in (e.g.) clickable links or title attributes which is not actually displayed as a visible column.

Parameters

$field
string
$field The name of the field.
$sql
string
$sql An SQL fragment to calculate the field, if it is calculated.
public
# SetTitle( string $new_title )

Set the Title for the browse.

Set the Title for the browse.

This can also be set in the constructor but if you create a template Browser and then clone it in a loop you may want to assign a different Title for each instance.

Parameters

$new_title
string
$new_title The new title for the browser
public string
# Title( string $new_title = null )

Accessor for the Title for the browse, which could set the title also.

Accessor for the Title for the browse, which could set the title also.

Parameters

$new_title
string
$new_title The new title for the browser

Returns

string
The current title for the browser
public
# SetTranslatable( array $column_list )

Set the named columns to be translatable

Set the named columns to be translatable

Parameters

$column_list
array
$column_list The list of columns which are translatable
public
# SetSubTitle( string $sub_title )

Set a Sub Title for the browse.

Set a Sub Title for the browse.

Parameters

$sub_title
string
$sub_title The sub title string
public
# SetDiv( string $open_div, string $close_div )

Set a div for wrapping the browse.

Set a div for wrapping the browse.

Parameters

$open_div
string
$open_div The HTML to open the div
$close_div
string
$close_div The HTML to open the div
public
# SetJoins( string $join_list )

Set the tables and joins for the SQL.

Set the tables and joins for the SQL.

For a single table this should just contain the name of that table, but for multiple tables it should be the full content of the SQL 'FROM ...' clause (excluding the actual 'FROM' keyword).

Parameters

$join_list
string
$join_list
public
# SetUnion( string $union_select )

Set a Union SQL statement.

Set a Union SQL statement.

In rare cases this might be useful. It's currently a fairly simple hack which requires you to put an entire valid (& matching) UNION subclause (although without the UNION keyword).

Parameters

$union_select
string
$union_select
public
# SetWhere( string $where_clause )

Set the SQL Where clause to a specific value.

Set the SQL Where clause to a specific value.

The WHERE keyword should not be included.

Parameters

$where_clause
string
$where_clause A valide SQL WHERE ... clause.
public
# SetDistinct( string $distinct )

Set the SQL DISTINCT clause to a specific value.

Set the SQL DISTINCT clause to a specific value.

The whole clause (except the keyword) needs to be supplied

Parameters

$distinct
string
$distinct The whole clause, after 'DISTINCT'
public
# SetLimit( integer $limit_n )

Set the SQL LIMIT clause to a specific value.

Set the SQL LIMIT clause to a specific value.

Only the limit number should be supplied.

Parameters

$limit_n
integer
$limitn A number of rows to limit the SQL selection to
public
# SetOffset( integer $offset_n )

Set the SQL OFFSET clause to a specific value.

Set the SQL OFFSET clause to a specific value.

Only the offset number

Parameters

$offset_n
integer
$offsetn A number of rows to offset the SQL selection to, based from the start of the results.
public
# MoreWhere( string $operator, string $more_where )

Add an [operator] ... to the SQL Where clause

Add an [operator] ... to the SQL Where clause

You will generally want to call OrWhere or AndWhere rather than this function, but hey: who am I to tell you how to code!

Parameters

$operator
string
$operator The operator to combine with previous where clause parts.
$more_where
string
$more_where The extra part of the where clause
public
# AndWhere( string $more_where )

Add an OR ... to the SQL Where clause

Add an OR ... to the SQL Where clause

Parameters

$more_where
string
$more_where The extra part of the where clause
public
# OrWhere( string $more_where )

Add an OR ... to the SQL Where clause

Add an OR ... to the SQL Where clause

Parameters

$more_where
string
$more_where The extra part of the where clause
public
# AddGrouping( mixed $field, mixed $browser_array_key = 0 )
public
# AddOrder( string $field, string $direction, string $browser_array_key = 0, string $secondary = 0 )

Add an ordering to the browser widget.

Add an ordering to the browser widget.

The ordering can be overridden by GET parameters which will be rendered into the column headers so that a user can click on the column headers to control the actual order.

Parameters

$field
string
$field The name of the field to be ordered by.
$direction
string
$direction A for Ascending, otherwise it will be descending order.
$browser_array_key
string
$browser_array_key Use this to distinguish between multiple browser widgets on the same page. Leave it empty if you only have a single browser instance.
$secondary
string
$secondary Use this to indicate a default secondary order which shouldn't interfere with the default primary order.
public
# ForceOrder( string $field, string $direction )

Force a particular ordering onto the browser widget.

Force a particular ordering onto the browser widget.

Parameters

$field
string
$field The name of the field to be ordered by.
$direction
string
$direction A for Ascending, otherwise it will be descending order.
public
# SetOrdering( mixed $default_fld = null, mixed $default_dir = 'A' , mixed $browser_array_key = 0 )

Set up the ordering for the browser. Generally you should call this with the first parameter set as a field to order by default. Call with the second parameter set to 'D' or 'DESCEND' if you want to reverse the default order.

Set up the ordering for the browser. Generally you should call this with the first parameter set as a field to order by default. Call with the second parameter set to 'D' or 'DESCEND' if you want to reverse the default order.

public
# AddTotal( string $column_name, string $total_function = false )

Mark a column as something to be totalled. You can also specify the name of a function which may modify the value before the actual totalling.

Mark a column as something to be totalled. You can also specify the name of a function which may modify the value before the actual totalling.

The callback function will be called with each row, with the first argument being the entire record object and the second argument being only the column being totalled. The callback should return a number, to be added to the total.

Parameters

$column_name
string
$column_name The name of the column to be totalled.
$total_function
string
$total_function The name of the callback function.
public
# GetTotal( string $column_name )

Retrieve the total from a totalled column

Retrieve the total from a totalled column

Parameters

$column_name
string
$column_name The name of the column to be totalled.
public
# RowFormat( string $beginrow, string $closerow, string $rowargs )

Set the format for an output row.

Set the format for an output row.

The row format is set as an sprintf format string for the start of the row, and a plain text string for the close of the row. Subsequent arguments are interpreted as names of fields, the values of which will be sprintf'd into the beginrow string for each row.

Some special field names exist beginning with the '#' character which have 'magic' functionality, including '#even' which will insert '0' for even rows and '1' for odd rows, allowing a nice colour alternation if the beginrow format refers to it like: 'class="r%d"' so that even rows will become 'class="r0"' and odd rows will be 'class="r1"'.

At present only '#even' exists, although other magic values may be defined in future.

Parameters

$beginrow
string
$beginrow The new printf format for the start of the row.
$closerow
string
$closerow The new string for the close of the row.
$rowargs
string
$rowargs ... The row arguments which will be sprintf'd into the $beginrow format for each row
public
# ExtraRowFormat( string $beginrow, string $closerow, string $rowargs )

Set the format for an extra output row.

Set the format for an extra output row.

Like Browser::RowFormat(), but used for formatting additional / extra rows created with Browser::AddRow(). Defaults to the format set with Browser::RowFormat() if unset.

Parameters

$beginrow
string
$beginrow The new printf format for the start of the extra row.
$closerow
string
$closerow The new string for the close of the extra row.
$rowargs
string
$rowargs ... The row arguments which will be sprintf'd into the $beginrow format for each extra row
public boolean
# DoQuery( )

This method is used to build and execute the database query.

This method is used to build and execute the database query.

You need not call this method, since Browser::Render() will call it for you if you have not done so at that point.

Returns

boolean
The success / fail status of the AwlQuery::Exec()
public
# AddRow( mixed $column_values )

Add an extra arbitrary row onto the end of the browser.

Add an extra arbitrary row onto the end of the browser.

Var

array $column_values Contains an array of named fields, hopefully matching the column names.
public
# MatchedRow( string $column, string $value, string $function )

Replace a row where $column = $value with an extra arbitrary row, returned from calling $function

Replace a row where $column = $value with an extra arbitrary row, returned from calling $function

Parameters

$column
string
$column The name of a column to match
$value
string
$value The value to match in the column
$function
string
$function The name of the function to call for the matched row
public
# ValueReplacement( array $matches )

Return values from the current row for replacing into a template.

Return values from the current row for replacing into a template.

This is used to return values from the current row, so they can be inserted into a row template. It is used as a callback function for preg_replace_callback.

Parameters

$matches
array
of string $matches An array containing a field name as offset 1
public string
# Render( string $title_tag = null, mixed $subtitle_tag = null )

This method is used to render the browser as HTML. If the query has not yet been executed then this will call DoQuery to do so.

This method is used to render the browser as HTML. If the query has not yet been executed then this will call DoQuery to do so.

The browser (including the title) will be displayed in a div with id="browser" so that you can style '#browser tr.header', '#browser tr.totals' and so forth.

Parameters

$title_tag
string
$title_tag The tag to use around the browser title (default 'h1')
$subtitle_tag

Returns

string
The rendered HTML fragment to display to the user.
Properties summary
public mixed $Title
#
public mixed $SubTitle
#
public mixed $FieldNames
#
public mixed $Columns
#
public mixed $HiddenColumns
#
public mixed $Joins
#
public mixed $Where
#
public mixed $Distinct
#
public mixed $Union
#
public mixed $Order
#
public mixed $OrderField
#
public mixed $OrderDirection
#
public mixed $OrderBrowserKey
#
public mixed $ForcedOrder
#
public mixed $Grouping
#
public mixed $Limit
#
public mixed $Offset
#
public mixed $Query
#
public mixed $BeginRow
#
public mixed $CloseRow
#
public mixed $BeginRowArgs
#
public mixed $BeginExtraRow
#
public mixed $CloseExtraRow
#
public mixed $BeginExtraRowArgs
#
public mixed $Totals
#
public mixed $TotalFuncs
#
public mixed $ExtraRows
#
public mixed $match_column
#
public mixed $match_value
#
public mixed $match_function
#
public mixed $DivOpen
#
public mixed $DivClose
#
AWL API documentation generated by ApiGen 2.8.0