Andrew's Web Libraries (AWL)
Browser Class Reference

Public Member Functions

 __construct ( $title="")
 
 AddColumn ( $field, $header="", $align="", $format="", $sql="", $class="", $datatype="", $hook=null)
 
 AddHidden ( $field, $sql="")
 
 SetTitle ( $new_title)
 
 Title ( $new_title=null)
 
 SetTranslatable ( $column_list)
 
 SetSubTitle ( $sub_title)
 
 SetDiv ( $open_div, $close_div)
 
 SetJoins ( $join_list)
 
 SetUnion ( $union_select)
 
 SetWhere ( $where_clause)
 
 SetDistinct ( $distinct)
 
 SetLimit ( $limit_n)
 
 SetOffset ( $offset_n)
 
 MoreWhere ( $operator, $more_where)
 
 AndWhere ( $more_where)
 
 OrWhere ( $more_where)
 
 AddGrouping ( $field, $browser_array_key=0)
 
 AddOrder ( $field, $direction, $browser_array_key=0, $secondary=0)
 
 ForceOrder ( $field, $direction)
 
 SetOrdering ( $default_fld=null, $default_dir='A', $browser_array_key=0)
 
 AddTotal ( $column_name, $total_function=false)
 
 GetTotal ( $column_name)
 
 RowFormat ( $beginrow, $closerow, $rowargs)
 
 ExtraRowFormat ( $beginrow, $closerow, $rowargs)
 
 DoQuery ()
 
 AddRow ( $column_values)
 
 MatchedRow ( $column, $value, $function)
 
 ValueReplacement ($matches)
 
 Render ( $title_tag=null, $subtitle_tag=null)
 

Public Attributes

 $Title
 
 $SubTitle
 
 $FieldNames
 
 $Columns
 
 $HiddenColumns
 
 $Joins
 
 $Where
 
 $Distinct
 
 $Union
 
 $Order
 
 $OrderField
 
 $OrderDirection
 
 $OrderBrowserKey
 
 $ForcedOrder
 
 $Grouping
 
 $Limit
 
 $Offset
 
 $Query
 
 $BeginRow
 
 $CloseRow
 
 $BeginRowArgs
 
 $BeginExtraRow
 
 $CloseExtraRow
 
 $BeginExtraRowArgs
 
 $Totals
 
 $TotalFuncs
 
 $ExtraRows
 
 $match_column
 
 $match_value
 
 $match_function
 
 $DivOpen
 
 $DivClose
 

Detailed Description

Definition at line 178 of file classBrowser.php.

Constructor & Destructor Documentation

◆ __construct()

Browser::__construct (   $title = "")

The Browser class constructor

Parameters
string$titleA title for the browser (optional).

Definition at line 218 of file classBrowser.php.

Member Function Documentation

◆ AddColumn()

Browser::AddColumn (   $field,
  $header = "",
  $align = "",
  $format = "",
  $sql = "",
  $class = "",
  $datatype = "",
  $hook = null 
)

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 '

' the format will replace the column format, otherwise it will be used within '

...' tags.

See also
BrowserColumn
Parameters
string$fieldThe name of the field.
string$headerA column header for the field.
string$alignAn alignment for column values.
string$formatA sprintf format for displaying column values.
string$sqlAn SQL fragment for calculating the value.
string$classA CSS class to apply to the cells of this column.
string$hookThe 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; }

Definition at line 264 of file classBrowser.php.

◆ AddGrouping()

Browser::AddGrouping (   $field,
  $browser_array_key = 0 
)

Definition at line 453 of file classBrowser.php.

◆ AddHidden()

Browser::AddHidden (   $field,
  $sql = "" 
)

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
string$fieldThe name of the field.
string$sqlAn SQL fragment to calculate the field, if it is calculated.

Definition at line 279 of file classBrowser.php.

◆ AddOrder()

Browser::AddOrder (   $field,
  $direction,
  $browser_array_key = 0,
  $secondary = 0 
)

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
string$fieldThe name of the field to be ordered by.
string$directionA for Ascending, otherwise it will be descending order.
string$browser_array_keyUse this to distinguish between multiple browser widgets on the same page. Leave it empty if you only have a single browser instance.
string$secondaryUse this to indicate a default secondary order which shouldn't interfere with the default primary order.

Definition at line 478 of file classBrowser.php.

◆ AddRow()

Browser::AddRow (   $column_values)

Definition at line 676 of file classBrowser.php.

◆ AddTotal()

Browser::AddTotal (   $column_name,
  $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.

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
string$column_nameThe name of the column to be totalled.
string$total_functionThe name of the callback function.

Definition at line 561 of file classBrowser.php.

◆ AndWhere()

Browser::AndWhere (   $more_where)

Add an OR ... to the SQL Where clause

Parameters
string$more_whereThe extra part of the where clause

Definition at line 440 of file classBrowser.php.

◆ DoQuery()

Browser::DoQuery ( )

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

Definition at line 647 of file classBrowser.php.

◆ ExtraRowFormat()

Browser::ExtraRowFormat (   $beginrow,
  $closerow,
  $rowargs 
)

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
string$beginrowThe new printf format for the start of the extra row.
string$closerowThe new string for the close of the extra row.
string$rowargs... The row arguments which will be sprintf'd into the $beginrow format for each extra row

Definition at line 626 of file classBrowser.php.

◆ ForceOrder()

Browser::ForceOrder (   $field,
  $direction 
)

Force a particular ordering onto the browser widget.

Parameters
string$fieldThe name of the field to be ordered by.
string$directionA for Ascending, otherwise it will be descending order.

Definition at line 512 of file classBrowser.php.

◆ GetTotal()

Browser::GetTotal (   $column_name)

Retrieve the total from a totalled column

Parameters
string$column_nameThe name of the column to be totalled.

Definition at line 574 of file classBrowser.php.

◆ MatchedRow()

Browser::MatchedRow (   $column,
  $value,
  $function 
)

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

Parameters
string$columnThe name of a column to match
string$valueThe value to match in the column
string$functionThe name of the function to call for the matched row

Definition at line 689 of file classBrowser.php.

◆ MoreWhere()

Browser::MoreWhere (   $operator,
  $more_where 
)

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
string$operatorThe operator to combine with previous where clause parts.
string$more_whereThe extra part of the where clause

Definition at line 427 of file classBrowser.php.

◆ OrWhere()

Browser::OrWhere (   $more_where)

Add an OR ... to the SQL Where clause

Parameters
string$more_whereThe extra part of the where clause

Definition at line 449 of file classBrowser.php.

◆ Render()

Browser::Render (   $title_tag = null,
  $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.

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
string$title_tagThe tag to use around the browser title (default 'h1')
Returns
string The rendered HTML fragment to display to the user.

@TODO: We should deprecate this approach in favour of simply doing the ValueReplacement on field names

Definition at line 734 of file classBrowser.php.

◆ RowFormat()

Browser::RowFormat (   $beginrow,
  $closerow,
  $rowargs 
)

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
string$beginrowThe new printf format for the start of the row.
string$closerowThe new string for the close of the row.
string$rowargs... The row arguments which will be sprintf'd into the $beginrow format for each row

Definition at line 601 of file classBrowser.php.

◆ SetDistinct()

Browser::SetDistinct (   $distinct)

Set the SQL DISTINCT clause to a specific value.

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

Parameters
string$distinctThe whole clause, after 'DISTINCT'

Definition at line 392 of file classBrowser.php.

◆ SetDiv()

Browser::SetDiv (   $open_div,
  $close_div 
)

Set a div for wrapping the browse.

Parameters
string$open_divThe HTML to open the div
string$close_divThe HTML to open the div

Definition at line 343 of file classBrowser.php.

◆ SetJoins()

Browser::SetJoins (   $join_list)

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
string$join_list

Definition at line 357 of file classBrowser.php.

◆ SetLimit()

Browser::SetLimit (   $limit_n)

Set the SQL LIMIT clause to a specific value.

Only the limit number should be supplied.

Parameters
int$limit_nA number of rows to limit the SQL selection to

Definition at line 403 of file classBrowser.php.

◆ SetOffset()

Browser::SetOffset (   $offset_n)

Set the SQL OFFSET clause to a specific value.

Only the offset number

Parameters
int$offset_nA number of rows to offset the SQL selection to, based from the start of the results.

Definition at line 414 of file classBrowser.php.

◆ SetOrdering()

Browser::SetOrdering (   $default_fld = null,
  $default_dir = 'A',
  $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.

Definition at line 539 of file classBrowser.php.

◆ SetSubTitle()

Browser::SetSubTitle (   $sub_title)

Set a Sub Title for the browse.

Parameters
string$sub_titleThe sub title string

Definition at line 333 of file classBrowser.php.

◆ SetTitle()

Browser::SetTitle (   $new_title)

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
string$new_titleThe new title for the browser

Definition at line 293 of file classBrowser.php.

◆ SetTranslatable()

Browser::SetTranslatable (   $column_list)

Set the named columns to be translatable

Parameters
array$column_listThe list of columns which are translatable

Definition at line 315 of file classBrowser.php.

◆ SetUnion()

Browser::SetUnion (   $union_select)

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
string$union_select

Definition at line 370 of file classBrowser.php.

◆ SetWhere()

Browser::SetWhere (   $where_clause)

Set the SQL Where clause to a specific value.

The WHERE keyword should not be included.

Parameters
string$where_clauseA valide SQL WHERE ... clause.

Definition at line 381 of file classBrowser.php.

◆ Title()

Browser::Title (   $new_title = null)

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

Parameters
string$new_titleThe new title for the browser
Returns
string The current title for the browser

Definition at line 304 of file classBrowser.php.

◆ ValueReplacement()

Browser::ValueReplacement (   $matches)

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
arrayof string $matches An array containing a field name as offset 1

Definition at line 705 of file classBrowser.php.

Member Data Documentation

◆ $BeginExtraRow

Browser::$BeginExtraRow

Definition at line 201 of file classBrowser.php.

◆ $BeginExtraRowArgs

Browser::$BeginExtraRowArgs

Definition at line 203 of file classBrowser.php.

◆ $BeginRow

Browser::$BeginRow

Definition at line 198 of file classBrowser.php.

◆ $BeginRowArgs

Browser::$BeginRowArgs

Definition at line 200 of file classBrowser.php.

◆ $CloseExtraRow

Browser::$CloseExtraRow

Definition at line 202 of file classBrowser.php.

◆ $CloseRow

Browser::$CloseRow

Definition at line 199 of file classBrowser.php.

◆ $Columns

Browser::$Columns

Definition at line 183 of file classBrowser.php.

◆ $Distinct

Browser::$Distinct

Definition at line 187 of file classBrowser.php.

◆ $DivClose

Browser::$DivClose

Definition at line 211 of file classBrowser.php.

◆ $DivOpen

Browser::$DivOpen

Definition at line 210 of file classBrowser.php.

◆ $ExtraRows

Browser::$ExtraRows

Definition at line 206 of file classBrowser.php.

◆ $FieldNames

Browser::$FieldNames

Definition at line 182 of file classBrowser.php.

◆ $ForcedOrder

Browser::$ForcedOrder

Definition at line 193 of file classBrowser.php.

◆ $Grouping

Browser::$Grouping

Definition at line 194 of file classBrowser.php.

◆ $HiddenColumns

Browser::$HiddenColumns

Definition at line 184 of file classBrowser.php.

◆ $Joins

Browser::$Joins

Definition at line 185 of file classBrowser.php.

◆ $Limit

Browser::$Limit

Definition at line 195 of file classBrowser.php.

◆ $match_column

Browser::$match_column

Definition at line 207 of file classBrowser.php.

◆ $match_function

Browser::$match_function

Definition at line 209 of file classBrowser.php.

◆ $match_value

Browser::$match_value

Definition at line 208 of file classBrowser.php.

◆ $Offset

Browser::$Offset

Definition at line 196 of file classBrowser.php.

◆ $Order

Browser::$Order

Definition at line 189 of file classBrowser.php.

◆ $OrderBrowserKey

Browser::$OrderBrowserKey

Definition at line 192 of file classBrowser.php.

◆ $OrderDirection

Browser::$OrderDirection

Definition at line 191 of file classBrowser.php.

◆ $OrderField

Browser::$OrderField

Definition at line 190 of file classBrowser.php.

◆ $Query

Browser::$Query

Definition at line 197 of file classBrowser.php.

◆ $SubTitle

Browser::$SubTitle

Definition at line 181 of file classBrowser.php.

◆ $Title

Browser::$Title

Definition at line 180 of file classBrowser.php.

◆ $TotalFuncs

Browser::$TotalFuncs

Definition at line 205 of file classBrowser.php.

◆ $Totals

Browser::$Totals

Definition at line 204 of file classBrowser.php.

◆ $Union

Browser::$Union

Definition at line 188 of file classBrowser.php.

◆ $Where

Browser::$Where

Definition at line 186 of file classBrowser.php.


The documentation for this class was generated from the following file: