wire
Connect actions and events to a HTML element.
The wire scomp is the basis for most Ajax interaction on web pages. It allows to connect actions to HTML elements. Examples of actions are showing/hiding elements or postbacks 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:
{% wire id="show" action={show target="message"} %}
<a id="show" href="#">Click to show a message</a>
<p style="display: none" id="message">Hello World!</p>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:
{% wire id="mybutton" postback={hello world="round"} %}
<button id="mybutton">Post event to server</button>When the button is clicked the event function of the page resource will be called as:
event({postback, Postback, TriggerId, 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:
{% wire id="myform" type="submit" postback="some_tag" action={toggle target="message"} %}
<form id="myform" method="post" action="postback">
<input type="text" name="title" value="" />
<button id="mybutton" type="submit">Submit</button>
</form>The wire scomp redirects the submit of the form to the event routine of the resource. 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:
event({submit, Tag, FormId, TargetId}, Context).Where Tag will be the postback set by the wire scomp (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.
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" |
| z_pageid | Id of the page in the browser, used to connect comet and other communictation between the browser and the server. | "1uTsbzIsWqmdPmNopF32" |
| postback | Signed postback set by the wire scomp. Handled internally. |
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.
{% wire action={alert text="Welcome to this page."} %}The type “unload” will execute all actions and/or postback when leaving the page:
{% wire type="unload" action={alert text="Bye."} %}Arguments
The wire scomp 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". | 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. (available from zotonic 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 resource or the delegate. Either a string, which will be send 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 resource that handled the page request. | delegate="event_handler" |
See also the scomp {% wire_args %} and the list of predefined actions.
This page is part of the Zotonic documentation, which is licensed under the Apache License 2.0.
Comments
Sanket
Posted 1 year, 1 month ago.
Hello
Just wanted to notify a small mistake in first example
{% wire id="show" action={show id="message"} %}
show id="message" should be -> show target="message"
I wasted time to figure out such a small so it may help others
Regards
Sanket
Marc Worrell
Posted 1 year, 1 month ago.
Thanks for finding this mistake!
Andreas Stenius
Posted 6 months, 17 days ago.
"Where Tag will be the postback set by the wire scomp (in the example the atom 'some_tag')"
This is could be clarified to indicate, as for the previous example, that tag will be the first value in a tuple, and not a single atom. Ever.