Documentation

AdminController extends Controller
in package

Application

Main class to handle admin processing.

This delegates processing to controllers registered with Register::adminControllers

Constants

ALLOW_PRODUCTION : mixed = TRUE

Properties

$action_log : mixed: Should this controller log add/edit/delete actions?

Methods

__call() : void: Handles methods that do not exist.
__construct() : void: Does some general admin loading
_run() : mixed: The router/kohana will invoke this method to invoke an action.
add() : mixed: Shows an add form for the specified item
addSave() : mixed: Executes the save action for a specific item
aiReprocess() : mixed: Shows an AI bulk reprocessing form for the specified type
aiReprocessAction() : mixed: Executes the reprocessing action for a specific item
ajaxUnlock() : mixed: Unlock a record.
call() : void: Directly calls a method provided by an admin controller
checkRecordAccess() : bool: Checks that an admin user has access to an individual record
closeFirstrun() : void: Closes the 'first run' box, which is shown on the admin dashboard
contents() : mixed: Shows an edit form for the specified item
cronGenericActivate() : mixed: Activates AutoLaunch revisions
dashboard() : mixed: Dashboard shown when a user first logs in to the admin
delete() : mixed: Shows a delete form for the specified item
deleteSave() : mixed: Executes the delete action for a specific item
duplicate() : mixed: Shows a duplication form for the specified item This uses the edit form with some string replacements
duplicateSave() : mixed: Executes the save action for a record duplication
edit() : mixed: Shows an edit form for the specified item
editSave() : mixed: Executes the save action for a specific item
emailReportAction() : mixed: Executes the save action for a specific email report
emailReportAdd() : mixed: Shows the import form for the specified item
emailReports() : mixed: Shows the import form for the specified item
emailReportSend() : mixed: Sends a specified email report
export() : mixed: Shows an export form for the specified type
exportAction() : mixed: Executes the export action for a specific item
extra() : void: Calls any 'extra' commands that might be provided by the controller
getAbsModulePath() : string: Get the absolute path of the current module for this controller.
getCssClassName() : string: Return the class name for this controller, expressed in CSS style, i.e. with dashes
getModule() : ModuleInterface|null: Get the module that this controller belongs to.
getModulePath() : string: Get the a prefix suitable for finding views for this controller.
heartbeat() : mixed
importAction() : mixed: Executes the import action
importOptions() : mixed: Shows the import form for the specified item
importUpload() : mixed: File upload box for importing, options are the next step
importUploadAction() : mixed: Copies the file to a temporary directory
index() : mixed: Home page of admin area
intro() : mixed: Shows an introduction for a specified type.
login() : mixed: Shows a login form
loginAction() : mixed: Processes a user login
loginCallback() : void: If using a 3rd party provider, you must redirect login success to here
loginTwoFactor() : mixed: Show the two-factor-auth ui for a half-logged-in operator
loginTwoFactorAction() : mixed: Process the result of a two-factor-auth for a half-logged-in operator
logout() : mixed: Processes a user logout
moderate() : mixed: Moderation
moderateAction() : mixed: Processes the moderation form
restore() : void: Restore a deleted record from log data
result() : mixed: Generic result page for POST redirects.
search() : mixed: Shows a search form for the specified item
setActiveSubsite() : mixed: Sets the active subsite, and then redirects back to the admin area.
styleGuide() : mixed: View the various styles available in the admin area
userAgent() : void: Browser information
autoSetEmptyParam() : void: Auto-set the "empty" param for fields with foreign keys to be NULL
deleteRecord() : int: Deletes a record, and logs the deletion This should be used by all _deleteSave methods Starts a transaction and commits it if not already in a transaction when called
generateFormView() : PhpView: Generates a form view from a JSON config file
jsonExtraValidate() : void: Do any additional validation prior to saving the record
loadEditJson() : array<string, array<string|int, array<string, mixed>>>: Loads a JSON config file for an automated edit-type form for this controller
loadFormJson() : array<string|int, mixed>: Loads a config file for a JsonForm associated with this controller
loadRecord() : array<string|int, mixed>|bool: Fetches the pre-update record from the database.
logAction() : int: Stores a history item in the database, recording an add (i.e. insert), edit, or delete.
logAdd() : int: Logs an add action. This is a wrapper for {@see Controller::logAction}
logAddCategory() : int: Logs the adding of a record to a category. This is a wrapper for {@see Controller::logAction}
logDelete() : int: Logs a delete action. This is a wrapper for {@see Controller::logAction}
logDeleteCategory() : int: Logs the removal of a record from a category. This is a wrapper for {@see Controller::logAction}
logEdit() : int: Logs an edit action. This is a wrapper for {@see Controller::logAction}
perRecordPermissionsFields() : string: Generates HTML for fields relating to per-record permissions in the 'save changes' box
replaceSet() : void: Inserts records which are in $new_records, but are not in the specified table Deletes records which are in the specified table, but not in $new_records Updates records which are in both
saveJsonData() : bool: Automatically saves the data associated with a submission on a JSON-generated form
checkAccess() : bool: Check access for a given controller/access flag combo If this returns false, it will echo out an error message; the calling code should just return.
cleanupCommonPostData() : mixed: Ensure 'active' flag and 'tags' POST fields have values set, if they are nonexistant
error() : mixed: Shows an error message in the admin skin
lock() : mixed: Does lock checking, locking, or lock messages.
renderSubActions() : string: Render a list of sub-actions into HTML as links
setDefaultMainviewParams() : mixed: Sets the a bunch of parameters for a the main view.
setNavigation() : mixed: Sets up the sidebar navigation for a view to show the navigation for a specific controller.
unlock() : mixed: Unlocks lock for a given record/controller, all records for a controller, or all locks

ALLOW_PRODUCTION


    public
        mixed
    ALLOW_PRODUCTION
    = TRUE

$action_log

Should this controller log add/edit/delete actions?


        protected
            mixed
    $action_log
     = false

__call()

Handles methods that do not exist.


    public
                    __call(string $method, array<string|int, mixed> $args) : void

Parameters

$method : string: Method name
$args : array<string|int, mixed>: Arguments

__construct()

Does some general admin loading


    public
                    __construct() : void

_run()

The router/kohana will invoke this method to invoke an action.


    public
                    _run(mixed $method, mixed $args) : mixed

Parameters

$method : mixed
$args : mixed

add()

Shows an add form for the specified item


    public
                    add(string $type) : mixed

Parameters

$type : string: The type of item to show the add form of

addSave()

Executes the save action for a specific item


    public
                    addSave(string $type) : mixed

Parameters

$type : string: The type of item to add

aiReprocess()

Shows an AI bulk reprocessing form for the specified type


    public
                    aiReprocess(string $type) : mixed

Parameters

$type : string: The type of item to show the AI form of

aiReprocessAction()

Executes the reprocessing action for a specific item


    public
                    aiReprocessAction(string $type) : mixed

Parameters

$type : string: The type of item to save

ajaxUnlock()

Unlock a record.


    public
                    ajaxUnlock() : mixed

Called via ajax in the beforeunload javascript event

call()

Directly calls a method provided by an admin controller


    public
                    call(string $class, string $method, string ...$args) : void

Supports var args.

Parameters

$class : string: The shorthand class name, e.g. 'page'
$method : string: The method name, e.g. 'reorder_top'
$args : string: additional args

Return values

void —

Does whatever the called function does, e.g. echo or redirect

checkRecordAccess()

Checks that an admin user has access to an individual record


    public
                    checkRecordAccess(ManagedAdminController $ctlr, int $item_id) : bool

Parameters

$ctlr : ManagedAdminController: The controller which manages the table containing the record
$item_id : int: The id of the row to be edited/deleted

Return values

bool —

True if access allowed

closeFirstrun()

Closes the 'first run' box, which is shown on the admin dashboard


    public
                    closeFirstrun() : void

Return values

void —

Redirects to the admin dashboard

contents()

Shows an edit form for the specified item


    public
                    contents(string $type) : mixed

Parameters

$type : string: The type of item to show the edit form of

cronGenericActivate()

Activates AutoLaunch revisions


    public
                    cronGenericActivate() : mixed

dashboard()

Dashboard shown when a user first logs in to the admin


    public
                    dashboard() : mixed

delete()

Shows a delete form for the specified item


    public
                    delete(string $type, int $id) : mixed

Parameters

$type : string: Shorthand controller name; see Register::adminControllers
$id : int: The id of the record to show

deleteSave()

Executes the delete action for a specific item


    public
                    deleteSave(string $type, int $id) : mixed

Parameters

$type : string: The Type of the item to delete
$id : int: The id of the record to delete

duplicate()

Shows a duplication form for the specified item This uses the edit form with some string replacements


    public
                    duplicate(string $type, int $id) : mixed

Parameters

$type : string: The type of item to show the duplication form of
$id : int: The id of the record to duplicate

duplicateSave()

Executes the save action for a record duplication


    public
                    duplicateSave(string $type, int $orig_id) : mixed

Parameters

$type : string: The type of item to save
$orig_id : int: The id of the record to save

edit()

Shows an edit form for the specified item


    public
                    edit(string $type, int $id) : mixed

Parameters

$type : string: The type of item to show the edit form of
$id : int: The id of the record to edit

editSave()

Executes the save action for a specific item


    public
                    editSave(string $type, int $id) : mixed

Parameters

$type : string: The type of item to save
$id : int: The id of the record to save

emailReportAction()

Executes the save action for a specific email report


    public
                    emailReportAction(string $type) : mixed

Parameters

$type : string: The type of item to save

emailReportAdd()

Shows the import form for the specified item


    public
                    emailReportAdd(string $type) : mixed

Parameters

$type : string: The type of item to show the import form of

emailReports()

Shows the import form for the specified item


    public
                    emailReports(string $type) : mixed

Parameters

$type : string: The type of item to show the import form of

emailReportSend()

Sends a specified email report


    public
                    emailReportSend(int $report_id) : mixed

Parameters

$report_id : int: The report to load and send

export()

Shows an export form for the specified type


    public
                    export(string $type) : mixed

Parameters

$type : string: The type of item to show the export form of

exportAction()

Executes the export action for a specific item


    public
                    exportAction(string $type) : mixed

Parameters

$type : string: The type of item to export

extra()

Calls any 'extra' commands that might be provided by the controller


    public
                    extra(string $class, string $method, string ...$args) : void

Method names will be prefixed with '_extra' and must be public Names which are lower_cased will be converted to camelCase

Supports varargs - additional args are passed to the underlying function Called method should return an array, with two keys: title string Main title content string HTML for the main content area

Parameters

$class : string: The class name of the method to call (must extend ManagedAdminController)
$method : string: The method name to call
$args : string: additional params

Return values

void —

Outputs HTML

getAbsModulePath()

Get the absolute path of the current module for this controller.


    public
                    getAbsModulePath() : string

TODO this might be too broad. It's only used for loading JSON forms and perhaps encourages bad behaviour. Such as assuming common path structures for all modules, where instead this should be written into the module class.

Return values

string

getCssClassName()

Return the class name for this controller, expressed in CSS style, i.e. with dashes


    public
                    getCssClassName() : string

Example: When called from BlogPostController --> 'blog-post-controller'

Return values

string —

Name of this PHP class, in a format suitable for use in CSS

getModule()

Get the module that this controller belongs to.


    public
                    getModule() : ModuleInterface|null

If the controllers belongs to Sprout itself, this returns null.

Return values

ModuleInterface|null

getModulePath()

Get the a prefix suitable for finding views for this controller.


    public
                    getModulePath() : string

Do not assume that all modules, or even core sprout live relative to each other or the DOCROOT (as they previously did).

TODO rename this - like getViewPrefix()

Return values

string —

'sprout' or 'modules/AwesomeModule'

heartbeat()


    public
                    heartbeat() : mixed

importAction()

Executes the import action


    public
                    importAction(string $type) : mixed

Parameters

$type : string: The type of item to import

importOptions()

Shows the import form for the specified item


    public
                    importOptions(string $type) : mixed

Parameters

$type : string: The type of item to show the import form of

importUpload()

File upload box for importing, options are the next step


    public
                    importUpload(string $type) : mixed

Parameters

$type : string: The type of item to show the import form of

importUploadAction()

Copies the file to a temporary directory


    public
                    importUploadAction(mixed $type) : mixed

Parameters

$type : mixed

index()

Home page of admin area


    public
                    index() : mixed

intro()

Shows an introduction for a specified type.


    public
                    intro(string $type) : mixed

Parameters

$type : string: The type to show an intro for.

login()

Shows a login form


    public
                    login() : mixed

loginAction()

Processes a user login


    public
                    loginAction() : mixed

loginCallback()

If using a 3rd party provider, you must redirect login success to here


    public
                    loginCallback() : void

loginTwoFactor()

Show the two-factor-auth ui for a half-logged-in operator


    public
                    loginTwoFactor() : mixed

loginTwoFactorAction()

Process the result of a two-factor-auth for a half-logged-in operator


    public
                    loginTwoFactorAction() : mixed

logout()

Processes a user logout


    public
                    logout() : mixed

moderate()

Moderation


    public
                    moderate() : mixed

moderateAction()

Processes the moderation form


    public
                    moderateAction() : mixed

restore()

Restore a deleted record from log data


    public
                    restore(int $log_id) : void

Parameters

$log_id : int: ID in the history_items table

result()

Generic result page for POST redirects.


    public
                    result(mixed $state) : mixed

Parameters

$state : mixed

search()

Shows a search form for the specified item


    public
                    search(string $type) : mixed

Parameters

$type : string: The type of item to show the search form for

setActiveSubsite()

Sets the active subsite, and then redirects back to the admin area.


    public
                    setActiveSubsite() : mixed

Uses the post variable "subsite".

styleGuide()

View the various styles available in the admin area


    public
                    styleGuide(mixed $section) : mixed

Parameters

$section : mixed

userAgent()

Browser information


    public
                    userAgent() : void

Return values

void —

Echos HTML

autoSetEmptyParam()

Auto-set the "empty" param for fields with foreign keys to be NULL


    protected
                    autoSetEmptyParam(array<string, array<string|int, array<string, mixed>>> &$conf) : void

This greatly reduces the number of foreign-key constraints hit in day-to-day use, especially with file fields.

Parameters

$conf : array<string, array<string|int, array<string, mixed>>>: Json form configuration

Return values

void —

Array $conf is altered in-place

deleteRecord()

Deletes a record, and logs the deletion This should be used by all _deleteSave methods Starts a transaction and commits it if not already in a transaction when called


    protected
                    deleteRecord(string $table, int $record_id[, int $parent_log_id = 0 ]) : int

Parameters

$table : string: Table name
$record_id : int
$parent_log_id : int = 0: ID of a parent entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data.

Return values

int —

ID of the record inserted into the history_items table (0 if no logging)

generateFormView()

Generates a form view from a JSON config file


    protected
                    generateFormView(mixed $file_name) : PhpView

Parameters

$file_name : mixed

Return values

PhpView

jsonExtraValidate()

Do any additional validation prior to saving the record


    protected
                    jsonExtraValidate(int $id, Validator $validator) : void

Parameters

$id : int: Record ID or 0 for adds
$validator : Validator: Validator instance to attach your errors to

loadEditJson()

Loads a JSON config file for an automated edit-type form for this controller


    protected
                    loadEditJson() : array<string, array<string|int, array<string, mixed>>>

Return values

array<string, array<string|int, array<string, mixed>>>

loadFormJson()

Loads a config file for a JsonForm associated with this controller


    protected
                    loadFormJson(string $file_name) : array<string|int, mixed>

Parameters

$file_name : string: The config file name, e.g. 'register.json'

Return values

array<string|int, mixed>

loadRecord()

Fetches the pre-update record from the database.


    protected
                    loadRecord(string $table, int $record_id) : array<string|int, mixed>|bool

Used by the action log system, and disabled if the action log system has been turned off

Parameters

$table : string: Name of table to load record from
$record_id : int: ID of record to load

Return values

array<string|int, mixed>|bool —

False if not using logging for this controller, else the record row

logAction()

Stores a history item in the database, recording an add (i.e. insert), edit, or delete.


    protected
                    logAction(string $table, int $record_id, string $type[, array<string|int, mixed> $data = [] ][, int $parent_log_id = 0 ]) : int

Should be called AFTER the action has been made. N.B. This is a low-level method; the friendlier wrapper methods are preferred; e.g. Controller::logAdd, Controller::logEdit

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the added/edited/deleted record
$type : string: ENUM value from history_items.type
$data : array<string|int, mixed> = []: Data associated with an add/edit. The handling differs based on the $type parameter: 'Add' ignored 'Edit' should be an array of the pre-update data, used to build a diff 'Delete' should contain the complete data of the deleted record 'Add category' should contain ['cat_id' => value] 'Delete category' should contain ['cat_id' => value] 'Change password' should be an empty array
$parent_log_id : int = 0: ID of a parent log entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data. N.B. This is only relevant for deletes

Return values

int —

ID of the record inserted into the history_items table; 0 if no insert was done; -1 if it failed

logAdd()

Logs an add action. This is a wrapper for {@see Controller::logAction}


    protected
                    logAdd(string $table, int $record_id) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the added record

Return values

int —

ID of the record inserted into the history_items table

logAddCategory()

Logs the adding of a record to a category. This is a wrapper for {@see Controller::logAction}


    protected
                    logAddCategory(string $table, int $record_id, int $cat_id) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The ID of the record which was added to the category
$cat_id : int: The ID of the category which the record was added to

Return values

int —

ID of the record inserted into the history_items table

logDelete()

Logs a delete action. This is a wrapper for {@see Controller::logAction}


    protected
                    logDelete(string $table, int $record_id, array<string|int, mixed> $data[, int $parent_log_id = 0 ]) : int

Parameters

$table : string: The table which contained the deleted record
$record_id : int: The id of the deleted record
$data : array<string|int, mixed>: The complete contents of the record which was deleted, i.e. [field => value], so it can be restored if necessary
$parent_log_id : int = 0: ID of a parent log entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data.

Return values

int —

ID of the record inserted into the history_items table

logDeleteCategory()

Logs the removal of a record from a category. This is a wrapper for {@see Controller::logAction}


    protected
                    logDeleteCategory(string $table, int $record_id, int $cat_id) : int

Parameters

$table : string: The table which contains the record which was removed from the category
$record_id : int: The ID of the record which was removed from the category
$cat_id : int: The ID of the category which the record was removed from

Return values

int —

ID of the record inserted into the history_items table

logEdit()

Logs an edit action. This is a wrapper for {@see Controller::logAction}


    protected
                    logEdit(string $table, int $record_id, array<string|int, mixed> $data) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the edited record
$data : array<string|int, mixed>: Pre-update data, used to build a diff

Return values

int —

ID of the record inserted into the history_items table

perRecordPermissionsFields()

Generates HTML for fields relating to per-record permissions in the 'save changes' box


    protected
                    perRecordPermissionsFields(ManagedAdminController $ctlr, int $item_id) : string

Parameters

$ctlr : ManagedAdminController: The controller to check permissions for
$item_id : int: The ID of the record being edited (0 when adding a new record)

Return values

string —

HTML

replaceSet()

Inserts records which are in $new_records, but are not in the specified table Deletes records which are in the specified table, but not in $new_records Updates records which are in both


    protected
                    replaceSet(string $table, array<string|int, mixed> $new_records, array<string|int, mixed> $conditions) : void

Matching is done on the 'id' field, as a result the $new_records arrays MUST contain an id field.

Parameters

$table : string: The table name. Do not include prefix.
$new_records : array<string|int, mixed>: The new records for the table. Should be an array of arrays, With each sub-array being the arguments which would normally be passed to Pdb::insert or Pdb::update
$conditions : array<string|int, mixed>: A where clause to use when looking to see what records already exist. Pdb::buildClause

saveJsonData()

Automatically saves the data associated with a submission on a JSON-generated form


    protected
                    saveJsonData(array<string, array<string|int, array<string, mixed>>> $conf, int &$item_id[, string $mode = '' ]) : bool

Parameters

$conf : array<string, array<string|int, array<string, mixed>>>: Config loaded from a JSON file
$item_id : int: Database ID of record to store data in. If zero, a new record will be inserted, and as this argument is a reference, it will be updated with the auto-increment ID generated by the insert.
$mode : string = '': Mode: 'add', 'edit', or something custom (e.g. 'duplicate', 'verify'). If blank, 'add' or 'edit' will be automatically determined, based on $item_id

Return values

bool —

True if the save succeeded. If false is returned, errors will be saved in $_SESSION

checkAccess()

Check access for a given controller/access flag combo If this returns false, it will echo out an error message; the calling code should just return.


    private
                    checkAccess(ManagedAdminController $ctlr, string $access_flag, bool $action) : bool

Parameters

$ctlr : ManagedAdminController: A controller to check
$access_flag : string: The access flag to check, e.g. 'add', 'edit', etc
$action : bool: True if it's an action method, false if it's a form method.

Return values

bool —

True if auth is okay, false if it is not.

cleanupCommonPostData()

Ensure 'active' flag and 'tags' POST fields have values set, if they are nonexistant


    private
                    cleanupCommonPostData(ManagedAdminController $ctlr) : mixed

Parameters

$ctlr : ManagedAdminController

error()

Shows an error message in the admin skin


    private
                    error(string $message[, ManagedAdminController $ctlr = null ]) : mixed

Parameters

$message : string: The message to show. Should be plain-text.
$ctlr : ManagedAdminController = null: A controller to show the navigation of.

lock()

Does lock checking, locking, or lock messages.


    private
                    lock(string $type, int $id, BaseView $view) : mixed

Parameters

$type : string: Admin controller slug, e.g. 'page'
$id : int: Record id which is being edited
$view : BaseView: Main layout view to provide lock details into

renderSubActions()

Render a list of sub-actions into HTML as links


    private
                    renderSubActions(array<string|int, mixed> $list) : string

Each sub-action should be an array, with the following keys: url Link URL name Link text class Optional class new_tab Optional bool to show in new window/tab

Use a special entry with a key of "_preview" and a value of the preview URL to set up a preview button

Parameters

$list : array<string|int, mixed>: Sub-actions to render

Return values

string —

HTML

setDefaultMainviewParams()

Sets the a bunch of parameters for a the main view.


    private
                    setDefaultMainviewParams(BaseView $view) : mixed

Parameters

$view : BaseView: The view to set the parameters for.

setNavigation()

Sets up the sidebar navigation for a view to show the navigation for a specific controller.


    private
                    setNavigation(BaseView $view, ManagedAdminController $ctlr) : mixed

Parameters

$view : BaseView: The view to set the navigation parameters for.
$ctlr : ManagedAdminController: The controller to use for navigation (and searching if supported).

unlock()

Unlocks lock for a given record/controller, all records for a controller, or all locks


    private
                    unlock([mixed $type = null ][, mixed $id = null ]) : mixed

Parameters

$type : mixed = null
$id : mixed = null

AdminController extends Controller in package Application

Table of Contents

Constants

Properties

Methods

Constants

ALLOW_PRODUCTION

Properties

$action_log

Methods

__call()

Parameters

Tags

__construct()

_run()

Parameters

Tags

add()

Parameters

addSave()

Parameters

aiReprocess()

Parameters

aiReprocessAction()

Parameters

ajaxUnlock()

call()

Parameters

Return values

checkRecordAccess()

Parameters

Return values

closeFirstrun()

Return values

contents()

Parameters

cronGenericActivate()

dashboard()

delete()

Parameters

deleteSave()

Parameters

duplicate()

Parameters

duplicateSave()

Parameters

edit()

Parameters

editSave()

Parameters

emailReportAction()

Parameters

emailReportAdd()

Parameters

emailReports()

Parameters

emailReportSend()

Parameters

export()

Parameters

exportAction()

Parameters

extra()

Parameters

Tags

Return values

getAbsModulePath()

Return values

getCssClassName()

Return values

getModule()

Return values

getModulePath()

Return values

heartbeat()

importAction()

Parameters

importOptions()

Parameters

importUpload()

AdminController extends Controller
in package

Application