action

Documentation

Overview

Package action defines actions that you can trigger using events. Normally you would do this with the On() function that all GoRADD controls have.

For example:

button := NewButton(p, "okButton").SetText("OK")
button.On(event.Click(), action.Message(javascript.JsCode("event.target.value") + "was clicked"))

will create a Message action that responds to a button click.

There are two types of actions:

• Javascript Actions
• Callback Actions

Javascript Actions execute javascript code that is handled immediately by the browser. Goradd provides a number of standard Javascript actions, like Redirect. Also, the Javascript action can execute any javascript.

Callback Actions invoke the DoAction() function on GoRADD controls. There are currently two kinds of Callback Actions:

• Ajax and
• Post

Create a callback action by calling action.Do. By default, this will create an Ajax action. Call Post on the resulting action to turn it into a Post action. You specify the control id of the receiving control, and an integer representing the action. The DoAction function of the control can then do whatever is needed on the server side.

Ajax actions use the javascript XMLHttpRequest mechanism to pass data without a complete refresh. In response to an Ajax action, a control can call its Refresh() function to redraw just that control. If a Post action is working, but not an Ajax action, one thing to check is to make sure Refresh() is called if anything in a control changes.

Post actions use the standard http Post method of html forms, and cause a page to completely refresh. This is the method used in the early days of the web, and while it still works, it isn't as efficient as Ajax actions. However, there are still specific times to use a Post action:

• When starting a file upload. Currently, you must use a Post action for file uploads.
• When debugging a problem with an Ajax action, it may be helpful to see if it works as a Post action.

In addition to the action id, a Callback action can receive data that is sent with the action, data that is sent by the control, and also data that is sent by the event that triggered the action. This data can be static data when the action is created, or dynamic data that is gathered by javascript when the action is invoked. See the action.Params structure for a description of what is supplied to the DoAction() function.

To execute multiple actions in response to an event, put the actions in an actionGroup. The actionGroup can have multiple javascript actions, but only one callback action.

Index

• Constants
• type ActionI
  • func AddClass(controlID string, classes string) ActionI
  • func Blur(controlID string) ActionI
  • func Confirm(m interface{}) ActionI
  • func Css(controlID string, property string, value interface{}) ActionI
  • func Focus(controlID string) ActionI
  • func GoraddFunction(operation string, arguments ...interface{}) ActionI
  • func Group(actions ...ActionI) ActionI
  • func Hide(controlID string) ActionI
  • func Javascript(js string) ActionI
  • func Message(m interface{}) ActionI
  • func Redirect(url string) ActionI
  • func RemoveClass(controlID string, classes string) ActionI
  • func Select(controlID string) ActionI
  • func SetControlValue(id string, key string, value interface{}) ActionI
  • func Show(controlID string) ActionI
  • func ToggleClass(controlID string, classes string) ActionI
  • func Trigger(controlID string, event string, data interface{}) ActionI
  • func WidgetFunction(controlID string, operation string, arguments ...interface{}) ActionI
• type CallbackActionAccessor
• type CallbackActionI
  • func Ajax(destControlId string, actionID int) CallbackActionI
  • func Do() CallbackActionI
  • func Refresh(id string) CallbackActionI
  • func Server(destControlId string, actionID int) CallbackActionI
• type GroupI
• type Params
  • func NewActionParams(event string, id int, action ActionI, controlId string, ...) Params
  • func (a *Params) ActionValue(i interface{}) (ok bool, err error)
  • func (a *Params) ActionValueBool() bool
  • func (a *Params) ActionValueFloat() float64
  • func (a *Params) ActionValueInt() int
  • func (a *Params) ActionValueString() string
  • func (a *Params) ControlValue(i interface{}) (ok bool, err error)
  • func (a *Params) ControlValueBool() (ret bool)
  • func (a *Params) ControlValueFloat() float64
  • func (a *Params) ControlValueInt() int
  • func (a *Params) ControlValueString() string
  • func (a *Params) EventValue(i interface{}) (ok bool, err error)
  • func (a *Params) EventValueBool() bool
  • func (a *Params) EventValueFloat() float64
  • func (a *Params) EventValueInt() int
  • func (a *Params) EventValueString() string
  • func (a *Params) EventValueStringMap() (m map[string]string)
• type RawActionValues
• type RenderParams

Constants

const DefaultActionId = 0

DefaultActionId is the default action id for events that do not want to specify a custom action id

const DefaultControlId = ""

DefaultControlId indicates that the control that the action is first sent to is the same as the control that received the event.

const RefreshActionId = -1

RefreshActionId is the action id that causes a control to refresh.

Types

type ActionI

type ActionI interface {
	// RenderScript is called by the framework to return the action's javascript.
	// You do not normally need to call this function.
	RenderScript(params RenderParams) string
}

ActionI is an interface that defines actions that can be triggered by events

func AddClass

func AddClass(controlID string, classes string) ActionI

AddClass will add the given class, or space separated classes, to the html object specified by the id.

func Blur

func Blur(controlID string) ActionI

Blur will blur the html object specified by the id.

func Confirm

func Confirm(m interface{}) ActionI

Confirm will put up a standard browser confirmation dialog box, and will cancel any following actions if the user does not agree.

func Css

func Css(controlID string, property string, value interface{}) ActionI

Css will set the css property to the given value on the given html object.

func Focus

func Focus(controlID string) ActionI

Focus will focus the html object specified by the id.

func GoraddFunction

func GoraddFunction(operation string, arguments ...interface{}) ActionI

GoraddFunction calls a function defined on the global goradd object that is in goradd.js.

func Group

func Group(actions ...ActionI) ActionI

Group joins multiple actions into a single action. Any number of javascript actions can be included, but only one callback action can be included in the group.

func Hide

func Hide(controlID string) ActionI

Hide will hide the given control

func Javascript

func Javascript(js string) ActionI

Javascript will execute the given javascript

func Message

func Message(m interface{}) ActionI

Message returns an action that will display a standard browser alert message. Specify a string, or one of the javascript.* types.

func Redirect

func Redirect(url string) ActionI

Redirect will navigate to the given page.

func RemoveClass

func RemoveClass(controlID string, classes string) ActionI

RemoveClass will turn off the given space separated classes in the html object specified by the id.

func Select

func Select(controlID string) ActionI

Select will select all the text in the html object specified by the id. The object should be a text box.

func SetControlValue

func SetControlValue(id string, key string, value interface{}) ActionI

SetControlValue is primarily used by custom controls to set a value that eventually can get picked up by the control in the UpdateFormValues function. It is an aid to tying javascript powered widgets together with the go version of the control. Value gets converted to a javascript value, so use the javascript.* helpers if you want to interpret a javascript value and pass it on. For example:

action.SetControlValue(myControl.ID(), "myKey", javascript.NewJsCode("event.target.id"))

will pass the id of the target of an event to the receiver of the action.

Note that if you need to save and restore state by calling MarshalState and UnmarshalState, you will need to have your control listen for the event that sets this value and call action.Do() so that UpdateFormValues will eventually get called.

func Show

func Show(controlID string) ActionI

Show will show the given control if it is hidden

func ToggleClass

func ToggleClass(controlID string, classes string) ActionI

ToggleClass will turn on or off the given space separated classes in the html object specified by the id.

func Trigger

func Trigger(controlID string, event string, data interface{}) ActionI

Trigger will trigger a javascript event on a control

func WidgetFunction

func WidgetFunction(controlID string, operation string, arguments ...interface{}) ActionI

WidgetFunction calls a GoRADD widget function in javascript on an HTML control with the given id. Functions for all widgets are defined by the widget object in goradd.js. Additional widget functions can be defined in the javascript for each individual widget.

type CallbackActionAccessor

type CallbackActionAccessor interface {
	GetActionID() int
	// GetDestinationControlID returns the id that the action was sent to.
	GetDestinationControlID() string
	// GetDestinationControlSubID returns the id of the sub-control that is the destination of the action, if one was assigned.
	GetDestinationControlSubID() string
	// IsPostAction returns true if the action is a server action
	IsPostAction() bool
}

CallbackActionAccessor is used by the framework and the internals of controls to access actions. Callback actions must satisfy this interface, as well as the CallbackActionI interface.

type CallbackActionI

type CallbackActionI interface {
	ActionI
	ID(id int) CallbackActionI
	ActionValue(v interface{}) CallbackActionI
	Async() CallbackActionI
	ControlID(id string) CallbackActionI
	Post() CallbackActionI
}

CallbackActionI defines actions that result in a callback to the server through a Post or Ajax call.

• ID sets an optional action id, which can be retrieved in the DoAction function.
• ActionValue sets the value that will be available to the DoAction handler as the ActionValue() function in the Param structure. This can be any go type, including slices and maps, or a javascript.JavaScripter interface type. javascript.Closures will be called immediately with a (this) parameter.
• Async will cause the action to be handled asynchronously. Use this only in special situations where you know that you do not need information from other actions.
• ControlID sets the id of the control that will receive the action. Composite controls can specify a sub id which indicates that the action should be sent to a component inside the main control by concatenating the control's id with another id that indicates the internal destination, separated with an underscore. By default, the control will be the control receiving the event that triggered the action.
• Post turns the action into a form post action, vs. an Ajax action. You only need this in special situations, when the standard Ajax action will not work.

func Ajax

func Ajax(destControlId string, actionID int) CallbackActionI

Ajax creates an ajax action. When the action fires, the DoAction() function of the GoRADD control identified by the destControlId will be called, and the given actionID will be the ID passed in the Params of the call. You can specify a sub id which indicates that the action should be sent to something inside the main control by concatenating the control's id with another id that indicates the internal destination, separated with an underscore.

The returned action uses a Builder pattern to add options, so for example you might call:

myControl.On(event.Click(), action.Do("myControl", MyActionIdConst).EventValue("myActionValue").Async())

Deprecated: Use Do() instead.

func Do

func Do() CallbackActionI

Do returns an action that will invoke the DoAction function on the destination control.

By default, the control that will receive the action will be the control that triggered the action.

The returned action uses a Builder pattern to add options, so for example you might call:

myControl.On(event.Click(), action.Do("myControl", MyActionIdConst).EventValue("myActionValue").Async())

By default, the action uses an ajax process defined in the goradd.js file. If you want to instead use a more traditional http POST process, call the Post() function on the returned action, but that would rarely be needed.

func Refresh

func Refresh(id string) CallbackActionI

Refresh will cause the given control to redraw

func Server

func Server(destControlId string, actionID int) CallbackActionI

Server returns a Server based action that is invoked with a Post http call. Deprecated: Use Do instead.

type GroupI

type GroupI interface {
	GetCallbackAction() CallbackActionI
}

type Params

type Params struct {
	// Event is the javascript name of the event that was triggered.
	Event string
	// ID is the action id assigned when the action was created
	ID int
	// Action is an interface to the action itself
	Action ActionI
	// ControlID is the control that originated the action
	ControlId string
	// contains filtered or unexported fields
}

Params are sent to the control.DoAction() function in response to a user action. Each action might contain one of three kinds of values:

• Action value, a value assigned to the action when it is created,
• Control value, a value returned by certain custom controls
• Event value, a value assigned by certain event types

Use the accessor functions like Params.ActionValueInt or Params.ControlValueString to extract an appropriately typed value from the action.

func NewActionParams

func NewActionParams(event string, id int, action ActionI, controlId string, rawValues RawActionValues) Params

NewActionParams is used internally by the framework to create new action parameters. You should not normally need to call this function.

func (*Params) ActionValue

func (a *Params) ActionValue(i interface{}) (ok bool, err error)

ActionValue will return the action value into the given object using json.Unmarshal. You should primarily use it to get object or array values out of the action value. If you are expecting a basic type, use one of the ActionValue* helper functions instead. The given value should be a pointer to an object or variable that is the expected type for the data. ok will be false if no data was found. It will return an error if the data was found, but could not be converted to the given type.

func (*Params) ActionValueBool

func (a *Params) ActionValueBool() bool

ActionValueBool returns the action value as a bool.

func (*Params) ActionValueFloat

func (a *Params) ActionValueFloat() float64

ActionValueFloat returns the action value as a float64.

func (*Params) ActionValueInt

func (a *Params) ActionValueInt() int

ActionValueInt returns the action value as an integer.

func (*Params) ActionValueString

func (a *Params) ActionValueString() string

ActionValueString returns the action value as a string. It will convert to a string, even if the value is not a string.

func (*Params) ControlValue

func (a *Params) ControlValue(i interface{}) (ok bool, err error)

ControlValue will return the control value into the given object using json.Unmarshal. You should primarily use it to get object or array values out of the control value. If you are expecting a basic type, use one of the ControlValue* helper functions instead. The given value should be a pointer to an object or variable that is the expected type for the data. ok will be false if no data was found. It will return an error if the data was found, but could not be converted to the given type.

func (*Params) ControlValueBool

func (a *Params) ControlValueBool() (ret bool)

ControlValueBool returns the control value as a bool.

func (*Params) ControlValueFloat

func (a *Params) ControlValueFloat() float64

ControlValueFloat returns the control value as a float64.

func (*Params) ControlValueInt

func (a *Params) ControlValueInt() int

ControlValueInt returns the control value as an int.

func (*Params) ControlValueString

func (a *Params) ControlValueString() string

ControlValueString returns the control value as a string. It will convert to a string, even if the value is not a string.

func (*Params) EventValue

func (a *Params) EventValue(i interface{}) (ok bool, err error)

EventValue will attempt to put the Event value into the given object using json.Unmarshal. You should primarily use it to get object or array values out of the Action value. If you are expecting a basic type, use one of the EventValue* helper functions instead. The given value should be a pointer to an object or variable that is the expected type for the data. ok will be false if no data was found. It will return an error if the data was found, but could not be converted to the given type.

func (*Params) EventValueBool

func (a *Params) EventValueBool() bool

EventValueBool returns the event value as a bool. To be false, the value should be a boolean false, a numeric 0, an empty string, null or undefined on the client side. Otherwise, will return true.

func (*Params) EventValueFloat

func (a *Params) EventValueFloat() float64

EventValueFloat returns the event value as a float64. If the value was not numeric, it will return 0.

func (*Params) EventValueInt

func (a *Params) EventValueInt() int

EventValueInt returns the event value as an integer. If the value was a floating point value at the client, it will be truncated to an integer. If the value is not numeric, will return 0.

func (*Params) EventValueString

func (a *Params) EventValueString() string

EventValueString returns the event value as a string. It will convert to a string, even if the value is not a string.

func (*Params) EventValueStringMap

func (a *Params) EventValueStringMap() (m map[string]string)

EventValueStringMap returns the event value as a map[string]string.

type RawActionValues

type RawActionValues struct {
	Event   json.RawMessage `json:"event"`
	Control json.RawMessage `json:"control"`
	Action  json.RawMessage `json:"action"`
}

RawActionValues is the structure representing the json values sent in an ActionParam. Use the helper functions to get to the values.

type RenderParams

type RenderParams struct {
	// TriggeringControlID is the id of the control that triggered the action
	TriggeringControlID string
	// ControlActionValue is the control action value that will be received by the DoAction() function.
	ControlActionValue interface{}
	// EventID is the event that triggered the action
	EventID uint16
	// EventActionValue is the event action value that will be received by the DoAction() function.
	EventActionValue interface{}
}

RenderParams is used by the framework to give information that helps with rendering actions.