# plugins.core.action.handler

A support class for handler handlers. It is not used directly, rather it is a 'super class' that provides common functionality.

Instances of the class primarily need to provide functions for the following:

local handler = actionManager:addHandler("foobar")
:onChoices(function(choices) ... end)
:onExecute(function(action) ... end)

The choices added to the choices should have the params value set to a table containing the details of the action to execute if the choice is selected.

# API Overview

Constructors - API calls which return an object, typically one that offers API methods

Fields - Variables which can only be accessed from an object returned by a constructor

cached
choices

Methods - API calls which can only be made on an object returned by a constructor

actionId
execute
group
id
label
onActionId
onChoices
onExecute
reset

# API Documentation

# Constructors

# new


Signature	`plugins.core.action.handler.new(id, group, label) -> handler`
Type	Constructor
Description	Creates a new handler with the specified ID.
Parameters	`id` - The unique ID of the action handler. `group` - The group the handler belongs to. `label` - An optional label for the handler (over-riding a supplied i18n value)
Returns	The new action handler instance.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 29

# Fields

# cached


Signature	`plugins.core.action.handler.cached <cp.prop: boolean>`
Type	Field
Description	If set to `true` (the default), any choices created will be cached until [reset] is called.
Notes	None
Source	src/plugins/core/action/manager/handler.lua line 131

# choices


Signature	`plugins.core.action.handler.choices <cp.prop: cp.choices; read-only>`
Type	Field
Description	Provides `cp.choices` instance for the handler. May be watched/monitored/etc.
Notes	None
Source	src/plugins/core/action/manager/handler.lua line 141

# Methods

# actionId


Signature	`plugins.core.action.handler:actionId(action) -> string`
Type	Method
Description	Returns a string that can be used as a unique ID for the action details.
Parameters	None
Returns	None
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 189

# execute


Signature	`plugins.core.action.handler:execute(action) -> boolean`
Type	Method
Description	Executes the action, based on values in the table.
Parameters	`action` - A table of details about the action.
Returns	`true` if the execution succeeded.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 215

# group


Signature	`plugins.core.action.handler:group() -> string`
Type	Method
Description	Returns the group for this handler.
Parameters	None
Returns	Group as string.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 92

# id


Signature	`plugins.core.action.handler:id() -> string`
Type	Method
Description	Returns the ID for this handler.
Parameters	None
Returns	The ID string.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 105

# label


Signature	`plugins.core.action.handler:label() -> string`
Type	Method
Description	Returns the label for this handler.
Parameters	None
Returns	The ID string.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 118

# onActionId


Signature	`plugins.core.action.handler:onActionId(actionFn) -> handler`
Type	Method
Description	Configures a function to handle converting an action to unique ID. The function is passed the `action` table and should return a string.
Parameters	`actionFn` - The function with a signature of `function(action) -> string`
Returns	This action handler.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 78

# onChoices


Signature	`plugins.core.action.handler:onChoices(choicesFn) -> handler`
Type	Method
Description	Adds a callback function which will receive the `cp.choices` instance to add choices to. This will only get called when required - the results will be cached if the cached property is set to `true`.
Parameters	`choicesFn` - The function with the signature of `function(choices) -> nothing`
Returns	This action handler.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 64

# onExecute


Signature	`plugins.core.action.handler:onExecute(executeFn) -> handler`
Type	Method
Description	Configures the function to call when a choice is executed. This will be passed the choice parameters in a single table.
Parameters	`executeFn` - The function to call when executing.
Returns	This action handler.
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 50

# reset


Signature	`plugins.core.action.handler:reset([updateNow]) -> nil`
Type	Method
Description	Resets the handler, clearing any cached result and requesting new ones.
Parameters	`updateNow` - (optional) If `true`, the choices will update immediately, otherwise they will update when the choices are next requested.
Returns	Nothing
Notes	None
Examples	None
Source	src/plugins/core/action/manager/handler.lua line 231