Documentation

MultiStepFormController extends Controller
in package

Application

AbstractYes

Supports multistep forms

Constants

ALLOW_PRODUCTION : mixed = TRUE

Properties

$action_log : mixed: Should this controller log add/edit/delete actions?
$complete_function : mixed: Appendage to route, where user is redirected after save on final step
$page_title : mixed: Page title to be displayed on form steps
$route : mixed: Route to form, relative to site root
$session_key : mixed: Key for partitioning session data associated with this form, i.e. $_SESSION[$this->session_key]
$steps : mixed: Steps and functions/views used to implement them Keys are step numbers, values are function (and matching view) names e.g. [1 => 'intro', 2 => 'personal_details']
$table : mixed: Table into which data will be saved at the final step
$view_dir : mixed: Directory in which views are stored, without trailing slash
$view_type : mixed: What types of templates live in the view_dir?

Methods

__call() : void: Handles methods that do not exist.
__construct() : void
_run() : mixed: The router/kohana will invoke this method to invoke an action.
complete() : void: Display the thanks message after the process has been completed
form() : BaseView|void
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.
autoSetEmptyParam() : void: Auto-set the "empty" param for fields with foreign keys to be NULL
buildUrl() : string: Builds a URL to the form at a particular step
checkStep() : void: Check the user has access to a step
createView() : BaseView: Create a skin view for this form.
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
firstStep() : int: Gets the number (should be 0 or 1) of first step of the process
generateFormView() : PhpView: Generates a form view from a JSON config file
getForm() : BaseView: The method used to drive the forms at each step This should be called by the entry function of the subclass controller
getSession() : array<string|int, mixed>: Instantiate the session and make sure the session key is useable
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
save() : mixed: Do any final preparation / data massaging; then call saveData and finally redirect.
saveData() : int|null: Save the data, e.g. into a database, after successful validation at the final step
saveJsonData() : bool: Automatically saves the data associated with a submission on a JSON-generated form
submit() : void: The method used to drive the form submissions at each step This should be called by the submit function of the subclass controller
validate() : void

ALLOW_PRODUCTION


    public
        mixed
    ALLOW_PRODUCTION
    = TRUE

$action_log

Should this controller log add/edit/delete actions?


        protected
            mixed
    $action_log
     = false

$complete_function

Appendage to route, where user is redirected after save on final step


        protected
            mixed
    $complete_function
     = 'complete'

$page_title

Page title to be displayed on form steps


        protected
            mixed
    $page_title
     = 'Form'

$route

Route to form, relative to site root


        protected
            mixed
    $route
     = 'multistep'

$session_key

Key for partitioning session data associated with this form, i.e. $_SESSION[$this->session_key]


        protected
            mixed
    $session_key
     = 'DUMMY'

$steps

Steps and functions/views used to implement them Keys are step numbers, values are function (and matching view) names e.g. [1 => 'intro', 2 => 'personal_details']


        protected
            mixed
    $steps
     = []

$table

Table into which data will be saved at the final step


        protected
            mixed
    $table
     = ''

$view_dir

Directory in which views are stored, without trailing slash


        protected
            mixed
    $view_dir
     = ''

$view_type

What types of templates live in the view_dir?


        protected
            mixed
    $view_type
     = 'php'

Note, this only applies to templates within modules/. Skin templates will respect sprout.skin_views_type.

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


    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

complete()

Display the thanks message after the process has been completed


    public
                    complete() : void

form()


    public
                    form([int $step = -1 ]) : BaseView|void

Use getForm() instead.

Parameters

$step : int = -1

Return values

BaseView|void

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'

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

buildUrl()

Builds a URL to the form at a particular step


    protected
                    buildUrl(int $step[, bool $include_first = false ]) : string

Parameters

$step : int
$include_first : bool = false: Include /0 or /1 ending for the first step

Return values

string —

the URL

checkStep()

Check the user has access to a step


    protected
                    checkStep(mixed $session, mixed $step) : void

Parameters

$session : mixed
$step : mixed

Return values

void —

A redirect is performed if the user isn't ready for the step

createView()

Create a skin view for this form.


    protected
                    createView(string $name) : BaseView

This is somewhat specialised because the view_dir could be a skin directory which needs to respect the sprout.skin_views_type config.

Or it could be a modules folder that contains either php OR twig files. This is indicated by the view_type property.

Parameters

$name : string

Return values

BaseView

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)

firstStep()

Gets the number (should be 0 or 1) of first step of the process


    protected
                    firstStep() : int

Return values

int —

Usually 0 or 1, although in theory step 1000 can be the first step if so desired

generateFormView()

Generates a form view from a JSON config file


    protected
                    generateFormView(mixed $file_name) : PhpView

Parameters

$file_name : mixed

Return values

PhpView

getForm()

The method used to drive the forms at each step This should be called by the entry function of the subclass controller


    protected
                    getForm([int $step = -1 ]) : BaseView

Parameters

$step : int = -1: The current step

Return values

BaseView —

The view containing the form for that step

getSession()

Instantiate the session and make sure the session key is useable


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

Return values

array<string|int, mixed>

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

save()

Do any final preparation / data massaging; then call saveData and finally redirect.


    protected
                    save() : mixed

This should generally be overridden.

saveData()

Save the data, e.g. into a database, after successful validation at the final step


    protected
                    saveData(string $table[, array<string|int, mixed> $sub_tables = array() ][, array<string|int, mixed> $extra_fields = array() ]) : int|null

Parameters

$table : string: The table to save the data in, e.g. 'members'
$sub_tables : array<string|int, mixed> = array(): The subtables which should be used. The keys must match those used in the $session['data'] array. Each of the values is itself an array with one element. The 0-th value is the subtable to save the data in, and the 1st value is the column in that table which links to the core table, e.g. ['preferences' => ['member_prefs', 'member_id']]
$extra_fields : array<string|int, mixed> = array(): Extra field values which should be set before performing the inserts. The keys are the table names, and each value is an array of column name to value mappings, e.g. ['members' => ['date_added' => Pdb::now(), ...]]

Return values

int|null —

The insert id from the newly created record, or null if no table is specified

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

submit()

The method used to drive the form submissions at each step This should be called by the submit function of the subclass controller


    protected
                    submit(int $step) : void

Parameters

$step : int: The current step

Return values

void —

On the final step, the save() method is called. On earlier steps, the user is redirected to the form for the next step.

validate()


    protected
                    validate(int $step, array<string|int, mixed> $reqd, array<string|int, mixed> $rules[, Validator|null $valid = null ]) : void

Parameters

$step : int
$reqd : array<string|int, mixed>: Names of required fields, e.g. ['name', 'email']
$rules : array<string|int, mixed>: Each element is an array which is passed to Validator::check, e.g. [['first_name', 'Validity::length', 0, 20], ['last_name', 'Validity::length', 0, 20]]
$valid : Validator|null = null: A Validator, or null to create one on the fly. Specifying a Validator allows the addition of rules/errors before this method is called.

Return values

void —

A redirect will occur if validation fails

MultiStepFormController extends Controller in package Application

Table of Contents

Constants

Properties

Methods

Constants

ALLOW_PRODUCTION

Properties

$action_log

$complete_function

$page_title

$route

$session_key

$steps

$table

$view_dir

$view_type

Methods

__call()

Parameters

Tags

__construct()

_run()

Parameters

Tags

complete()

form()

Parameters

Return values

getAbsModulePath()

Return values

getCssClassName()

Return values

getModule()

Return values

getModulePath()

Return values

autoSetEmptyParam()

Parameters

Return values

buildUrl()

Parameters

Return values

checkStep()

Parameters

Return values

createView()

Parameters

Tags

Return values

deleteRecord()

Parameters

Tags

Return values

firstStep()

Return values

generateFormView()

Parameters

Tags

Return values

getForm()

Parameters

Return values

getSession()

Return values

jsonExtraValidate()

Parameters

loadEditJson()

Tags

Return values

loadFormJson()

Parameters

Tags

Return values

loadRecord()

Parameters

Tags

Return values

logAction()

Parameters

MultiStepFormController extends Controller
in package

Application