The following example binds the action
click events of a button.
The action handler uses the
client module for calling an url defined by
Note: Don't forget to export your action handler, otherwise it won't be accessible.
There are different types of action handlers:
- Direct action handlers are directly passed to the
bindActionfunction (see section Action Binding Mechanism).
- Registered action handlers are globaly registered by means of the
registerHandlerfunction and can be shared by modules.
- Component action handlers are used to execute actions of a ui Components
- Namespace action handlers will be searched within the humhub namespace if there is no other matching handler
Note: Component and Namespace action handlers are the most common and prefered handler types.
TIP: You can define multiple actions with different urls on the same $trigger by means of for example
All action handler functions are provided with an action event which is a derivate of
$.Event and provides, beside others, the following attributes:
$trigger: The jquery instance, which was responsible for triggering the event e.g. a button.
$target: Can be used to define a target component or widget and is defined by the
data-action-targetattribute of $trigger. If not explicitly set, the $trigger node will also be the events $target. See the component section for more details.
url: Contains the
data-action-click-url(will be prefered in case of click events).
params: Can be used to add additional action parameters by setting
data-action-paramsor the more specific
data-action-click-paramsin case of a click event.
$form: In case your $trigger is of
type="submit"or has a
data-action-submitattribute, the action event will include a jquery instance of the sorrounding form or the form set by the $target.
clientmodule knows how to handle action events and will try to determine the url from the given event instance if no url was explicitly provided as argument. In case of
client.submit, the client will try to determine the url of the forms
actionif the trigger does not specify an action url.
originalEvent: The original event which triggered the action
finish: This function is called to mark the action as completed, this function may be called manually to release the action block or remove the loader animation of a trigger with
data-ui-loaderflag. See the Action Blocking section for more information.
To prevent actions from beeing executed multiple times before finishing, actions are blocked during the execution time by default. The blocking logic can be configured by setting the
data-action-block on the trigger node. The following block values are available:
- none: No blocking at all
- sync: Synchronous blocking, the block will be released after the handler finished. This is the default block for all non async trigger elements.
- async: The block has to be released manually by calling the
event.finish()function. Note this block type is used by default for action handlers with a given
client.submit(evt)will call the events
finishfunction automatically after receiving the server response, so you won't have to call it in your handler.
Action Binding Mechanism
humhub.modules.action.bindAction function is used to bind event types to all nodes of a given selector.
The following action bindings are available by default:
change events are supported by default. This may change in the future.
You can extend the supported event types on demand as in the following example:
NOTE: The first argument of the bindAction should be the first static (never removed from dom or lazy loaded) parent node of all nodes you wish to bind.
NOTE: Too many delegated events to the
documentis a performance antipattern.
How does it work:
In the previous example the bindAction call will bind a delegate to the
If the delegate handler receives an unhandled action event, it will rebind all bindings directly to the trigger elements and run the action. All upcoming events will directly be handled by the trigger, which prevents the bubbling latency.
NOTE: As long as you don't need any custom bindings, you won't have to worry about the binding mechanism.
TIP: Since humhub action binding is based on jquerys event delegation, you can use all event types of jquery.