Home » Documentation » Scomps » loremipsum menu wire_args wire validate tabs spinner sorter sortable script pager include google_chart droppable draggable stream chart_pie3d chart_pie button

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.