# wire Source: https://zotonic.com/docs/1327/wire URI: https://zotonic.com/id/1327 Language: en Connect actions and events to a HTML element. The wire tag is the basis for most Ajax interaction on web pages. It allows to connect actions to HTML elements. Examples of [Actions](/id/template_action#actions) are action#show / action#hide elements or action#postback to the server. Wire actions to an element -------------------------- The primary use of wire is to connect an action to a HTML element or javascript event. Example: ```erlang {% wire id="show" action={show target="message"} %} Click to show a message ``` A click on the link will show the message “Hello World!”. Wire postbacks to the server ---------------------------- Wire can post an event back to the server. Use for this the “postback” argument: ```erlang {% wire id="mybutton" postback={hello world="round"} %} ``` When the button is clicked the event function of the page controller will be called as: ```erlang event(#postback{message=Postback, trigger=TriggerId, target=TargetId}, Context). ``` Where “Postback” will be `{hello, [{world,<<"round">>}]}` and both “TriggerId” and “TargetId” will be `<<"mybutton">>`. Wire form submit events ----------------------- Wire is also used to connect a form to the event routine handling the form. Example: ```erlang {% wire id="myform" type="submit" postback="some_tag" action={toggle target="message"} %} ``` The wire tag redirects the submit of the form to the event routine of the controller. A submit will also toggle the visibility of the “message” element on the page. Note that the action is “postback”, this is obligatory. The event routine will be called as: ```erlang event(#submit{message=Tag, form=FormId, target=TargetId}, Context). ``` Where Tag will be the postback set by the wire tag (in the example the atom `some_tag`) and FormId and TargetId are both the HTML id of the submitted form. The posted input fields can be fetched using `z_context:get_q/2`, `z_context:get_q_all/1` or `z_context:get_q_validated/2`. ```erlang Title = z_context:get_q(<<"title">>, Context), AllArgs = z_context:get_q_all(Context); ``` There are some extra arguments added to every form post: | Post argument | Description | Example | | -------------- | -------------------------------------------------------- | ---------------- | | `z_trigger_id` | Id of the HTML element that triggered the submit. | `<<"mybutton">>` | | `postback` | Signed postback set by the wire tag. Handled internally. | | Browser-server communication uses MQTT over WebSocket connections managed by Cotonic. The browser MQTT bridge handles connection identity; a `z_pageid` form argument is not required. Wire to the page load or unload ------------------------------- A `{% wire %}` without an id will bind the actions and/or postback to the window instead of an element. Omitting a type as well will execute all actions and/or postback on page load. Example: ```erlang {% wire action={alert text="Welcome to this page."} %} ``` The type “unload” will execute all actions and/or postback when leaving the page: ```erlang {% wire type="unload" action={alert text="Bye."} %} ``` Call a wire action from JavaScript ---------------------------------- Use `{% wire name="myname" %}` to define a named action and trigger it from JavaScript with `z_event("myname")`. See: [Wires](/id/doc_developerguide_server_browser_interaction#guide-named-wire). Wire an action to a MQTT topic ------------------------------ ::: {.note title="Note"} module#mod_mqtt must be enabled before wiring to a topic ::: Use `{% wire type={mqtt topic=... topic=...} %}` to connect to one or more MQTT topics. Example: ```erlang {% wire type={mqtt topic="~site/public/hello"} action={growl text="hello"} %} ``` And in Erlang this will trigger the above *growl*: ```erlang z_mqtt:publish(<<"~site/public/hello">>, <<>>, z_acl:sudo(z:c(mysite))). ``` See also scomp#live Arguments --------- The wire tag accepts the following arguments: | Argument | Description | Example | | ----------- | -------------------------------------------------------------------------------- | ----------------------------------------------------- | | `id` | HTML id of the element the action gets connected to. When the id is not given then the event is bound to the window. | `id=”mybutton”` | | `type` | The type of the event triggering the action. Defaults to “click”. Other types are: “enterkey”, “interval”, “continuation”, “submit” or one of the jQuery events “blur”, “focus”, “load”, “resize”, “scroll”, “unload”, “beforeunload”, “click”, “dblclick”, “mousedown”, “mouseup”, “mousemove”, “mouseover”, “mouseout”, “mouseenter”, “mouseleave”, “change”, “select”, “keydown”, “keypress”, “keyup” or “error”. The types can be extended by modules using the `#action_event_type` notification. The type must be a tuple, an example is the `{mqtt topic=...}` type provided by module#mod_mqtt | `type=”submit”` | | `propagate` | Specify this when you don’t want the event to be canceled after handling the wire. Useful for event types like focus, click etc. .. versionadded:: 0.6.1 | `propagate` | | `target` | Possible target for the action. The meaning of this argument depends on the action, defaults to id. | | | `action` | Action wired to the element. This parameter can be repeated to wire more than one action at a time. The value is a single or a list of action records. | `action={toggle target="message"}` | | `postback` | Postback that will be sent to the event handler of the controller or the delegate. Either a string, which will be sent as an atom, or a tagged property list. The example will be in Erlang `{myevent, [{foo,1},{bar,2}]}`. | `postback="ajaxevent" postback={myevent foo=1 bar=2}` | | `delegate` | Name of the Erlang module that will receive the postback. Defaults to the controller that handled the page request. | `delegate="event_handler"` | License: Attribution: Related resources: https://zotonic.com/api/agent/related/1327?language=en ## API access - [API help]() - [OpenAPI specification]() - [This resource as JSON]()