Wiring and Handling Events

rklophaus edited this page Sep 12, 2010 · 6 revisions

A Nitrogen event is a special kind of action that is triggered when the user clicks, mouses over, or otherwise interacts with the page.

Nitrogen events are most commonly used to execute a “postback”. A postback calls the event/1 function on your page module, giving you the opportunity to run some logic and update the page using Ajax.

For example, the following code issues a postback when the text is clicked:

#span { 
  text="Posts back when clicked.", 
  actions=#event { type=click, postback=got_click }

Nitrogen events can also be used to conditionally run Javascript on the browser. For example, the following code shows a Javascript alert when the text is clicked:

#span { 
  text="Posts back when clicked.", 
  actions=#event { type=click, actions=#alert { text="Click!" }}

You can use both style of events at the same time. For instance, you may want to have a postback event that saves a user’s work while at the same time displaying a Javascript alert indicating that the work is being saved.

Postback Events

How Do Postback Events Work?

When the user performs some action that triggers an event, a Javascript function bundles up the state of the page and then fires an Ajax postback to your server which is handled by Nitrogen.

Nitrogen examines the parameters of the postback, figures out which page and element caused the request, and then calls the event/1 function in the calling page’s module.

In the event/1 function you can execute whatever logic you want and update the HTML via Ajax. Because this could cause the page structure to change, only one Nitrogen postback event is allowed at a time. Events are queued and run sequentially.

Without this, if two events were to update the page at once there would be unpredictable results.

The Flexibility of the Event Tag

The event tag is the Erlang term that is passed to the event/1 function when a postback is executed. You can specify any valid Erlang term in this tag, the only tradeoff is that bigger tags mean bigger page sizes.

Use pattern matching in your event/1 function to catch the incoming tag.

For example:

#span { 
  id=mySpan, text="Click here.", 
  actions=#event { type=click, postback={got_click, mySpan, [1, two, "three"]} }

Some Shortcuts

90% of the time, when you add a postback event to a #textbox or #link, you will simply want the element to post back when clicked. Because this is such a standard operation, these elements support a shortcut.

Simply set the postback property of the textbox or link. When the textbox or link is clicked, it will automatically issue a postback using the value of the postback attribute as the postback tag.

For example:

#textbox { text="Click Me", postback=got_click }

Non-Postback Events

As stated above, not all #event actions necessarily have to post back. #event actions can contain other actions that are executed when the event is fired.

For example, this code will cause the text to fade out when clicked:

#span { 
  text="Disappears when clicked.", 
  actions=#event { type=click, actions=#effect_fade{} } 

By nesting #event tags, you can get some complicated behavior, such as showing a Javascript confirmation when an element is clicked, and then posting back only when the user clicks OK.

Properties of the #event Action

  • type – Any valid Javascript event, including click, mouseover, mouseout, mousedown, mouseup, focus, blur, etc.
  • postback – The tag that will be passed to the event/1 function when this event is triggered.
  • actions – Actions that will be run when this event is triggered.
  • delegate – The module that will receive the call to event/1. This defaults to the current page.
  • trigger – The element that will trigger this event.
  • target – The element that will be modified by Javascript in this event.
  • show_if – Only wires the event if set to true.