Documentation

Admin
in package

Application

Useful functions for the admin

Properties

$cat_singlecat : bool
$cat_tablename : string
$error_msgs : mixed

Methods

attrEditor() : void: Renders an interface for editing attributes Uses a multiedit
categorySelection() : void: Outputs an interface for selecting multiple categories
checkboxList() : void: Outputs a list of checkboxes.
clearFieldErrors() : void: Clears all pre-field error messages
clearOldLocks() : void: Remove all locks which are older than the allowed lock time.
createLockKey() : string: Return a unique key for identifying a session.
ensureUrlAbsolute() : string: For a given URL, ensure it's absolute.
fieldError() : string: Shows a per-field error message
forceUnlock() : void: Nuke a lock
generateFriendlyName() : string: Create a plural human-friendly version of a controller shorthand name.
getController() : ManagedAdminController: Gets an instance of a managed admin controller
getControllerSlug() : string|null: When in the admin, return the slug of the controller being used, e.g. 'page' or 'blog_post'
getLock() : array<string|int, mixed>|null: Gets the lock details for a given record
getRecordId() : int|null: When in the admin, return the record id being added or edited.
isTourCompleted() : bool: Has a given JavaScript tour been completed?
lock() : int|null: Locks the given record for the current user
locksEnabled() : bool: Is admin locks enabled?
lookupErrMsg() : string: Finds an appropriate error message for the specified error code
multieditBuild() : array<string|int, mixed>: For a set of multi-edit fields, loads the data into a much more usable array
navigationTreeNode() : void: Render a tree of nodes for the navigation area of the admin Used by the pages module
pageDropdown() : void: Deprecated wrapper around {@see Fb::pageDropdown}
pingLock() : void: Updates the timestamp for a given lock record to prevent it from timing out
radioList() : void: Outputs a list of radiobuttons, which will all use the same field name
setCategorySinglecat() : void
setCategoryTablename() : void
setTourCompleted() : mixed: Set a given JavaScript tour as being "completed", preventing it from being shown again.
topNav() : void: Return HTML for the top nav tabs
unlock() : void: Removes locks for the current user
widgetList() : void: Shows a UI for the list of widgets, for editing

$cat_singlecat


        private
        static    bool
    $cat_singlecat
     = false

$cat_tablename


        private
        static    string
    $cat_tablename

$error_msgs


        private
        static    mixed
    $error_msgs
     = array('required' => 'This field is required', 'length\[0,([0-9]+)\]' => 'Too long, max length is $1 characters', 'length\[([0-9]+),([0-9]+)\]' => 'Incorrect length, must be between $1 and $2 characters', 'length\[([0-9]+)\]' => 'Incorrect length, must be exactly $1 characters', 'alphaDash' => 'Field can only contain letters, numbers, underscores (_) and dashes (-)', 'emailUnique' => 'Email address is not unique', 'email' => 'Email address is not valid', 'matches\[password.*' => 'Password fields do not match', 'numMin\[([-0-9]+)\]' => 'Number must be at least $1', 'numMax\[([-0-9]+)\]' => 'Number must be at most $1', 'numBetween\[([-0-9]+),([-0-9]+)\]' => 'Number must be between $1 and $2 inclusive', 'check_redirect' => 'URL must begin with http:// (external url) or / (internal url)', 'exclusive\[(.*)\]' => 'These fields cannot be used together, only one of them may be used', 'check_controller_entrance\[.*\]' => 'Only one page may reference any given module', 'raw\[(.+)\]' => '$1', '.+' => 'Incorrect value provided')

attrEditor()

Renders an interface for editing attributes Uses a multiedit


    public
            static        attrEditor(array<string|int, mixed> $current_attrs) : void

Parameters

$current_attrs : array<string|int, mixed>

Return values

void —

Outputs HTML directly

categorySelection()

Outputs an interface for selecting multiple categories


    public
            static        categorySelection(mixed $field, mixed $data, mixed $selected) : void

Parameters

$field : mixed: The field name
$data : mixed: An array of key-value pairs, with the keys being the id of the category, and the value being the name.
$selected : mixed: An array of selected category ids.

Return values

void —

Outputs HTML directly

checkboxList()

Outputs a list of checkboxes.


    public
            static        checkboxList(string $field, array<string|int, mixed> $data, array<string|int, mixed> $selected) : void

If the $field parameter is provided, multiple checkboxes with the same field name will be rendered. $data should be a key-value pair, with the keys being the value of the checkbox, and the value being the label. $selected should be an array of selected checkbox ids.

If the $field parameter is omitted (null), multiple checkboxes widh different field names will be rendered. The checkboxes will be binary checkboxes with a value of 1. $data should be a key-value pair, with the keys being the field name, and the value being the label. $selected should be a key-value pair, with the keys being the field name, and the value being 1 or 0.

Parameters

$field : string: The field name.
$data : array<string|int, mixed>
$selected : array<string|int, mixed>

Return values

void —

Outputs HTML directly

clearFieldErrors()

Clears all pre-field error messages


    public
            static        clearFieldErrors([string $scope = 'admin' ]) : void

Parameters

$scope : string = 'admin': The scope of the field errors. Defaults to 'admin'.

clearOldLocks()

Remove all locks which are older than the allowed lock time.


    public
            static        clearOldLocks() : void

createLockKey()

Return a unique key for identifying a session.


    public
            static        createLockKey() : string

This will be constant even if the session id changes, although it's nuked if you log out.

Return values

string

ensureUrlAbsolute()

For a given URL, ensure it's absolute.


    public
            static        ensureUrlAbsolute(string $url) : string

If it's not absolute, the current admin abs-root is prepended

Parameters

$url : string: Either relative or absolute

Return values

string —

Absolute URL

fieldError()

Shows a per-field error message


    public
            static        fieldError(string $field_name[, string $scope = 'admin' ]) : string

Parameters

$field_name : string: The name of the field to show the error message for.
$scope : string = 'admin': The scope of the field errors. Defaults to 'admin'.

Return values

string —

The HTML for the error message.

forceUnlock()

Nuke a lock


    public
            static        forceUnlock(int $lock_id) : void

Parameters

$lock_id : int

generateFriendlyName()

Create a plural human-friendly version of a controller shorthand name.


    public
            static        generateFriendlyName(string $shorthand) : string

Parameters

$shorthand : string

Return values

string

getController()

Gets an instance of a managed admin controller


    public
            static        getController(string $name[, bool $autoload = true ]) : ManagedAdminController

When parsing URL strings, please enforce the shorthand form with $autoload = false.

Parameters

$name : string

A class name or shorthand identifier, e.g.

'awesome'
'Sprout\Controllers\Admin\AwesomeAdminController' (autoload = true)

$autoload : bool = true

permit class names (default: true)

true: permit class names and shorthand
false: only permit shorthand names

Return values

ManagedAdminController

getControllerSlug()

When in the admin, return the slug of the controller being used, e.g. 'page' or 'blog_post'


    public
            static        getControllerSlug() : string|null

Return values

string|null

getLock()

Gets the lock details for a given record


    public
            static        getLock(string $ctlr, int $record_id) : array<string|int, mixed>|null

Parameters

$ctlr : string: Controller name
$record_id : int: DB record ID

Return values

array<string|int, mixed>|null —

If locked; has keys 'id', 'operator_name', 'lock_key', 'date_modified'

getRecordId()

When in the admin, return the record id being added or edited.


    public
            static        getRecordId() : int|null

If it's not an add or an edit, returns null. If used outside of the admin, behaviour is undefined

Return values

int|null

isTourCompleted()

Has a given JavaScript tour been completed?


    public
            static        isTourCompleted(string $tour_name) : bool

Parameters

$tour_name : string: Internal name for the tour, e.g. "page_edit"

Return values

bool —

True if it's been completed, false if it hasn't

lock()

Locks the given record for the current user


    public
            static        lock(string $ctlr, int $record_id) : int|null

Parameters

$ctlr : string: The controller responsible for the record
$record_id : int: The record ID

Return values

int|null —

Lock ID if the lock was acquired, null if it was already held

locksEnabled()

Is admin locks enabled?


    public
            static        locksEnabled() : bool

Return values

bool —

True if they are, false if they aren't

lookupErrMsg()

Finds an appropriate error message for the specified error code


    public
            static        lookupErrMsg(string|AdminError $err) : string

Parameters

$err : string|AdminError: The error code to lookup.

Return values

string —

The error message.

multieditBuild()

For a set of multi-edit fields, loads the data into a much more usable array


    public
            static        multieditBuild(array<string|int, mixed> $dataset, array<string|int, mixed> $field_names) : array<string|int, mixed>

Input: [phone] = ('1234 1234', '4321 4321') [type] = ('Mobile', 'Home')

Output: [1] = ('phone' => '1234 1234', 'type' => 'Mobile') [2] = ('phone' => '4321 4321', 'type' => 'Home')

Parameters

$dataset : array<string|int, mixed>: The original data to use
$field_names : array<string|int, mixed>: An array of the names of the fields to use

Return values

array<string|int, mixed>

navigationTreeNode()

Render a tree of nodes for the navigation area of the admin Used by the pages module


    public
            static        navigationTreeNode(Treenode $node, array<string|int, mixed> $actions[, int $depth = 1 ]) : void

Parameters

$node : Treenode: The node to render
$actions : array<string|int, mixed>: Additional links to show in the cog icon menu; keys: url, class, name
$depth : int = 1: How deep in the tree the rendering is, starts at 1 for the top-level

Return values

void —

Outputs HTML directly

pageDropdown()

Deprecated wrapper around {@see Fb::pageDropdown}


    public
            static        pageDropdown(string $field_name[, int $selected = null ][, int $exclude = null ][, int $subsite_id = null ][, string $top_text = 'None (top level page)' ]) : void

use Fb::pageDropdown instead

Parameters

$field_name : string: The name of the field
$selected : int = null: The id of the page to select
$exclude : int = null: The id of the page to exclude from the list
$subsite_id : int = null: The subsite of pages to show. Defaults to the current admin subsite
$top_text : string = 'None (top level page)': Text for the top (id 0) item

Return values

void —

Outputs HTML directly

pingLock()

Updates the timestamp for a given lock record to prevent it from timing out


    public
            static        pingLock(int $lock_id) : void

Parameters

$lock_id : int

radioList()

Outputs a list of radiobuttons, which will all use the same field name


    public
            static        radioList(string $field, array<string|int, mixed> $data, array<string|int, mixed> $selected) : void

Parameters

$field : string: The field name.
$data : array<string|int, mixed>: The data. Key is the radiobutton value, Value is used in the label for the radiobutton.
$selected : array<string|int, mixed>: The selected item

Return values

void —

Outputs HTML directly

setCategorySinglecat()


    public
            static        setCategorySinglecat(bool $value) : void

Parameters

$value : bool

setCategoryTablename()


    public
            static        setCategoryTablename(string $name) : void

Parameters

$name : string

setTourCompleted()

Set a given JavaScript tour as being "completed", preventing it from being shown again.


    public
            static        setTourCompleted(string $tour_name) : mixed

Parameters

$tour_name : string: Internal name for the tour, e.g. "page_edit"

topNav()

Return HTML for the top nav tabs


    public
            static        topNav(string $selected_controller) : void

Parameters

$selected_controller : string

Return values

void —

Echos HTML

unlock()

Removes locks for the current user


    public
            static        unlock([string $ctlr = null ][, int $record_id = null ]) : void

Parameters

$ctlr : string = null: Will refine lock removal by controller
$record_id : int = null: Will refine lock removal by record id

widgetList()

Shows a UI for the list of widgets, for editing


    public
            static        widgetList(string $field_name, WidgetArea $area, array<string|int, mixed> $curr_widgets[, bool $enable_all = true ]) : void

Parameters

$field_name : string: Name of the field to store the final value when the form is submitted
$area : WidgetArea: The area that is being edited
$curr_widgets : array<string|int, mixed>: A list of the widgets currently being used, in order, as db rows with keys: type string Class name, e.g. 'RichText' settings string Opaque JSON string conditions string Opaque JSON string active int 1 for active, 0 for inactive heading string HTML H2 rendered front-end within widget
$enable_all : bool = true: Toggle whether all the widgets are enabled by default (defaults to true)

Return values

void —

Outputs HTML directly

Admin in package Application

Table of Contents

Properties

Methods

Properties

$cat_singlecat

$cat_tablename

$error_msgs

Methods

attrEditor()

Parameters

Return values

categorySelection()

Parameters

Return values

checkboxList()

Parameters

Return values

clearFieldErrors()

Parameters

clearOldLocks()

createLockKey()

Return values

ensureUrlAbsolute()

Parameters

Return values

fieldError()

Parameters

Return values

forceUnlock()

Parameters

generateFriendlyName()

Parameters

Return values

getController()

Parameters

Tags

Return values

getControllerSlug()

Return values

getLock()

Parameters

Return values

getRecordId()

Return values

isTourCompleted()

Parameters

Return values

lock()

Parameters

Tags

Return values

locksEnabled()

Return values

lookupErrMsg()

Parameters

Return values

multieditBuild()

Parameters

Return values

navigationTreeNode()

Parameters

Return values

pageDropdown()

Parameters

Return values

pingLock()

Parameters

radioList()

Parameters

Return values

setCategorySinglecat()

Parameters

setCategoryTablename()

Parameters

setTourCompleted()

Parameters

topNav()

Parameters

Return values

Admin
in package

Application