@@ -1362,10 +1362,6 @@ <key>showFileHierarchyDrawer</key> <true/> <key>windowFrame</key> -<<<<<<< HEAD:Nitrogen.tmproj <string>{{285, 0}, {928, 778}}</string> -======= - <string>{{287, 0}, {928, 778}}</string> ->>>>>>> 19b6f15aecead6e0cb0d1de9317551bf1ef735ab:Nitrogen.tmproj </dict> </plist> Nitrogen.tmproj @@ -2,8 +2,6 @@ {title, "Confirm Password Validator"}, -{see_also, [base]}, - {usage, " wf:wire(ButtonID, ConfirmPasswordID, #validate { validators=[   #confirm_password { text=\"Passwords must match.\", password=PasswordID } Quickstart/reference/validators/confirm_password.txt @@ -2,8 +2,6 @@ {title, "Custom Server-Side Validator"}, -{see_also, [base]}, - {usage, " % Function to validate that a value is either upper or lower case, % depending on the value of Tag... Quickstart/reference/validators/custom.txt @@ -2,8 +2,6 @@ {title, "Email Validator"}, -{see_also, [base]}, - {usage, " wf:wire(ButtonID, TextBoxID, #validate { validators=[   #is_email { text=\"Not a valid email address.\" } Quickstart/reference/validators/is_email.txt @@ -2,8 +2,6 @@ {title, "Integer Validator"}, -{see_also, [base]}, - {usage, " wf:wire(ButtonID, TextBoxID, #validate { validators=[   #is_integer { text=\"Must be an integer.\" } Quickstart/reference/validators/is_integer.txt @@ -2,8 +2,6 @@ {title, "Required Field Validator"}, -{see_also, [base]}, - {usage, " wf:wire(ButtonID, TextBoxID, #validate { validators=[   #is_required { text=\"Required\" } Quickstart/reference/validators/is_required.txt @@ -2,8 +2,6 @@ {title, "Custom Client-Side Validator"}, -{see_also, [base]}, - {usage, " % Wire the validator against the 'my_validator' Javascript % function, passing in some args... Quickstart/reference/validators/js_custom.txt @@ -2,8 +2,6 @@ {title, "Max Length Validator"}, -{see_also, [base]}, - {usage, " wf:wire(ButtonID, TextBoxID, #validate { validators=[   #max_length { text=\"Maximum of 7 characters.\", length=7 } Quickstart/reference/validators/max_length.txt @@ -2,8 +2,6 @@ {title, "Min Length Validator"}, -{see_also, [base]}, - {usage, " wf:wire(ButtonID, TextBoxID, #validate { validators=[   #min_length { text=\"Minimum of 4 characters.\", length=4 } Quickstart/reference/validators/min_length.txt @@ -8,10 +8,32 @@ main() -> #template { file="./wwwroot/onecolumn.html", bindings=[ ]}. title() -> "Nitrogen API Reference". -headline() -> "Nitrogen API Reference". +headline() -> "<a name=top></a>Nitrogen API Reference". + +hlink(Title, Name) -> [ + #p{}, + #hr{}, + #link { text="(back to top)", url="#top", style="float: right;" }, + wf:f("<a name=~s><h2>~s</h2></a>", [Name, Title]) +]. body() -> [ - #h2 { text="Convenience Functions" }, + #link { text="Convenience Functions", url="#convenience_functions" }, #br{}, + #link { text="AJAX Updates", url="#ajax_updates" }, #br{}, + #link { text="Event Wiring", url="#event_wiring" }, #br{}, + #link { text="Comet", url="#comet" }, #br{}, + #link { text="Continuations/Polling", url="#continuations" }, #br{}, + #link { text="Redirects", url="#redirect" }, #br{}, + #link { text="Session State", url="#session_state" }, #br{}, + #link { text="Page State", url="#page_state" }, #br{}, + #link { text="Authentication and Authorization", url="#authentication" }, #br{}, + #link { text="HTTP Request and Response", url="#request_and_response" }, #br{}, + #link { text="Cookies", url="#cookies" }, #br{}, + #link { text="Headers", url="#headers" }, #br{}, + #link { text="Serialization", url="#serialization" }, #br{}, + #p{}, + + hlink("Convenience Functions", convenience_functions), #h3 { text="wf:f(Format, Data) -> String" }, "Convenience function to format a string similar to io_lib:format(Format, Data). Returns a flattened list.", @@ -38,28 +60,190 @@ body() -> [ "HTML encodes the supplied String, converting things like < and > into &lt; and &gt;.", #h3 { text="wf:guid() -> String" }, - "Returns a guid. That is, highly unique 32 byte hex string.", + "Returns a guid. That is, highly unique 16 byte value, represented as a hex string 32 characters long.", + #h3 { text="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. + ", + + + + hlink("AJAX Updates", ajax_updates), + #h3 { text="wf:update(TargetID, Elements) -> ok" }, + "Replace the contents of TargetID with a new set of Nitrogen Elements.", - #h2 { text="Serialization" }, + #h3 { text="wf:insert_top(TargetID, Elements) -> ok" }, + "Insert Nitrogen Elements at the top of TargetID, shifting the existing contents downward.", - #h3 { text="wf:pickle(Term) -> PickledBinary" }, - "Serialize a term into a web-safe hex string, with checksumming. (Not encrypted!)", + #h3 { text="wf:insert_bottom(TargetID, Elements) -> ok" }, + "Insert Nitrogen Elements at the bottom of the TargetID, below the existing contents.", + + #h3 { text="wf:flash(Elements) -> ok" }, + "Insert the Nitrogen Elements as a new flash message.", + + + hlink("Event Wiring", event_wiring), - #h3 { text="wf:depickle(PickledBinary) -> Term" }, - "Turn a pickled binary back into the original term.", + #h3 { text="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: + <code>wf:wire(#alert { text=\"Hello, World!\" })</code> + ", - #h3 { text="wf:depickle(PickledBinary, SecondsToLive) -> {IsStillValid, Term}" }, + #h3 { text="wf:wire(TargetID, Actions) -> ok" }, " - 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'. + Wire actions to the page, targeted against supplied TargetID. + For example, hide a Panel: + <code>wf:wire(PanelID, #hide {})</code> ", - + #h3 { text="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: + <code>wf:wire(ButtonID, PanelID, #event { type=click, actions=#hide {} })</code> + ", + + + hlink("Comet", comet), + #h3 { text="wf:comet(Function) -> Pid" }, + " + Spawn a function and tell the browser to open a COMET request to receive the results in real time. + See <a href='/web/samples/comet1'>example 1</a>, <a href='/web/samples/comet2'>example 2</a>, and + <a href='/web/samples/comet3'>example 3</a> for usage. + ", + + #h3 { text="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. + ", + + + + hlink("Continuations", continuations), + + #h3 { text="wf:continue(Tag, Function) -> ok" }, + " + Spawn the provided function (arity 0) and tell the browser to poll for the results. + See <a href='/web/samples/continuations'>continuations example</a> for usage. + ", + + #h3 { text="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 <a href='/web/samples/continuations'>continuations example</a> for usage. + ", + + #h3 { text="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 <a href='/web/samples/continuations'>continuations example</a> for usage. + ", + + + + + hlink("Redirect", redirect), + + #h3 { text="wf:redirect(Url) -> ok" }, + "Redirect to the provided URL.", + + #h3 { text="wf:redirect_to_login(Url) -> ok" }, + " + Redirect to the provided URL, attaching a token on the end. The recieving page can call + <code>wf:redirect_from_login(DefaultUrl)</code> to send the user back to the current page. + ", + + #h3 { text="wf:redirect_from_login(DefaultUrl) -> ok" }, + " + Redirect the user back to a page that called <code>wf:redirect_to_login(Url)</code>. If + the user came to the page for some other reason, then the user is redirected to the + provided DefaultUrl. + ", + + hlink("Session State", session_state), + + #h3 { text="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: + <code>Count = wf:session(count)</code> + ", + + #h3 { text="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: + <code>wf:session(count, Count)</code> + ", + + #h3 { text="wf:clear_session() -> ok" }, + " + Clear the current user's session. + ", + + #h3 { text="wf:logout() -> ok" }, + "Clear session state, page state, identity, and roles.", + + + + hlink("Page State", page_state), + + #h3 { text="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. + ", + + #h3 { text="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. + ", + + #h3 { text="wf:clear_state() -> ok" }, + "Clear a user's page state.", + + + hlink("Authentication and Authorization", authentication), + + #h3 { text="wf:user() -> User or 'undefined'" }, + "Return the user value that was previously set by <code>wf:user(User)</code>", + + #h3 { text="wf:user(User) -> ok" }, + "Set the user for the current session.", + + #h3 { text="wf:clear_user() -> ok" }, + "Same as <code>wf:user(undefined)</code>.", + + #h3 { text="wf:role(Role) -> 'true' or 'false'" }, + "Check if the current user has a specified role.", + + #h3 { text="wf:role(Role, IsInRole) -> ok" }, + "Set whether the current user is in a specified role.", + + #h3 { text="wf:clear_roles() -> ok" }, + "Remove the user from all roles.", + + + + hlink("Web Request and Response", request_and_response), - #h2 { text="Web Request and Response" }, + #h3 { text="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. + ", #h3 { text="wf:set_response_code(IntegerCode) -> ok" }, "Set the HTTP response code. Defaults to 200", @@ -86,7 +270,7 @@ body() -> [ - #h2 { text="HTTP Cookies" }, + hlink("HTTP Cookies", cookies), #h3 { text="wf:set_cookie(Key, Value) -> ok" }, " @@ -105,7 +289,7 @@ body() -> [ - #h2 { text="HTTP Headers" }, + hlink("HTTP Headers", headers), #h3 { text="wf:get_headers() -> [{AtomKey, StringValue}, ...]" }, "Returns a proplist of all HTTP headers.", @@ -116,104 +300,20 @@ body() -> [ #h3 { text="wf:set_header(StringKey, HeaderValue) -> ok" }, "Sets an HTTP header during the next response.", - - - #h2 { text="AJAX Updates" }, - #h3 { text="wf:update(TargetID, Elements) -> ok" }, - "Replace the contents of TargetID with a new set of Nitrogen Elements.", - #h3 { text="wf:insert_top(TargetID, Elements) -> ok" }, - "Insert Nitrogen Elements at the top of TargetID, shifting the existing contents downward.", + hlink("Serialization", serialization), - #h3 { text="wf:insert_bottom(TargetID, Elements) -> ok" }, - "Insert Nitrogen Elements at the bottom of the TargetID, below the existing contents.", - - - #h2 { text="Event Wiring" } -]. - -% wire(Actions) -> wf_render:wire(Actions). -% wire(TargetID, Actions) -> wf_render:wire(TargetID, Actions). -% wire(TriggerID, TargetID, Actions) -> wf_render:wire(TriggerID, TargetID, Actions). -% -% -% %%% WF_CONTINUE %%% -% -% continue(Tag, Function) -> wf_continuation:continue(Tag, Function). -% continue(Tag, Function, Interval) -> wf_continuation:continue(Tag, Function, Interval). -% continue(Tag, Function, Interval, Timeout) -> wf_continuation:continue(Tag, Function, Interval, Timeout). -% -% -% %%% WF_COMET %%% -% -% comet(Function) -> wf_comet:comet(Function). -% comet_flush() -> wf_comet:comet_flush(). -% -% -% %%% WF_REDIRECT %%% -% -% redirect(Url) -> wf_redirect:redirect(Url). -% redirect_to_login(Url) -> wf_redirect:redirect_to_login(Url). -% redirect_from_login(DefaultUrl) -> wf_redirect:redirect_from_login(DefaultUrl). -% -% -% -% %%% WF_SESSION %%% -% -% state(Key) -> wf_state:state(Key). -% state(Key, Value) -> wf_state:state(Key, Value). -% clear_state() -> wf_state:clear_state(). -% -% -% %%% WF_STATE %%% -% -% user() -> wf_session:user(). -% user(User) -> wf_session:user(User). -% clear_user() -> wf_session:clear_user(). -% -% role(Role) -> wf_session:role(Role). -% role(Role, IsInRole) -> wf_session:role(Role, IsInRole). -% clear_roles() -> wf_session:clear_roles(). -% -% session(Key) -> wf_session:session(Key). -% session(Key, Value) -> wf_session:session(Key, Value). -% clear_session() -> wf_session:clear_session(). -% -% logout() -> clear_user(), clear_roles(), clear_state(), clear_session(). -% -% -% %%% WF_CACHE %%% -% -% cache(Key, Function) -> wf_cache:cache(Key, Function). -% cache(Key, Function, Options) -> wf_cache:cache(Key, Function, Options). -% -% -% %%% WF_QUERY %%% -% -% q(Q) -> wf_query:q(Q). -% -% -% %%% WF_PATH %%% -% -% me_var() -> wf_render:me_var(). -% temp_id() -> wf_path:temp_id(). -% to_js_id(Path) -> wf_path:to_js_id(Path). -% -% -% %%% OTHER %%% -% -% flash(Terms) -> element_flash:add_flash(Terms). -% -% assert(true, _) -> ok; -% assert(false, Error) -> erlang:error(Error). -% -% -% -% -% -% -% -% "Coming soon.". -% -% event(_) -> ok. + #h3 { text="wf:pickle(Term) -> PickledBinary" }, + "Serialize a term into a web-safe hex string, with checksumming. (Not encrypted!)", + + #h3 { text="wf:depickle(PickledBinary) -> Term" }, + "Turn a pickled binary back into the original term.", + + #h3 { text="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'. + " +]. \ No newline at end of file Quickstart/src/reference/web_reference_api.erl @@ -51,7 +51,6 @@ column2() -> ], Other = [ - { "/web/reference/validators/base", "(Base Action)" }, { "/web/reference/validators/js_custom", "Custom Client Side (JS)" }, { "/web/reference/validators/custom", "Custom Server Side (Erlang)" } ], @@ -66,10 +65,6 @@ column2() -> body() -> Term = get(term), - TransformSeeAlso = fun(SeeAlso, Acc) -> - SeeAlso1 = wf:to_list(SeeAlso), - {{SeeAlso1, SeeAlso1}, Acc, []} - end, #bind { data=[Term], @@ -78,11 +73,6 @@ body() -> #p{}, #span { class=reference_description, id=description, html_encode=false }, #p{}, - #span { class=reference_see_also_label, text="See also: " }, - #bind { id=see_also, data=[], map={link@text, link@url}, transform=TransformSeeAlso, - body=[#link { class=reference_see_also_link, id=link }, " "], - empty_body="-" - }, #h2{ text="Usage" }, #span { class=reference_usage, id=usage, html_encode=false }, #h2 { text="Attributes" }, Quickstart/src/reference/web_reference_validators.erl b6f927b4bffea9e8e9017b059077eae8d9478fd3 Rusty Klophaus rusty@RTK.local http://github.com/rklophaus/nitrogen/commit/003da14393616f411f08793b89e8d42658ebc3cb 003da14393616f411f08793b89e8d42658ebc3cb

2009-10-02T07:54:06-07:00

More documentation. 5b759598c63bffd3a415d953781d7d8886bc2a2c Rusty Klophaus rusty@RTK.local