Wizard’s Toolkit Documentation

Browse.php

Browse Data functionality - Wizard’s Toolkit low-code development library

All rights reserved.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Tags
author
Programming Labs
license
All rights reserved
version
2.0

Table of Contents

wtkSetHeaderSort()  : void
Declare Columns to be sortable in browse list.
wtkFilterRequest()  : string
This function manages Filter requests on browse boxes.
wtkFillSuppressArray()  : void
Fill Suppress Array
wtkSearchReplaceRow()  : mixed
Search and replace for each row returned
wtkBuildDataBrowse()  : string
Build Data Browse in HTML table with sortable columns and option to show add, edit and delete button/features.
wtkFillBrowsePage()  : string
Fill Browse Page: this uses any SQL SELECT statement to build a full page showing the result set.
wtkBrowseExport()  : html
This will export the results to CSV and show a download option instead of showing SQL as a browse result set.
wtkBrowseExportXML()  : html
This will export the results to XML and show a download option instead of showing SQL as a browse result set.

Below functions only used internally these should never be called directly

wtkModifyOrderBy()  : string
Alter ORDER BY based on header sort options.
wtkSearchCounter()  : string
Number of values to replace in a data row
wtkColSuppressed()  : bool
Pass in Column Name to see if it is suppressed due to wtkFillSuppressArray
wtkBuildColHeader()  : string
Build Column Header
wtkBuildFooter()  : string
Build Footer

Demos and Tutorials

Below you will find all the functional details however we have found that reviewing code in our demo files is usually a much faster way to learn. We have several demos showing all the different functionality for the wtkBuildDataBrowse function which you will find is one of the most useful functions in the Wizard’s Toolkit library. The PHP demos have exact minimalist code examples of how easy it is to use the powerful feature of passing a SQL query to generate a full listing web page with column sorting, page navigation, totaling and other features.

  • /demo/listDataMin.php - uses wtkFillBrowsePage
  • /demo/listCustomHTML.php - demo wtkFillBrowsePage with custom HTML template
  • /demo/listSortAligns.php - uses wtkSetHeaderSort
  • /demo/list3demo.php - 3 lists on one page
  • /demo/listWithImage.php - demo of WTKIMAGE feature
  • /demo/listRowFunction.php - demo wtkRowFunction for extreme flexibility
  • /demo/listCustomRowHTM.php - demo $gloColHdr and $gloRowHtm

Our Wiki page (https://wizardstoolkit.com/wiki/doku.php?id=browse_box) has much more detail in a better format.

Full feature tutorial is also available:

Functions

wtkSetHeaderSort()

Declare Columns to be sortable in browse list.

wtkSetHeaderSort ( string  $fncColumn [, string  $fncColHeader = '' ] [, string  $fncColSort = '' ] ) : void

Before calling wtkBuildDataBrowse use this function to declare which columns should be sortable. Pass in one, two or three parameters. The first parameter is the SQL column name. The second parameter is the alias or column header you wish to show; if this is ommitted then it will use the column name. If the value is not sortable, for example a formatted date, then for the third parameter pass the actual column name you want to sort on.

For example, for formatted dates pass in the third parameter of actual date field name and in the SELECT use an alias. For example call might be: wtkSetHeaderSort("FormattedBDay", "Birthday", 'date_of_birth'); when your SELECT statement has something like: SELECT first_name, DATE_FORMAT(date_of_birth, '%M %d, %Y') FROM friend_list

Parameters
$fncColumn : string
$fncColHeader : string = ''
$fncColSort : string = ''
Tags
global

array $gloColHeaderArray holds passed parameters

uses
function

wtkInsertSpaces to add spaces for column name

Return values
void —

wtkFilterRequest()

This function manages Filter requests on browse boxes.

wtkFilterRequest( string  $fncFilterName [, string  $fncPage = '' ] ) : string

Browse Data pages often have filter options. Pass in to this function the name of the form field that contains the filter and optionally the Page name. A session variable is created using a combination Page name and Filter name.

If the page was called with Reset=Y then it clears the session variable for this filter. Otherwise it checks to see if the filter has just been set. If so it saves the information in a session variable for the same name as the filter form field and returns the value that was chosen. If the filter was not just set, this function checks the session variable of same name to see if it was previously set and if so uses that value. This way the AJAX calls for page navigation and header sorts will retain prior filter settings.

Note: if $fncPage is not set, then it uses Server variable PHP_SELF. If this is '/wtk/lib/Save.php', then assumes page is being redirected here from the Save.php and therefore it uses the page you set in the wtkGoToURL hidden input field.

By passing the same FilterName and PageName on multiple pages, the filter preference can be shared across multiple pages.

Here is an example:
$pgProjUID = wtkFilterRequest('wtkProjectsUID','pageName');
if ($pgProjUID != ''):
    $pgSQL .= ' AND p.UID = ' . $pgProjUID;
endif;

Parameters
$fncFilterName : string
$fncPage : string = ''

which defaults to PHP_SELF

Return values
string —

$fncResult containing filter value

wtkFillSuppressArray()

Fill Suppress Array

wtkFillSuppressArray ( string  $fncColumnName ) : void

Add columns to this array that you do not want to show in Browse result list. This can be useful for sort order functionality.

Parameters
$fncColumnName : string
Tags
global

array $gloSuppressColumnArray

Return values
void —

wtkSearchReplaceRow()

wtkSearchReplaceRow ( mixed  $fncSearch , mixed  $fncReplace ) : mixed

Search & Replace for data rows. Pass to this function the values you want to search for and what you want it replaced with.

This will affect each row of data returned during the result set creation from wtkFillBrowsePage and wtkBuildDataBrowse.

Parameters
$fncSearch : mixed
$fncReplace : mixed
Return values
mixed —

wtkBuildDataBrowse()

Build Data Browse in HTML table with sortable columns and option to show add, edit and delete button/features.

wtkBuildDataBrowse( string  $fncSQL , array<string|int, mixed>  $fncSqlFilter [, string  $fncTableId = 'wtkBr' ][, string  $fncURL = '' ] [, string  $fncModalEdit = 'N' ] [, string  ) : string

Pass in a SELECT statement and this returns an HTML table with an AJAX-driven result set. Use this instead of wtkFillBrowsePage when multiple browses are needed on a page or you want to position a browse on a form page. The default 'wtkBr' will work as the TableID if there is only 1 browse on page. Each browse on a page must have a unique TableID in order for the AJAX data-set navigation to work.

Parameters
$fncSQL : string
$fncSqlFilter : array<string|int, mixed>

array that has PDO names of fields and their values

$fncTableId : string = 'wtkBr'

Default value ("wtkBr") will only work if 1 browse on page

$fncURL : string = ''
$fncModalEdit : string = 'N'

Pass Y, P or N (default) showing whether should use popup modal window for edit.
If pass 'P' for $fncModalEdit the Add and Edit buttons will use ajaxGo but $gloMoreButtons will use wtkModal.

Tags
uses
function

wtkSearchReplace

uses
function

wtkTimeTrack

uses
function

wtkConnectToDB

uses
function

wtkRowFunction

Return values
string —

entire browse list table

wtkFillBrowsePage()

Fill Browse Page: this uses any SQL SELECT statement to build a full page showing the result set.

wtkFillBrowsePage( string  $fncSQL , array<string|int, mixed>  $fncSqlFilter [, string  $fncTableId = 'wtkBr' ] [, string  $fncURL = '' ] [, string  $fncModalEdit = 'N' ] [, string $fncHTMLtemplate = '' ] ) : string

The function is just a wrapper for wtkBuildDataBrowse and includes a call to wtkMergePage. Thus this function can be called when needing to display a single browse list in a single page (not to be used for Single Page App navigation).

Parameters
$fncSQL : string

SQL Query that will retrieve list of data

$fncSqlFilter : array<string|int, mixed>

array that has PDO names of fields and their values

$fncTableId : string = 'wtkBr'

default value of 'wtkBr'

$fncURL : string = ''

when browse requires a different URL here for the AJAX to use for page navigation

$fncModalEdit : string = 'N'

If pass 'P' for $fncModalEdit the Add and Edit buttons will use ajaxGo but $gloMoreButtons will use wtkModal

$fncHTMLtemplate : string = ''

.htm page to use for HTML template; if blank defaults to /wtk/htm/mpa.htm

Tags
uses
function

wtkMergePage

Return values
string —

entire web page

wtkBrowseExport()

This will export the results to CSV and show a download option instead of showing SQL as a browse result set.

wtkBrowseExport( string  $fncSQL , array<string|int, mixed>  $fncSqlFilter , mixed  $fncTableId ) : html

If $fncTableId is 'modal' then returns HTML to display in a modal, otherwise uses wtk/htm/mcbox.htm and returns entire page. Result has HTML tags removed and is saved to ../exports folder and this returns link to download the file. File is named based on $gloPageTitle (wtk if blank) . date('hms',time()) . '.csv'

Parameters
$fncSQL : string
$fncSqlFilter : array<string|int, mixed>

array that has PDO names of fields and their values

$fncTableId : mixed
Tags
global

string $gloWTKobjConn

global

string $gloPageTitle this is displayed to describe export

global

string $gloFormMsg this will be displayed below $gloPageTitle and above download link

global

string $gloTotalArray

global

string $glowRowChangeArray

uses
function

wtkRemoveStyle to remove HTML styles from values

Return values
html —

to allow downloading CSV file

wtkBrowseExportXML()

This will export the results to XML and show a download option instead of showing SQL as a browse result set.

wtkBrowseExportXML ( string  $fncSQL , array<string|int, mixed>  $fncSqlFilter , mixed  $fncTableId ) : html

If $fncTableId is 'modal' then returns HTML to display in a modal, otherwise uses wtk/htm/mcbox.htm and returns entire page. Result has HTML tags removed and is saved to ../exports folder and this returns link to download the file. File is named based on $gloPageTitle (wtk if blank) . date('hms',time()) . '.xml'

Parameters
$fncSQL : string
$fncSqlFilter : array<string|int, mixed>

array that has PDO names of fields and their values

$fncTableId : mixed
Tags
global

string $gloWTKobjConn

global

string $gloPageTitle this is displayed to describe export

global

string $gloFormMsg this will be displayed below $gloPageTitle and above download link

global

string $gloTotalArray

global

string $glowRowChangeArray

uses
function

wtkRemoveStyle to remove HTML styles from values

Return values
html —

to allow downloading XML file

wtkModifyOrderBy()

Alter ORDER BY based on header sort options.

wtkModifyOrderBy ( string  $fncSQL , mixed  $fncTableId ) : string

This is called by wtkBuildDataBrowse, wtkBrowseExport and wtkBrowseExportXML and should not be called directly.

wtkSetHeaderSort is used to make sortable headers in browse list generated by wtkBuildDataBrowse. When the header is clicked, it calls a JavaScript function which passes parameters to a PHP page and this function is used to adjust the ORDER BY.

Parameters
$fncSQL : string

SQL query for wtkBuildDataBrowse

$fncTableId : mixed
Return values
string —

$fncSQL sends back SQL query with adjusted ORDER BY

wtkSearchCounter()

Number of values to replace in a data row

wtkSearchCounter () : string
Tags
global

string $pgSearchReplaceRowCntr

Return values
string —

$pageSearchReplaceRowCntr which holds count for managing $gloRowChangeArray values

wtkColSuppressed()

Pass in Column Name to see if it is suppressed due to wtkFillSuppressArray

wtkColSuppressed( string  $fncColumnName ) : bool

This function is called from wtkBuildDataBrowse, wtkBrowseExport and wtkBrowseExportXML. If column is suppressed it will not be shown.

Parameters
$fncColumnName : string
Tags
global

array $gloSuppressColumnArray

Return values
bool —

true if column is in $gloSuppressColumnArray array

wtkBuildColHeader()

Build Column Header

wtkBuildColHeader( string  $fncColumn , string  $fncTableId , string  $fncURL) : string

This uses the values you passed in by calling wtkSetHeaderSort to make columns sortable in the browse results. It is called by wtkBuildDataBrowse and should not be called directly.

Parameters
$fncColumn : string

Column name to be shown in header of list. Will be sortable if previously declared by calling wtkSetHeaderSort.

$fncTableId : string

by each browse list having different Table Ids sorts and page navigation know which browse to update

$fncURL : string

this determines what URL to call to update browse list

Return values
string —

column header including sortable JavaScript function call to sort if necessary

wtkBuildFooter()

Build Footer

wtkBuildFooter ( string  $fncTableId , string  $fncURL) : string

This builds the footer information that goes at the bottom of the browse result set and allows for page navigation. This is called from wtkBuildDataBrowse and should not be called directly.

Parameters
$fncTableId : string
$fncURL : string
Tags
uses
function

wtkTimeTrack

Return values
string —

html footer for browse box navigation

Search results