Nitrogen - Nitrogen API Reference

Nitrogen API Reference

Convenience Functions
AJAX Updates
Event Wiring
Comet
Continuations/Polling
Redirects
Session State
Page State
Authentication and Authorization
HTTP Request and Response
Cookies
Headers
Serialization

(back to top)

Convenience Functions

wf:f(Format, Data) -> String

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

wf:coalesce([List]) -> Item

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

wf:is_string(Term) -> Bool

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

wf:to_list(Term) -> List

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

wf:to_atom(Term) -> Atom

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

wf:to_binary(Term) -> Binary

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

wf:to_integer(Term) -> Integer

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

wf:html_encode(String) -> EncodedString

HTML encodes the supplied String, converting things like < and > into < and >.

wf:guid() -> String

Returns a guid. That is, highly unique 16 byte value, represented as a hex string 32 characters long.

wf:temp_id() -> 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.

(back to top)

AJAX Updates

wf:update(TargetID, Elements) -> ok

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

wf:insert_top(TargetID, Elements) -> ok

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

wf:insert_bottom(TargetID, Elements) -> ok

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

wf:flash(Elements) -> ok

Insert the Nitrogen Elements as a new flash message.

(back to top)

Event Wiring

wf:wire(Actions) -> ok

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!" })

wf:wire(TargetID, Actions) -> ok

Wire actions to the page, targeted against supplied TargetID.
For example, hide a Panel:
wf:wire(PanelID, #hide {})

wf:wire(TriggerID, TargetID, Actions) -> ok

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 {} })

(back to top)

Comet

wf:comet(Function) -> Pid

Spawn a 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.

wf:comet_flush() -> ok

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

(back to top)

Continuations

wf:continue(Tag, Function) -> ok

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

wf:continue(Tag, Function, Interval) -> ok

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

wf:continue(Tag, Function, IntervalInMS, TimeoutInMS) -> ok

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

(back to top)

Redirect

wf:redirect(Url) -> ok

Redirect to the provided URL.

wf:redirect_to_login(Url) -> ok

Redirect to the provided URL, attaching a token on the end. The recieving page can call wf:redirect_from_login(DefaultUrl) to send the user back to the current page.

wf:redirect_from_login(DefaultUrl) -> ok

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

(back to top)

Session State

wf:session(Key) -> Value or 'undefined'

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

wf:session(Key, Value) -> ok

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)

wf:clear_session() -> ok

Clear the current user's session.

wf:logout() -> ok

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

(back to top)

Page State

wf:state(Key) -> Value

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.

wf:state(Key, Value) -> ok

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.

wf:clear_state() -> ok

Clear a user's page state.

(back to top)

Authentication and Authorization

wf:user() -> User or 'undefined'

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

wf:user(User) -> ok

Set the user for the current session.

wf:clear_user() -> ok

Same as wf:user(undefined).

wf:role(Role) -> 'true' or 'false'

Check if the current user has a specified role.

wf:role(Role, IsInRole) -> ok

Set whether the current user is in a specified role.

wf:clear_roles() -> ok

Remove the user from all roles.

(back to top)

Web Request and Response

wf:q(AtomKey) -> [StringValue]

Get all query string and POST values for the provided key. In most cases, returns a list of Values, though in most cases it will be a list of length 1.

wf:set_response_code(IntegerCode) -> ok

Set the HTTP response code. Defaults to 200

wf:set_content_type(ContentType) -> ok

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

wf:get_path_info() -> String

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

wf:get_page_module() -> Atom

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

(back to top)

HTTP Cookies

wf:set_cookie(Key, Value) -> ok

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

wf:set_cookie(Key, Value, Path, MinutesToLive) -> ok

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

wf:get_cookie(Key) -> String

Retrieve a previously set cookie.

(back to top)

HTTP Headers

wf:get_headers() -> [{AtomKey, StringValue}, ...]

Returns a proplist of all HTTP headers.

wf:get_header(AtomKey) -> Value

Returns the value of an HTTP header.

wf:set_header(StringKey, HeaderValue) -> ok

Sets an HTTP header during the next response.

(back to top)

Serialization

wf:pickle(Term) -> PickledBinary

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

wf:depickle(PickledBinary) -> Term

Turn a pickled binary back into the original term.

wf:depickle(PickledBinary, SecondsToLive) -> {IsStillValid, Term}

Turn a pickled binary back into the original term, checking to see if the term was pickled more than SecondsToLive second ago. Returns a tuple indicating if the term is still 'fresh'.