Documentation

HasCategoriesAdminController extends ManagedAdminController
in package

Application

AbstractYes

An abstract class for controllers of things which have categories.

Constants

ALLOW_PRODUCTION : mixed = TRUE

Properties

$action_log : bool: Should this controller log add/edit/delete actions?
$add_defaults : array<string, mixed>: Default values used for adding a record.
$category_archive : mixed: Do we have the 'archive' feature for categories? You will need a "show_admin TINYINT UNSIGNED DEFAULT 1" column on the category table.
$category_reorder : mixed: Enables re-ordering for categories.
$category_single : mixed: Enables single-cat mode.
$controller_name : string: This is the shorthand name of the controller.
$db : mixed
$duplicate_defaults : array<string, mixed>: Default values used for duplicating a record.
$duplicate_enabled : bool: Flag to turn duplication on or off
$duplicate_omit_table_joints : array<string|int, string>: Any tables / multiedits to have data emptied before duplicated.
$email_reports : bool: Is this controller enabled for automated email report sending?
$export_modifiers : array<string, ColModifier|ColModifier>|false>: Modifiers applied to data prior to export Should be a class which extends ColModifier Can be an object instance or string of a class name
$friendly_name : string: This is the friendly name of the controller.
$import_duplicates : string: The default selection for the "duplicates" option Values are "new", "merge", "merge_blank" and "skip".
$import_headings : array<string|int, mixed>|null: If a client is providing CSVs which don't have headings You'll need to provide them in this array
$import_id_column : bool: Typically, we don't want to import the ID, and just let autoinc do it's thing
$main_actions : array<string|int, mixed>: Actions for the itemlist
$main_add : bool: Should a link be shown above the list for adding records? (default yes)
$main_columns : array<string, string|ColModifier, 1: string}>: The columns to use for the main view
$main_delete : bool: Is deletion allowed, with an option shown in the UI? (default: no)
$main_modes : array<string|int, mixed>: Different modes available for the main view By default, there is only one mode: list
$main_order : string: Order of main view records
$main_where : array<string|int, mixed>: An additional where clause for the main view
$navigation_name : string: The friendly name used in the sidebar navigation.
$per_subsite : bool: Should a UI for editing the "subsite_id" field on a record be shown? If enabled by extending classes, then the table should contain a 'subsite_id' INT UNSIGNED column
$records_per_page : int: The default number of records to show per page
$refine_bar : RefineBar: Defines the widgets for the refine bar
$table_name : string: This is the name of the table to get data from.

Methods

__call() : void: Handles methods that do not exist.
__construct() : void: Constructor
_actionLog() : bool: Function to determine if we log admin actions for this controller
_addEmailReport() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns form for creating email reports
_addSave() : bool|string: Process the saving of an add.
_aiReprocessData() : bool: Perform AI reprocessing and enqueue new requests.
_contentsItemlistPreRender() : void: Makes modifications to a list of items for the contents view before they are rendered.
_deletePostSave() : void: Does custom actions after the _deleteSave method is called, e.g. clearing cache
_deletePreSave() : void: Does custom actions before _deleteSave method is called, e.g. extra security checks
_deleteSave() : bool|string: Deletes an item and logs the deleted data
_duplicateSave() : bool: Process the saving of a duplication. Basic version just calls _editSave
_editSave() : bool|string: Process the saving of a record.
_emailReports() : bool: Function to determine if we allow email reports to be created
_exportData() : false|array{type: string, filename: string, data: string}: Does the actual export. Return false on error.
_extraMultiCategorise() : mixed: Form to change the categories for a number of records
_extraMultiDelete() : mixed: Form to delete multiple records
_getAddForm() : array<string|int, mixed>: Returns a page title and HTML for a form to add a record
_getAddSubActions() : array<string, string|array{url: string, name: string, class?: string, new_tab?: bool}>: Return the sub-actions for adding a record (e.g. preview) These are rendered into HTML using {@see AdminController::renderSubActions}
_getAiReprocess() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns form for doing AI bulk content reprocessing
_getContentPermissionGroups() : array<string|int, bool>: Get the permission groups for this controller.
_getContents() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns the main list of records for this controller
_getContentsView() : string: Return HTML for a resultset of items The returned HTML will be sandwiched between the refinebar and the pagination bar.
_getContentsViewList() : string: Formats a resultset of items into an Itemlist
_getCustomAddSaveHTML() : string|null: Optional custom HTML for the save box Return NULL to use the default HTML
_getCustomDuplicateSaveHTML() : string: Optional custom HTML for the save box Return NULL to use the default HTML
_getCustomEditSaveHTML() : string|null: Optional custom HTML for the save box Return NULL to use the default HTML
_getDeleteForm() : string|array<string|int, mixed>|AdminError: Return HTML which represents the form for deleting a record
_getDeleteSubActions() : array<string|int, mixed>: Return the sub-actions for deleting a record (e.g. cancel) These are rendered into HTML using {@see AdminController::renderSubActions}
_getDuplicateForm() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns the edit form for duplicating a record
_getDuplicateSubActions() : array<string|int, mixed>: Return the sub-actions for duplicating a record These are rendered into HTML using {@see AdminController::renderSubActions}
_getEditForm() : array{title: string, content: string}|AdminError: Returns the edit form for adding a record
_getEditLiveUrl() : string|null: Return the URL to use for the 'view live site' button, when editing a given record
_getEditSubActions() : array<string, string|array{url: string, name: string, class?: string, new_tab?: bool}>: Return the sub-actions for editing a record (e.g. deleting) These are rendered into HTML using {@see AdminController::renderSubActions}
_getEmailReports() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns a list of email reports
_getExport() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns form for doing exports
_getImport() : array<string|int, mixed>|string|BaseView|AdminError|null: Returns a form which contains options for doing an export
_getNavigation() : string|null: Returns the contents of the navigation pane
_getSearchForm() : array<string|int, mixed>|string|BaseView|AdminError|null: Return HTML for a search form
_getSelectedTools() : array<string|int, mixed>: Generate list of tools for selected admin records
_getTools() : array<string|int, string>: Additional categry tools
_getVisibilityFields() : array<string, string>: Return the fields to show in the sidebar when adding or editing a record.
_identifier() : string: Creates the identifier used in the heading, and for reordering.
_importData() : bool: Does the actual import
_intro() : array<string|int, mixed>|string|BaseView: Returns the intro HTML for this controller.
_invalidateCaches() : void: This is called after every add, edit and delete, as well as other (i.e. bulk) actions.
_isAddSaved() : bool: Is the "add" action saved? These may be false if the UI provides its own save mechanism (e.g. multi-add)
_isDeleteSaved() : bool: Check if deletion of a particular record is allowed This method may be overridden if ignoring the $main_delete property is desired
_isEditSaved() : bool: Is the "edit" action saved? These may be false if the UI provides its own save mechanism
_run() : mixed: The router/kohana will invoke this method to invoke an action.
_sendEmailReport() : bool: Send an email report, using its DB record
ajaxLookup() : void: Return list of records for given search term Used for Fb::autocomplete
ajaxLookupList() : void: Return list of records for given search term Used for Fb::autocompleteList
catAllowAdd() : mixed: Return true if categories are allowed to be added.
catAllowDelete() : mixed: Return true if categories are allowed to be deleted.
catAllowEdit() : mixed: Return true if categories are allowed to be edited.
getAbsModulePath() : string: Get the absolute path of the current module for this controller.
getCategoryArchive() : mixed: Returns TRUE if category archive is enabled, FALSE otherwise
getControllerName() : string: Get the controller shortname.
getCssClassName() : string: Return the class name for this controller, expressed in CSS style, i.e. with dashes
getDuplicateEnabled() : bool: Returns the duplication enabling flag
getFriendlyName() : string: Get the controller friendly name.
getModule() : ModuleInterface|null: Get the module that this controller belongs to.
getModulePath() : string: Get the a prefix suitable for finding views for this controller.
getNavigationName() : string: Get the controller navigation name.
getTableName() : string: Returns the defined table name
getTopnavName() : string: Gets the name of the controller to use for the top nav
isPerSubsite() : bool: If true, then a UI for editing the "subsite_id" for a record should be shown
postJsonMultiTag() : never: Multi-tag some items. Uses AJAX. Returns JSON.
postMultiCategorise() : mixed: Change the categories for a number of records
postMultiDelete() : never: Delete multiple records
_addPreRender() : void: Hook called by _getAddForm() just before the view is rendered
_buildManualAiPrompt() : string: Perform string replacements on prompt text, inserting raw data as needed.
_duplicatePreRender() : mixed: Hook called by _getDuplicateForm() just before the view is rendered
_editPreRender() : void: Hook called by _getEditForm() just before the view is rendered
_getAiDataQuery() : string: Returns the SQL query for use by ai automation tools.
_getContentsQuery() : string: Returns the SQL query for use by the contents list.
_getExportQuery() : string: Returns the SQL query for use by the export tools.
_getRecord() : array<string|int, mixed>: Fetch the record with a given id
_getRefineClause() : string: Return the WHERE clause to use for a given key which is provided by the RefineBar
_importAiOptions() : string|null: Called when the import form is being built.
_importColGuess() : string|null: Try to guess the database name for a given CSV heading.
_importExtraOptions() : mixed: Called when the import form is being built.
_importPost() : mixed: Called at the end of the the import process, after everything has been done.
_importPostAi() : array<string|int, mixed>|bool: Called at the end of the the import process, after everything has been done.
_importPostRecord() : bool: Called after a record has been inserted or updated.
_importPostRecordAi() : bool: Called after a record has been inserted or updated.
_importPre() : mixed: Called at the beginning of the the import process.
_importPreRecord() : mixed: Called after the field data has been determined, but before the insert or update is run.
_modeSelector() : string: Returns HTML for a ui component to update the current main view mode
_paginationBar() : string: Builds the HTML for showing the navigation through pages in the admin.
_preSave() : void: Hook called by _addSave() just before the record is saved
applyRefineFilter() : array<string|int, mixed>: Applies filters defined in the query string using a LIKE contains Only fields which exist in the RefineBar will be filtered
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
initRefineBar() : void: Initialises the refine bar if it isn't already set, with a search widget for the 'name' field if it exists Most controllers which need a custom refine bar should call this before adding their own search widgets
initTableName() : void: Initialises the table name if it isn't already set, using the plural of the shorthand controller name
injectVisiblityFields() : void: Inject the visiblity fields into a loaded json configuration, so they actually save
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}
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
updateCategories() : bool: Updates the category table for this controller (so for articles, the updated table will be articles_cat_join) so that the records for the specified item match the category ids provided.

ALLOW_PRODUCTION


    public
        mixed
    ALLOW_PRODUCTION
    = TRUE

$action_log

Should this controller log add/edit/delete actions?


        protected
            bool
    $action_log
     = true

$add_defaults

Default values used for adding a record.


        protected
            array<string, mixed>
    $add_defaults
     = array()

$category_archive

Do we have the 'archive' feature for categories? You will need a "show_admin TINYINT UNSIGNED DEFAULT 1" column on the category table.


        protected
            mixed
    $category_archive
     = false

$category_reorder

Enables re-ordering for categories.


        protected
            mixed
    $category_reorder
     = false

You will need a "record_order" column on the category table.

$category_single

Enables single-cat mode.


        protected
            mixed
    $category_single
     = false

This uses radiobuttons instead of checkboxes in the category selection UI.

$controller_name

This is the shorthand name of the controller.


        protected
            string
    $controller_name

DO NOT declare this in the extending class. This is derived from the shortname used to register the controller.

$db


        protected
            mixed
    $db

$duplicate_defaults

Default values used for duplicating a record.


        protected
            array<string, mixed>
    $duplicate_defaults
     = array('name' => '')

$duplicate_enabled

Flag to turn duplication on or off


        protected
            bool
    $duplicate_enabled
     = false

$duplicate_omit_table_joints

Any tables / multiedits to have data emptied before duplicated.


        protected
            array<string|int, string>
    $duplicate_omit_table_joints
     = array()

e.g. "operator_cat_join"

$email_reports

Is this controller enabled for automated email report sending?


        protected
            bool
    $email_reports
     = true

$export_modifiers

Modifiers applied to data prior to export Should be a class which extends ColModifier Can be an object instance or string of a class name


        protected
            array<string, ColModifier|ColModifier>|false>
    $export_modifiers
     = array()

$friendly_name

This is the friendly name of the controller.


        protected
            string
    $friendly_name

In 99% of cases, should be the plural form of the controller name.

If this is not set, this is extracted from the class name.

$import_duplicates

The default selection for the "duplicates" option Values are "new", "merge", "merge_blank" and "skip".


        protected
            string
    $import_duplicates
     = ''

$import_headings

If a client is providing CSVs which don't have headings You'll need to provide them in this array


        protected
            array<string|int, mixed>|null
    $import_headings
     = null

$import_id_column

Typically, we don't want to import the ID, and just let autoinc do it's thing


        protected
            bool
    $import_id_column
     = false

$main_actions

Actions for the itemlist


        protected
            array<string|int, mixed>
    $main_actions
     = array()

$main_add

Should a link be shown above the list for adding records? (default yes)


        protected
            bool
    $main_add
     = true

$main_columns

The columns to use for the main view


        protected
            array<string, string|ColModifier, 1: string}>
    $main_columns

$main_delete

Is deletion allowed, with an option shown in the UI? (default: no)


        protected
            bool
    $main_delete
     = false

$main_modes

Different modes available for the main view By default, there is only one mode: list


        protected
            array<string|int, mixed>
    $main_modes
     = array()

$main_order

Order of main view records


        protected
            string
    $main_order
     = 'item.name'

$main_where

An additional where clause for the main view


        protected
            array<string|int, mixed>
    $main_where
     = array()

$navigation_name

The friendly name used in the sidebar navigation.


        protected
            string
    $navigation_name

Defaults to matching the friendly name.

$per_subsite

Should a UI for editing the "subsite_id" field on a record be shown? If enabled by extending classes, then the table should contain a 'subsite_id' INT UNSIGNED column


        protected
            bool
    $per_subsite
     = false

$records_per_page

The default number of records to show per page


        protected
            int
    $records_per_page
     = 50

$refine_bar

Defines the widgets for the refine bar


        protected
            RefineBar
    $refine_bar

$table_name

This is the name of the table to get data from.


        protected
            string
    $table_name

Will be automatically inferred from the controller name if not specified.

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

Constructor


    public
                    __construct() : void

_actionLog()

Function to determine if we log admin actions for this controller


    public
                    _actionLog() : bool

Return values

bool

_addEmailReport()

Returns form for creating email reports


    public
                    _addEmailReport() : array<string|int, mixed>|string|BaseView|AdminError|null

Return values

_addSave()

Process the saving of an add.


    public
                    _addSave(int &$item_id) : bool|string

Parameters

$item_id : int: The new record id should be returned in this variable

Return values

bool|string —

True on success, false on failure, or a redirect URL

_aiReprocessData()

Perform AI reprocessing and enqueue new requests.


    public
                    _aiReprocessData() : bool

Return values

bool

_contentsItemlistPreRender()

Makes modifications to a list of items for the contents view before they are rendered.


    public
                    _contentsItemlistPreRender(Itemlist $itemlist) : void

E.g. adding action buttons via Itemlist::setActionsFunc()

Parameters

$itemlist : Itemlist

_deletePostSave()

Does custom actions after the _deleteSave method is called, e.g. clearing cache


    public
                    _deletePostSave(int $item_id) : void

Parameters

$item_id : int: The record to delete

_deletePreSave()

Does custom actions before _deleteSave method is called, e.g. extra security checks


    public
                    _deletePreSave(int $item_id) : void

Parameters

$item_id : int: The record to delete

_deleteSave()

Deletes an item and logs the deleted data


    public
                    _deleteSave(int $item_id) : bool|string

This method should not be overridden unless absolutely necessary.

Parameters

$item_id : int: The record to delete

Return values

bool|string —

True on success, false on failure, or a redirect URL

_duplicateSave()

Process the saving of a duplication. Basic version just calls _editSave


    public
                    _duplicateSave(int $id) : bool

Parameters

$id : int: The record to save

Return values

bool —

True on success, false on failure

_editSave()

Process the saving of a record.


    public
                    _editSave(int $item_id) : bool|string

Parameters

$item_id : int: The ID of the record to save the data into

Return values

bool|string —

True on success, false on failure, or a redirect URL

_emailReports()

Function to determine if we allow email reports to be created


    public
                    _emailReports() : bool

Return values

bool

_exportData()

Does the actual export. Return false on error.


    public
                    _exportData() : false|array{type: string, filename: string, data: string}

Return values

false|array{type: string, filename: string, data: string} —

type - the content type
filename - filename
data - the data itself

_extraMultiCategorise()

Form to change the categories for a number of records


    public
                    _extraMultiCategorise() : mixed

_extraMultiDelete()

Form to delete multiple records


    public
                    _extraMultiDelete() : mixed

_getAddForm()

Returns a page title and HTML for a form to add a record


    public
                    _getAddForm() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Two elements: 'title' and 'content'

_getAddSubActions()

Return the sub-actions for adding a record (e.g. preview) These are rendered into HTML using {@see AdminController::renderSubActions}


    public
                    _getAddSubActions() : array<string, string|array{url: string, name: string, class?: string, new_tab?: bool}>

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

Return values

array<string, string|array{url: string, name: string, class?: string, new_tab?: bool}>

_getAiReprocess()

Returns form for doing AI bulk content reprocessing


    public
                    _getAiReprocess() : array<string|int, mixed>|string|BaseView|AdminError|null

Return values

_getContentPermissionGroups()

Get the permission groups for this controller.


    public
            static        _getContentPermissionGroups() : array<string|int, bool>

This determines the controller will appear in either:

record: 'Per-record permissions'
operator_category: 'Per-tab permissions'

Return values

array<string|int, bool> —

[ record, operator_category ]

_getContents()

Returns the main list of records for this controller


    public
                    _getContents() : array<string|int, mixed>|string|BaseView|AdminError|null

Return values

_getContentsView()

Return HTML for a resultset of items The returned HTML will be sandwiched between the refinebar and the pagination bar.


    public
                    _getContentsView(array<string|int, mixed>|Traversable $items, string $mode, stdClass|null $category) : string

Parameters

$items : array<string|int, mixed>|Traversable: The items to render.
$mode : string: The mode of the display.
$category : stdClass|null: Category details if a category has been selected.

Return values

string —

HTML

_getContentsViewList()

Formats a resultset of items into an Itemlist


    public
                    _getContentsViewList(array<string|int, mixed>|Traversable $items, stdClass|null $category) : string

Parameters

$items : array<string|int, mixed>|Traversable: The items to render.
$category : stdClass|null: Category details if a category has been selected.

Return values

string —

HTML

_getCustomAddSaveHTML()

Optional custom HTML for the save box Return NULL to use the default HTML


    public
                    _getCustomAddSaveHTML() : string|null

Return values

string|null —

HTML

_getCustomDuplicateSaveHTML()

Optional custom HTML for the save box Return NULL to use the default HTML


    public
                    _getCustomDuplicateSaveHTML(int $item_id) : string

Parameters

$item_id : int: The row ID of the record being duplicated

Return values

string —

HTML

_getCustomEditSaveHTML()

Optional custom HTML for the save box Return NULL to use the default HTML


    public
                    _getCustomEditSaveHTML(int $item_id) : string|null

Parameters

$item_id : int: Record which is being edited

Return values

string|null —

HTML

_getDeleteForm()

Return HTML which represents the form for deleting a record


    public
                    _getDeleteForm(int $id) : string|array<string|int, mixed>|AdminError

Parameters

$id : int: The record to show the delete form for

Return values

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

The HTML code which represents the edit form

_getDeleteSubActions()

Return the sub-actions for deleting a record (e.g. cancel) These are rendered into HTML using {@see AdminController::renderSubActions}


    public
                    _getDeleteSubActions(int $item_id) : array<string|int, mixed>

Parameters

$item_id : int: The ID of the target record row

Return values

array<string|int, mixed>

_getDuplicateForm()

Returns the edit form for duplicating a record


    public
                    _getDuplicateForm(int $id) : array<string|int, mixed>|string|BaseView|AdminError|null

Parameters

$id : int: The id of the record to get the data from

Return values

_getDuplicateSubActions()

Return the sub-actions for duplicating a record These are rendered into HTML using {@see AdminController::renderSubActions}


    public
                    _getDuplicateSubActions(int $item_id) : array<string|int, mixed>

Parameters

$item_id : int: The row ID of the record being duplicated

Return values

array<string|int, mixed>

_getEditForm()

Returns the edit form for adding a record


    public
                    _getEditForm(int $id) : array{title: string, content: string}|AdminError

Parameters

$id : int: The id of the record to get the edit form of

Return values

array{title: string, content: string}|AdminError

_getEditLiveUrl()

Return the URL to use for the 'view live site' button, when editing a given record


    public
                    _getEditLiveUrl(int $item_id) : string|null

Parameters

$item_id : int: Record which is being edited

Return values

string|null —

URL, either absolute or relative. null if default url should be used

_getEditSubActions()

Return the sub-actions for editing a record (e.g. deleting) These are rendered into HTML using {@see AdminController::renderSubActions}


    public
                    _getEditSubActions(int $item_id) : array<string, string|array{url: string, name: string, class?: string, new_tab?: bool}>

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

Parameters

$item_id : int

Return values

array<string, string|array{url: string, name: string, class?: string, new_tab?: bool}> —

Each key is a unique reference to the action, e.g. 'delete', and the value is an array, with keys: url => URL to link to, e.g. "admin/delete/thing/$item_id" name => Label to display to the user, e.g. 'Delete' class => CSS class(es) for the icon, e.g. 'icon-link-button icon-before icon-delete' new_tab => True to show in new window/tab (optional; defaults to false)

_getEmailReports()

Returns a list of email reports


    public
                    _getEmailReports() : array<string|int, mixed>|string|BaseView|AdminError|null

Return values

_getExport()

Returns form for doing exports


    public
                    _getExport() : array<string|int, mixed>|string|BaseView|AdminError|null

Return values

_getImport()

Returns a form which contains options for doing an export


    public
                    _getImport(string $filename) : array<string|int, mixed>|string|BaseView|AdminError|null

Parameters

$filename : string

Return values

_getNavigation()

Returns the contents of the navigation pane


    public
                    _getNavigation() : string|null

Return values

string|null —

HTML

_getSearchForm()

Return HTML for a search form


    public
                    _getSearchForm() : array<string|int, mixed>|string|BaseView|AdminError|null

Return values

_getSelectedTools()

Generate list of tools for selected admin records


    public
                    _getSelectedTools() : array<string|int, mixed>

Return values

array<string|int, mixed> —

[[ url => (string) button url class => (string) button class label => (string) button label ]]

_getTools()

Additional categry tools


    public
                    _getTools() : array<string|int, string>

Return values

array<string|int, string> —

(<identifier or autonumeric key, HTML with LI containing A>)

_getVisibilityFields()

Return the fields to show in the sidebar when adding or editing a record.


    public
                    _getVisibilityFields() : array<string, string>

These fields are shown under a heading of "Visibility"

Key is the field name, value is the field label

Return values

array<string, string>

_identifier()

Creates the identifier used in the heading, and for reordering.


    public
                    _identifier(array<string, mixed> $item) : string

Parameters

$item : array<string, mixed>: The row being viewed/edited/etc.

Return values

string

_importData()

Does the actual import


    public
                    _importData(string $filename) : bool

Parameters

$filename : string: The location of the import data, in a temporary directory

Return values

bool

_intro()

Returns the intro HTML for this controller.


    public
                    _intro() : array<string|int, mixed>|string|BaseView

Return values

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

_invalidateCaches()

This is called after every add, edit and delete, as well as other (i.e. bulk) actions.


    public
                    _invalidateCaches(string $action[, int $item_id = null ]) : void

Use it to clear any frontend caches. The default is an empty method.

Parameters

$action : string: The name of the action (e.g. 'add', 'edit', 'delete', etc)
$item_id : int = null: The item which was affected. Bulk actions (e.g. reorders) will have this set to NULL.

_isAddSaved()

Is the "add" action saved? These may be false if the UI provides its own save mechanism (e.g. multi-add)


    public
                    _isAddSaved() : bool

Return values

bool —

True if they are saved, false if they are not

_isDeleteSaved()

Check if deletion of a particular record is allowed This method may be overridden if ignoring the $main_delete property is desired


    public
                    _isDeleteSaved(int $item_id) : bool

Parameters

$item_id : int: The ID of the target record row

Return values

bool —

True if they are saved, false if they are not

_isEditSaved()

Is the "edit" action saved? These may be false if the UI provides its own save mechanism


    public
                    _isEditSaved(mixed $item_id) : bool

Parameters

$item_id : mixed

Return values

bool —

True if they are saved, false if they are not

_run()

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


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

Parameters

$method : mixed
$args : mixed

_sendEmailReport()

Send an email report, using its DB record


    public
                    _sendEmailReport(array<string|int, mixed> $report) : bool

Parameters

$report : array<string|int, mixed>

Return values

bool —

Email send success

ajaxLookup()

Return list of records for given search term Used for Fb::autocomplete


    public
                    ajaxLookup() : void

Return values

void —

Echos JSON directly

ajaxLookupList()

Return list of records for given search term Used for Fb::autocompleteList


    public
                    ajaxLookupList() : void

Return values

void —

Echos JSON directly

catAllowAdd()

Return true if categories are allowed to be added.


    public
                    catAllowAdd() : mixed

catAllowDelete()

Return true if categories are allowed to be deleted.


    public
                    catAllowDelete(mixed $category_id) : mixed

Parameters

$category_id : mixed

catAllowEdit()

Return true if categories are allowed to be edited.


    public
                    catAllowEdit(mixed $category_id) : mixed

Parameters

$category_id : mixed

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

getCategoryArchive()

Returns TRUE if category archive is enabled, FALSE otherwise


    public
        final            getCategoryArchive() : mixed

getControllerName()

Get the controller shortname.


    public
        final            getControllerName() : string

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

getDuplicateEnabled()

Returns the duplication enabling flag


    public
        final            getDuplicateEnabled() : bool

Return values

bool

getFriendlyName()

Get the controller friendly name.


    public
        final            getFriendlyName() : string

Return values

string

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'

getNavigationName()

Get the controller navigation name.


    public
        final            getNavigationName() : string

Return values

string

getTableName()

Returns the defined table name


    public
        final            getTableName() : string

Return values

string

getTopnavName()

Gets the name of the controller to use for the top nav


    public
                    getTopnavName() : string

Return values

string

isPerSubsite()

If true, then a UI for editing the "subsite_id" for a record should be shown


    public
        final            isPerSubsite() : bool

Return values

bool

postJsonMultiTag()

Multi-tag some items. Uses AJAX. Returns JSON.


    public
                    postJsonMultiTag() : never

Return values

never —

echoes JSON directly

postMultiCategorise()

Change the categories for a number of records


    public
                    postMultiCategorise() : mixed

postMultiDelete()

Delete multiple records


    public
                    postMultiDelete() : never

Return values

never —

redirects

_addPreRender()

Hook called by _getAddForm() just before the view is rendered


    protected
                    _addPreRender(BaseView $view) : void

Parameters

$view : BaseView: The view which will be rendered

_buildManualAiPrompt()

Perform string replacements on prompt text, inserting raw data as needed.


    protected
                    _buildManualAiPrompt(string $prompt_text, array<string|int, mixed> $raw_data) : string

We replace content of the form '{{ field_name }}' with the field from raw data.

This may be extended per controller for different or more complex use cases if needed.

Parameters

$prompt_text : string
$raw_data : array<string|int, mixed>

Return values

string

_duplicatePreRender()

Hook called by _getDuplicateForm() just before the view is rendered


    protected
                    _duplicatePreRender(BaseView $view, int $item_id) : mixed

Parameters

$view : BaseView: The view which will be rendered
$item_id : int: The id of the record to get the original data from

_editPreRender()

Hook called by _getEditForm() just before the view is rendered


    protected
                    _editPreRender(BaseView $view, int $item_id) : void

Parameters

$view : BaseView: The view which will be rendered
$item_id : int: The id of the record to get the original data from

_getAiDataQuery()

Returns the SQL query for use by ai automation tools.


    protected
                    _getAiDataQuery([string $where = '1' ]) : string

This wraps the export query by default, so a change there will apply to both However, it allows you to split them for inclusion or amendment of data for AI tooling

The query MUST NOT include a LIMIT clause.

Default generated based on the specified refine options.

Parameters

$where : string = '1': A where clause to use.

Return values

string

_getContentsQuery()

Returns the SQL query for use by the contents list.


    protected
                    _getContentsQuery(string $where, string $order, array<string|int, mixed> &$params) : string

The query MUST NOT include a LIMIT clause. The query MUST include a SQL_CALC_FOUND_ROWS clause. The main table SHOULD be aliased to 'item'.

Parameters

$where : string: A where clause to use. Generated based on the specified refine options.
$order : string: An order clause to use.
$params : array<string|int, mixed>: Params to bind to the query. These will be modified to include per-record permissions

Return values

string —

A SQL query.

_getExportQuery()

Returns the SQL query for use by the export tools.


    protected
                    _getExportQuery([string $where = '1' ]) : string

The query MUST NOT include a LIMIT clause.

Default generated based on the specified refine options.

Parameters

$where : string = '1': A where clause to use.

Return values

string

_getRecord()

Fetch the record with a given id


    protected
                    _getRecord(int $id) : array<string|int, mixed>

Parameters

$id : int: Record to fetch

Return values

array<string|int, mixed> —

Database row

_getRefineClause()

Return the WHERE clause to use for a given key which is provided by the RefineBar


    protected
                    _getRefineClause(string $key, string $val, array<string|int, mixed> &$query_params) : string

Allows custom non-table clauses to be added. Is only called for key names which begin with an underscore. The base table is aliased to 'item'.

Parameters

$key : string: The key name, including underscore
$val : string: The value which is being refined.
$query_params : array<string|int, mixed>: Parameters to add to the query which will use the WHERE clause

Return values

string —

WHERE clause, e.g. "item.name LIKE CONCAT('%', ?, '%')", "item.status IN (?, ?, ?)"

_importAiOptions()

Called when the import form is being built.


    protected
                    _importAiOptions(array<string|int, mixed> $headings, array<string|int, mixed> $db_columns, array<string|int, mixed> $data) : string|null

Returns HTML of extra options to display, or null if no extra options.

Parameters

$headings : array<string|int, mixed>: The headings from the CSV file
$db_columns : array<string|int, mixed>: The columns in the database table
$data : array<string|int, mixed>: Optional form data

Return values

string|null —

HTML of extra options to display, or null if no extra options.

_importColGuess()

Try to guess the database name for a given CSV heading.


    protected
                    _importColGuess(string $csv_heading) : string|null

If you can't figure it out, return NULL. If NULL is returned, the rudimentry almost-exact guesser will be run.

Parameters

$csv_heading : string: The exact heading provided in the CSV file.

Return values

string|null —

The database field name to use. Must exactly match the database field name.

_importExtraOptions()

Called when the import form is being built.


    protected
                    _importExtraOptions() : mixed

Returns HTML of extra options to display, or null if no extra options.

_importPost()

Called at the end of the the import process, after everything has been done.


    protected
                    _importPost() : mixed

Is called from within a transaction. Return FALSE to abort the import.

_importPostAi()

Called at the end of the the import process, after everything has been done.


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

Is called from within a transaction, specifically for AI tasks. Return FALSE to abort the import.

Return values

array<string|int, mixed>|bool —

Array of worker job info if a job was created, false on error, true if nothing to do

_importPostRecord()

Called after a record has been inserted or updated.


    protected
                    _importPostRecord(int $record_id, array<string|int, mixed> $new_data, array<string|int, mixed> $existing_record, string $type, array<string|int, mixed> $raw_data) : bool

Parameters

$record_id : int: The id of the record that was inserted or updated.
$new_data : array<string|int, mixed>: The new data of the record.
$existing_record : array<string|int, mixed>: The old data of the record, which has now been replaced.
$type : string: One of 'insert' or 'update'.
$raw_data : array<string|int, mixed>: Raw CSV data, with original field names.

Return values

bool —

False if any errors are encountered; will cancel the entire import process.

_importPostRecordAi()

Called after a record has been inserted or updated.


    protected
                    _importPostRecordAi(int $record_id, array<string|int, mixed> $new_data, array<string|int, mixed> $existing_record, string $type, array<string|int, mixed> $raw_data, array<string|int, mixed> $ai_config_fields, string $activation) : bool

Some args are unused but are available through the import tool and may be used for custom tools

Each $config_fields entry should look like the following:

[ 'target_col' => 'col_name', 'prompt_source' => 'db_col' or 'manual', 'prompt_col' => 'col_name', // for db_col 'prompt_text' => 'manual text', // for manual 'ai_class' => 'class_name', 'ai_method' => 'method_name' ]

Parameters

$record_id : int: The id of the record that was inserted or updated.
$new_data : array<string|int, mixed>: The new data of the record.
$existing_record : array<string|int, mixed>: The old data of the record, which has now been replaced.
$type : string: One of 'insert' or 'update'
$raw_data : array<string|int, mixed>: Raw CSV line or table row, with original field names.
$ai_config_fields : array<string|int, mixed>: Array of fields for AI post processing. @see generic_import_ai.php
$activation : string: Activation status for the record @see table ai_content_queue::activation_status

Return values

bool —

False if any errors are encountered; will cancel the entire import process.

_importPre()

Called at the beginning of the the import process.


    protected
                    _importPre() : mixed

Is called from within a transaction. Return FALSE to abort the import.

_importPreRecord()

Called after the field data has been determined, but before the insert or update is run.


    protected
                    _importPreRecord(array<string|int, mixed> &$new_data, array<string|int, mixed> $raw_data) : mixed

Return FALSE to skip the record.

Parameters

$new_data : array<string|int, mixed>: The CSV data, with database-mapped names, but before the database quoting has happened. This is a by-reference argument.
$raw_data : array<string|int, mixed>: Raw CSV data, with original field names.

_modeSelector()

Returns HTML for a ui component to update the current main view mode


    protected
        final            _modeSelector(string $current_mode) : string

Parameters

$current_mode : string: The current mode

Return values

string —

HTML

_paginationBar()

Builds the HTML for showing the navigation through pages in the admin.


    protected
        final            _paginationBar(int $current_page, int $total_row_count) : string

This method is FINAL to help keep the user interface consistent.

Parameters

$current_page : int: The current page. 1-based index.
$total_row_count : int: The total number of records in the dataset.

Return values

string —

HTML for the paginate bar.

_preSave()

Hook called by _addSave() just before the record is saved


    protected
                    _preSave(int $id, array<string, mixed> &$data) : void

Parameters

$id : int: The id of the record to save
$data : array<string, mixed>: The data to save

applyRefineFilter()

Applies filters defined in the query string using a LIKE contains Only fields which exist in the RefineBar will be filtered


    protected
                    applyRefineFilter([array<string|int, mixed> $source_data = null ]) : array<string|int, mixed>

Parameters

$source_data : array<string|int, mixed> = null: Source data, e.g. $_GET or $_POST

Return values

array<string|int, mixed> —

Three elements: [0] (array) WHERE clauses, to be joined by the calling code with AND [1] (array) Params to use in a Pdb::q call which uses the generated WHERE clauses [2] (array) Key-value pairs containing filter options extracted from the $_GET data

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

initRefineBar()

Initialises the refine bar if it isn't already set, with a search widget for the 'name' field if it exists Most controllers which need a custom refine bar should call this before adding their own search widgets


    protected
                    initRefineBar() : void

Return values

void —

The new RefineBar is set as $this->refine_bar

initTableName()

Initialises the table name if it isn't already set, using the plural of the shorthand controller name


    protected
                    initTableName() : void

use getTableName()

injectVisiblityFields()

Inject the visiblity fields into a loaded json configuration, so they actually save


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

Parameters

$conf : array<string|int, mixed>: JSON add/edit configuration

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

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

updateCategories()

Updates the category table for this controller (so for articles, the updated table will be articles_cat_join) so that the records for the specified item match the category ids provided.


    protected
                    updateCategories(int $item_id, array<string|int, mixed> $categories) : bool

APIYes

Parameters

$item_id : int: The id of the item to set the categories for
$categories : array<string|int, mixed>: A list of category-ids which the specified item should be associated with

Return values

bool —

True on success, false on failure

HasCategoriesAdminController extends ManagedAdminController in package Application

Table of Contents

Constants

Properties

Methods

Constants

ALLOW_PRODUCTION

Properties

$action_log

$add_defaults

$category_archive

$category_reorder

$category_single

$controller_name

$db

$duplicate_defaults

$duplicate_enabled

$duplicate_omit_table_joints

$email_reports

$export_modifiers

$friendly_name

$import_duplicates

$import_headings

$import_id_column

$main_actions

$main_add

$main_columns

$main_delete

$main_modes

$main_order

$main_where

$navigation_name

Tags

$per_subsite

$records_per_page

$refine_bar

$table_name

Tags

Methods

__call()

Parameters

Tags

__construct()

_actionLog()

Return values

_addEmailReport()

Return values

_addSave()

Parameters

Return values

_aiReprocessData()

Return values

_contentsItemlistPreRender()

Parameters

_deletePostSave()

Parameters

_deletePreSave()

Parameters

Tags

_deleteSave()

Parameters

Return values

_duplicateSave()

Parameters

Return values

_editSave()

Parameters

Return values

_emailReports()

Return values

_exportData()

Return values

_extraMultiCategorise()

_extraMultiDelete()

_getAddForm()

Return values

_getAddSubActions()

Return values

_getAiReprocess()

Return values

HasCategoriesAdminController extends ManagedAdminController
in package

Application