Nitrogen 2.x Documentation

Update a form element (textbox, dropdown, checkbox, etc) to set text value of TargetID. Can also be used to set the src attribute of an image tag.

Enables the target form field or button.

Disables the target form field or button.

Update the contents of TargetID with a new set of Nitrogen Elements.

Replace TargetID with a new set of Nitrogen Elements.

Remove TargetID from the DOM.

Insert Nitrogen Elements at the top of TargetID (within the contents of TargetID), shifting the existing contents downward.

Insert Nitrogen Elements at the bottom of the TargetID (within the contents of TargetID), below the existing contents.

Insert Nitrogen Elements before TargetID in the DOM, shifting the existing contents downward.

Insert Nitrogen Elements after TargetID in the DOM, below the existing contents.

Insert the Nitrogen Elements as a new flash message.

Convenience function to format a string similar to io_lib:format(Format, Data). Returns a flattened list.

Note, if Format is a binary, the return type will be a binary, and if Format is a string, the return type will be a string.

Return the first element in the list that is not 'undefined'.

Return true if the Term is an Erlang string. That is, a flat list of integers.

Convert the supplied term to a flat list, if possible. Useful for turning Integers, Atoms, Binaries into Strings.

Convert the supplied term into an Atom, if possible. Useful for turning Integers, Binaries, and Strings into Atoms.

Convert the supplied term into a Binary, if possible. Useful for turning Integers, Atoms, and Strings into Binaries.

Convert the supplied term into an Integer, if possible. Useful for turning Atoms, Strings, and Binaries into Integers.

HTML encode the supplied String, converting things like < and > into &lt; and &gt;.

HTML decoding decode the supplied String, converting things like &lt; and &gt; into < and >.

URL encode the supplied String, converting potentially URL-breaking characters into percent notation (%XX).

URL decode the supplied String, converting a percent-encoded String into a normal String.

Hex-encode the supplied String.

Convert a hex-encoded String to a normal String.

Return a temp id. Useful for naming an Element so that you can refer to it during a postback later, without giving it a specific name.

Convert a String to a JS-safe string by adding backslashes to quotes and newlines.

Because Erlang doesn't provide a means to join a list in a non-string fashion, this will join the Terms on the delimiter, regardless of the type of Delimiter.

wf:join([Line1,Line2,Line2],#br{}).

Wire actions to the page. The Actions are applied against the entire page unless a trigger or target are specified within the action itself.

For example, show a Javascript alert:

wf:wire(#alert { text="Hello, World!" })

Wire actions to the page, targeted against supplied TargetID. For example, hide a Panel:

wf:wire(PanelID, #hide {})

Wire actions to the page, triggering on the supplied TriggerID and targeting against the supplied TargetID. This allows you to wire actions (such as #event) that listen to a click on one element and modify a different element.

For example, when a button is clicked, hide a panel:

wf:wire(ButtonID, PanelID, #event { type=click, actions=#hide {} })

Wire actions to the page, however, execute the actions before any normal or deferred priority wired actions.

Wire actions to the page, however, execute these actions after any normal or eager priority wired actions.

Spawn the provided function (arity 0) and tell the browser to poll for the results at the specified interval, with a timeout setting. so See continuations example for usage.

Spawn a comet function, and tell the browser to open a COMET request to receive the results in real time. See example 1, example 2, and example 3 for usage.

Spawn a function connected to the specified local pool.

Spawn a function connected to the specified global pool.

Send the specified message to all comet functions connected to the specified local pool.

Send the specified message to all comet function connected to the specified GlobalPool.

Normally, the results of a comet function are sent to the browser when the function exits. flush/0 pushes results to the browser immediately, useful for a looping comet function.

Return the current async mode, either comet or {poll, IntervalInMS}.

Set the current async mode, either comet or {poll, IntervalInMS}.

Run all current and future async processes in comet mode. This uses more resources on the server, as HTTP connections stay open.

Run all current and future async processes in polling mode. This uses more resources on the client, as the application must issue a request every IntervalInMS milliseconds.

Spawn the provided function (arity 0) and tell the browser to poll for the results. See continuations example for usage.

Spawn the provided function (arity 0) and tell the browser to poll for the results at the specified interval. See continuations example for usage.

Redirect to the provided URL.

See Below.

Redirect to the provided URL, attaching a token on the end. The receiving page can subsequently call wf:redirect_from_login(DefaultURL) to send the user to PostLoginURL.

If PostLoginURL is not provided, it will default to the current page's URL.

Redirect the user back to a page that called wf:redirect_to_login(URL) or to the PostLoginURL provided to wf:redirect_to_login(URL, PostLoginURL) If the user came to the page for some other reason, then the user is redirected to the provided DefaultURL.

Retrieve the session value stored under the specified key. For example, retrieve the value of 'count' for the current user: Count = wf:session(count)

Retrieve the session value stored under a specific key. If not found, return the supplied default value.

Store a session variable for the current user. Key and Value can be any Erlang term. For example, store a count: wf:session(count, Count)

Returns the previous value associated with Key.

Clear the current user's session.

Clear session state, page state, identity, and roles.

Retrieve a page state value stored under the specified key. Page State is different from Session State in that Page State is scoped to a series of requests by one user to one Nitrogen Page.

Retrieve a page state value stored under the specified key. If the value is not set, then return the supplied default value.

Store a page state variable for the current user. Page State is different from Session State in that Page State is scoped to a series of requests by one user to one Nitrogen Page.

Clear a user's page state.

Return the user value that was previously set by wf:user(User)

Set the user for the current session.

Same as wf:user(undefined).

Check if the current user has a specified role.

Set whether the current user is in a specified role. IsInRole should be a boolean (true or false)

Remove the user from all roles.

Get all query string and POST values for the provided key. If more than one AtomKey matches, then this will throw an error, use wf:qs(AtomKey) instead.

Mnemonic: Think q as "Query".

Get the list of query string and POST values for the provided keys, and return the list of values for the keys. Syntactical sugar equivilant of:

[wf:q(AtomKey) || AtomKey <- ListOfAtomKeys]

Mnemonic: Think mq as "Multi Query".

Takes a list of keys returns a proplist of keys and respective values from query string and POST values.

Mnemonic: Think q_pl as "Query Proplist"

Example:

wf:qs_pl([favorite_robot,favorite_dinosaur,favorite_hobbit])

Returns something like:

[
    {favorite_robot,"Optimus Prime"},
    {favorite_dinosaur,"Velociraptor"},
    {favorite_hobbit,"Samwise"}
].

Get a list of query string and POST values for the provided key. (This acts like wf:q(AtomKey) in Nitrogen 1.0.)

Mnemonic: Think qs as "Query Plural"

Get a list of query string and POST values for the provided list of keys. Syntactical sugar equivilant of:

[wf:qs(AtomKey) || AtomKey <- ListOfAtomKeys]

Mnemonic: Think mqs as "Multi Query Plural"

Takes a list of keys and returns a proplist of keys and respective list of values from the query string and POST values.

Mnemonic: Think qs_pl as "Query Plurals into a Proplist"

Example:

wf:qs_pl([fruit,veggie,meat])

Returns something like:

[
   {fruit,["Apple","Peach"]},
   {veggie,["Broccoli"]},
   {meat,["Pork","Beef","Venison"]}
].

Return the complete text of the request body to the server. Note, this value will use the context of the current request. For example, the result of calling this during the page's initial request will be different than calling it within a postback event.

Set the HTTP response code. Default is 200.

Set the HTTP content type. Defaults is "text/html". This can be used to return text images or other files to the browser, rather than returning HTML.

Return the path info for the requested page. In other words, if the module web_my_page is requsted with the path "/web/my/page/some/extra/stuff then wf:get_path_info() would return "some/extra/stuff".

Return the requested page module. Useful information to know when writing a custom element or action.

Return the IP address of the client. Note that Erlang IP Addresses are 4-tuples (IPv4) or 8-tuples (IPv6). For example: {127,0,0,} or {8193,3512,51966,47806,0,0,0,1}

Shortcut method for wf:peer_ip(ListOfProxies, x_forwarded_for)

This will compare the peer_ip address against the provided list of proxies, and if any of them match the connected IP, then return the IP address from the ForwardedHeader.

Return a proplist of all cookies.

Get the value of a cookie.

Get the value of a cookie, if it doesn't exist, return the default.

Tell Nitrogen to set a cookie on the browser. Uses \"/\" for the Path, and Nitrogen's session timeout setting for the MinutesToLive value.

Tell Nitrogen to set a cookie on the browser under the specified Path that is valid for a certain number of minutes.

Tell Nitrogen to set the cookie to expire immediately, effectively deleting it from the browser. Is a shortcut for wf:cookie(Key,"","/",0).

Return a proplist of all HTTP headers.

Get the value of an HTTP header.

Get the value of an HTTP header, if it doesn't exist, return the default.

Set an HTTP header during the next response.

Serialize a term into a web-safe hex string, with checksumming. (Not encrypted!)

Turn a pickled binary back into the original term.

Turn a pickled binary back into the original term, checking to see if the term was pickled more than SecondsToLive second ago. Returns the Term if it is still 'fresh' or the atom 'undefined'.

Log an informational message.

Log an informational message.

Log a warning message.

Log a warning message.

Log an error message.

Log and error message.

Send a console.log() to the browser with Terms as the value. (See Console Log Action)

Get the Nitrogen configuration setting under the specified Key.

Get the Nitrogen configuration setting under the specified Key. If not set, then return DefaultValue.