wire

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 are show / hide elements or 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:

{% 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 controller 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 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:

event({submit, Tag, FormId, 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.

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 tag. 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.

Example:

{% 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."} %}

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: Interactivity: Calling Zotonic from Javascript.

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”. 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 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 controller that handled the page request. delegate=”event_handler”

See also

the tag wire_args and the list of predefined Actions.

Table Of Contents

Previous topic

validate

Next topic

wire_args

Versions

Actions