class Listing implements Listable

ViewModel for displaying a list of content objects.

Traits

Provides definition of permitted content object types.
Provides standard implementation for common parts of the Listable interface (excepting pagination and setMetadata()).
Provides methods for validating UTF-8 character encoding and string composition.

Methods

array
listTemplates()

Returns a list of template names used by specific content types.

array
listTypes()

Returns a whitelist of permitted content object types.

setOrder(string $field)

Sets the primary column to order query results by.

from Listable
setOrderType(string $orderType)

Sets the sort type (ascending or descending) for the primary order column of a result set.

from Listable
setSecondaryOrder(string $field)

Sets the secondary column to order query results by.

from Listable
setSecondaryOrderType(string $orderType)

Sets the sort type (ascending or descending) for the secondary order column of a result set.

from Listable
string
pageTitle()

Return title of this page.

from Listable
setPageTitle(string $pageTitle)

Set the title of this page.

from Listable
template()

Return the template object required by this page.

from Listable
setTemplate(string $template)

Set the template used by this page.

from Listable
string
theme()

Return the theme used by this page.

from Listable
setTheme(string $theme)

Set (change) the theme.

from Listable
array
metadata()

Return page-specific metadata overrides.

from Listable
setMetadata(array $metadata = [])

Set page-specific overrides of the site metadata.

string
encodeEscapeUrl(string $url)

URL-encode and escape a query string for use in a URL.

bool
isAlnum(string $alnum)

Check that a string is comprised solely of alphanumeric characters.

bool
isAlnumUnderscore(string $alnumUnderscore)

Check that a string is comprised solely of alphanumeric characters and underscores.

bool
isAlpha(string $alpha)

Check that a string is comprised solely of alphabetical characters.

bool
isUtf8(string $text)

Check if the character encoding of text is UTF-8.

string
trimString(mixed $text)

Cast to string, check UTF-8 encoding and strip trailing whitespace and control characters.

__construct(object $model)

Constructor.

displayList()

Display list of content in short (teaser) form.

displayObject()

Display a single content object.

array
activeTagOptions(string $zeroOption = TFISH_SELECT_TAGS)

Return IDs and titles of tags that are actually in use with content objects.

string
canonicalUrl()

Return canonical URL for this page view.

array
collectionTagOptions(int $id, string $zeroOption = TFISH_SELECT_TAGS)

Return a collection of tags.

countContent()

Count content objects meeting filter criteria.

array
contentTags()

Return tags associated with a content object.

array
extraParams()

Return extra parameters to be included in pagination control links.

getObject(int $id)

Get a content object.

int
limit()

Return user-side pagination limit.

array
listChildren()

Get children of a content object (collection or tag).

listContent()

Get content objects matching cached filter criteria.

string
backUrl()

Return the backUrl.

array
children()

Return children.

content()

Return content object.

int
contentCount()

Return content count.

array
contentList()

Return content list.

string
dateFormat()

Returns the template for formatting the date from preferences.

int
id()

Return ID.

setId(int $id)

Set ID.

string
mapsApiKey()

Returns the Google Maps API key (if set) from preferences.

parent()

Return parent of a content object.

int
start()

Return start.

setStart(int $start)

Set start.

int
tag()

Return tag ID.

setTag(int $tag)

Set tag ID.

string
type()

Return type.

setType(string $type)

Set type.

int
onlineStatus()

Return online status.

string
response()

Return the response message (success or failure) for an action.

Details

in ContentTypes at line 36
array listTemplates()

Returns a list of template names used by specific content types.

Return Value

array Array of type-template key values.

in ContentTypes at line 62
array listTypes()

Returns a whitelist of permitted content object types.

Use this whitelist when dynamically instantiating content objects. If you create additional types of content object (which must be descendants of the TfContentObject class) you must add them to the whitelist below. Otherwise their use will be denied in many parts of the Tuskfish system.

Return Value

array Array of whitelisted (permitted) content object types.

in Listable at line 46
setOrder(string $field)

Sets the primary column to order query results by.

Parameters

string $field Name of the primary column to order the query results by.

in Listable at line 56
setOrderType(string $orderType)

Sets the sort type (ascending or descending) for the primary order column of a result set.

Parameters

string $orderType Ascending (ASC) or descending (DESC) order.

in Listable at line 66
setSecondaryOrder(string $field)

Sets the secondary column to order query results by.

Parameters

string $field Name of the secondary column to order the query results by.

in Listable at line 76
setSecondaryOrderType(string $orderType)

Sets the sort type (ascending or descending) for the secondary order column of a result set.

Parameters

string $orderType Ascending (ASC) or descending (DESC) order.

in Listable at line 88
string pageTitle()

Return title of this page.

Return Value

string

in Listable at line 98
setPageTitle(string $pageTitle)

Set the title of this page.

Parameters

string $pageTitle Title of this page.

in Listable at line 108
Template template()

Return the template object required by this page.

Return Value

Template

in Listable at line 118
setTemplate(string $template)

Set the template used by this page.

Parameters

string $template Name of template (alphanumeric and underscore characters only).

in Listable at line 135
string theme()

Return the theme used by this page.

Return Value

string

in Listable at line 147
setTheme(string $theme)

Set (change) the theme.

You must ensure that the new theme directory contains the HTML template files that you need.

Parameters

string $theme Name of theme directory (alphanumeric and underscores only).

in Listable at line 164
array metadata()

Return page-specific metadata overrides.

Return Value

array

at line 513
setMetadata(array $metadata = [])

Set page-specific overrides of the site metadata.

Overrides trait setMetadata().

Parameters

array $metadata Overriden metadata properties.

in ValidateString at line 41
string encodeEscapeUrl(string $url)

URL-encode and escape a query string for use in a URL.

Trims, checks for UTF-8 compliance, rawurlencodes and then escapes with htmlspecialchars(). If you wish to use the data on a landing page you must decode it with htmlspecialchars_decode() followed by rawurldecode() in that order. But really, if you are using any characters that need to be encoded in the first place you should probably just stop.

Parameters

string $url Unescaped input URL.

Return Value

string Encoded and escaped URL.

in ValidateString at line 59
bool isAlnum(string $alnum)

Check that a string is comprised solely of alphanumeric characters.

Accented regional characters are rejected. This method is designed to be used to check database identifiers or object property names.

Parameters

string $alnum Input to be tested.

Return Value

bool True if valid alphanumerical string, false otherwise.

in ValidateString at line 77
bool isAlnumUnderscore(string $alnumUnderscore)

Check that a string is comprised solely of alphanumeric characters and underscores.

Accented regional characters are rejected. This method is designed to be used to check database identifiers or object property names.

Parameters

string $alnumUnderscore Input to be tested.

Return Value

bool True if valid alphanumerical or underscore string, false otherwise.

in ValidateString at line 95
bool isAlpha(string $alpha)

Check that a string is comprised solely of alphabetical characters.

Tolerates vanilla ASCII only. Accented regional characters are rejected. This method is designed to be used to check database identifiers or object property names.

Parameters

string $alpha Input to be tested.

Return Value

bool True if valid alphabetical string, false otherwise.

in ValidateString at line 113
bool isUtf8(string $text)

Check if the character encoding of text is UTF-8.

All strings received from external sources must be passed through this function, particularly prior to storage in the database.

Parameters

string $text Input string to check.

Return Value

bool True if string is UTF-8 encoded otherwise false.

in ValidateString at line 131
string trimString(mixed $text)

Cast to string, check UTF-8 encoding and strip trailing whitespace and control characters.

Removes trailing whitespace and control characters (ASCII <= 32 / UTF-8 points 0-32 inclusive), checks for UTF-8 character set and casts input to a string. Note that the data returned by this function still requires escaping at the point of use; it is not database or XSS safe.

As the input is cast to a string do NOT apply this function to non-string types (int, float, bool, object, resource, null, array, etc).

Parameters

mixed $text Input to be trimmed.

Return Value

string Trimmed and UTF-8 validated string.

at line 75
__construct(object $model)

Constructor.

Parameters

object $model Instance of a model class.

at line 86
displayList()

Display list of content in short (teaser) form.

at line 98
displayObject()

Display a single content object.

at line 128
array activeTagOptions(string $zeroOption = TFISH_SELECT_TAGS)

Return IDs and titles of tags that are actually in use with content objects.

Parameters

string $zeroOption Text for the default (unselected) option.

Return Value

array IDs and titles as key-value pairs.

at line 143
string canonicalUrl()

Return canonical URL for this page view.

Used to populate the canonical link tag in theme files.

Return Value

string

at line 168
array collectionTagOptions(int $id, string $zeroOption = TFISH_SELECT_TAGS)

Return a collection of tags.

Retrieves tags that have been grouped into a collection as ID-title key-value pairs. Used to build select box controls.

Parameters

int $id ID of the collection content object.
string $zeroOption Text for the default (unselected) option.

Return Value

array Tag IDs and titles as associative array.

at line 179
countContent()

Count content objects meeting filter criteria.

at line 203
array contentTags()

Return tags associated with a content object.

Return Value

array Array of tags as id/title key-value pairs.

at line 215
array extraParams()

Return extra parameters to be included in pagination control links.

Return Value

array

at line 241
getObject(int $id)

Get a content object.

Parameters

int $id ID of content object.

at line 251
int limit()

Return user-side pagination limit.

Return Value

int

at line 261
array listChildren()

Get children of a content object (collection or tag).

Return Value

array Array of content objects.

at line 284
listContent()

Get content objects matching cached filter criteria.

Result is cached as $contentList property.

at line 331
string backUrl()

Return the backUrl.

If the cancel button is clicked, the user will be redirected to the backUrl.

Return Value

string

at line 341
array children()

Return children.

Return Value

array Array of content objects.

at line 351
Content content()

Return content object.

Return Value

Content

at line 361
int contentCount()

Return content count.

Return Value

int

at line 371
array contentList()

Return content list.

Return Value

array Array of content objects.

at line 379
string dateFormat()

Returns the template for formatting the date from preferences.

Return Value

string

at line 389
int id()

Return ID.

Return Value

int ID of content object.

at line 399
setId(int $id)

Set ID.

Parameters

int $id ID of content object.

at line 409
string mapsApiKey()

Returns the Google Maps API key (if set) from preferences.

Return Value

string Google Maps API key.

at line 419
Content parent()

Return parent of a content object.

Return Value

Content Parent content object.

at line 429
int start()

Return start.

Return Value

int

at line 439
setStart(int $start)

Set start.

Parameters

int $start of first object to view in the set of available records.

at line 449
int tag()

Return tag ID.

Return Value

int

at line 459
setTag(int $tag)

Set tag ID.

Parameters

int $tag ID of tag.

at line 469
string type()

Return type.

Return Value

string Type of content object.

at line 481
setType(string $type)

Set type.

Filter list by content type.

Parameters

string $type Type of content object.

at line 491
int onlineStatus()

Return online status.

Return Value

int Online (1) or offline (0).

at line 501
string response()

Return the response message (success or failure) for an action.

Return Value

string