Fetching contributors…
Cannot retrieve contributors at this time
281 lines (230 sloc) 9.29 KB
box(Str) ->
{pre,[], yaws_api:htmlize(Str)}}.
tbox(T) ->
ssi(File) ->
{ssi, File,[],[]}}}.
ss(A, File) ->
{ok, B} = file:read_file(
filename:join([A#arg.docroot, File])),
out(A) ->
[{ssi, "", "%%",[{"json_intro", "choosen"}]},
{'div', [{id, "entry"}],
[{h1, [], "AJAX through JSON RPC"},
{p, [],
{i, [],
["Note: this documentation used to refer to the module "
"'yaws_jsonrpc', but that module was deprecated in favor of "
"'yaws_rpc', which handles JSON RPC, haXe and SOAP remoting. "
"For more specific information about SOAP, refer to ",
{a, [{href, "/soap_intro.yaws"}], "the SOAP page."}]}},
{p, [],
["The Yaws JSON-RPC binding is a way to have JavaScript code in the "
"browser evaluate a remote procedure call (RPC) in the Yaws server. "
"JSON itself as described at ",
{a, [{href, ""}], " "},
"is basically a simple marshaling format which can be used "
"from a variety of different programming languages, and "
"naturally it's completely straightforward to implement "
"in JavaScript itself. JSON-RPC version 2.0, the version Yaws "
"supports, is described here:"]},
{p, [],
[{a, [{href,
{p, [],
"The Yaws JSON-RPC implementation consist of JavaScript clients and a "
"server side library that must be explicitly invoked by Erlang "
"code in a .yaws page, appmod, etc."},
"It is not particularly easy to show and explain an AJAX setup "
"through JSON-RPC, but here is an attempt:"
"First we have an HTML page which:"},
{ol, [],
["Includes the client side of the JSON library. "
"The library is included in the Yaws distribution "
"and it is found under ",
"\"www/jsolait/jsolait.js\""}, "."]}},
{li,[],{p,[],"Second, the HTML code defines the name of a method, "
"i.e. the name of a server-side function that shall be "
"called by the client side JavaScript code."}},
{li,[],{p,[],"Finally the HTML code defines a FORM that's "
"used to invoke the RPC. This is just a really simple "
"example, really any JavaScript code can invoke any RPC in "
"more interesting scenarios than submitting a form."}}]},
{p, [], "The HTML code appears as shown below:"},
{p, [], ["This HTML code resides in file ",
{a,[{href, "json_sample.html"}], "json_sample.html"},
" and it is the HTML code that is the AJAX GUI."]},
{p, [], "Following that we need to take a look at json_sample.yaws "
" (shown below), which is the \"serviceURL\" according to "
"the JavaScript code. This code defines the function to be "
"called. Remember that the JavaScript code defined one method, "
"called \"test1\"; this information will be passed to the "
"serviceURL. The code looks like:"},
ss(A, "json_sample.yaws"),
{p,[], "The two important lines on the server side are"},
{pre,[],"yaws_rpc:handler_session(A2, {sample_mod, counter})."}},
{pre,[],"counter([{ip, IP}] = _State, {call, test1, Value} = _Request, Session)"}}]},
["The first line tells Yaws to forward all JSON-RPC methods to the "
" \"counter\" function in the \"sample_mod\" module. "
"The second line is the head of the counter function that will be "
"called when the client invokes a method called 'test1'. We would "
"duplicate this line with a different name than 'test1' for each RPC "
"function we wish to implement. Note that the first atom in the "
"request tuple will either be 'call' or 'notification' to indicate "
"the type of request. As per the ",
"JSON-RPC 2.0 specification"},
", a 'call' is a regular request-reply while a 'notification' is a "
"one-way message that does not have a corresponding reply."]},
{p,[],"On the client side we have"},
var methods = [ \"test1\" ];
var jsonrpc = imprt(\"jsonrpc\");
var service = new jsonrpc.ServiceProxy(serviceURL, methods);
{p,[],"This registers the Yaws page with the JSON-RPC handler and "
"gives it a list of methods that the Yaws page can satisfy. "
"In this case, the only method called 'test1'."},
{p, [],
"When we wish to return structured data, we simply let "
"the user-defined RPC function return JSON structures such as "},
box("{struct, [{field1, \"foo\"}, {field2, \"bar\"}]} "),
{p, [], " for a structure and "},
box("{array, [\"foo\", \"bar\"]}"),
{p, [],"for an array. We can nest arrays and structs in each other."},
{p, [],
"Finally, we must stress that this example is extremely simple. "
"In order to build a proper AJAX application in Yaws, a lot of "
"client side work is required, all Yaws provides is the basic "
"mechanism whereby the client side JavaScript code can RPC the "
"web server for data which can be subsequently used to populate "
"the DOM. Also required to build a good AJAX application is "
"good knowledge of how the DOM in the browser works"},
{p, [],
["The yaws_rpc:handler will also call: M:F(cookie_expire) "
"which is expected to return a proper Cookie expire string. This "
"makes it possible to setup the Cookie lifetime. If this callback "
"function is non-existent, the default behaviour is to not set a "
"cookie expiration time, i.e., it will live for this session only."]},
{h3, [], "One more example "},
{p, [],
["Here is yet another example, stolen from ",
"Tobbe's blog."}
{h4, [], "Setup the DOM"},
{p, [], "In the file ''ex1.html'' we create the DOM with a little HTML and add some JavaScript that will talk with the Erlang server side."},
<script type=\"text/javascript\"
<script language=\"javascript\" type=\"text/javascript\">
function ex1(what) {
{'op': \"ex1\", 'what': what},
function(x) {
do_ex1(what, x)
function do_ex1(what, x) {
jQuery.each(x, doit);
function doit() {
<button onclick=\"ex1('one')\">Update one!</button>
<button onclick=\"ex1('two')\">Update two!</button>
<button onclick=\"ex1('three')\">Update three!</button>
<div id=\"one\">This is one</div>
<div id=\"two\">This is two</div>
<div id=\"three\">This is three</div>
{h4, [], "The erlang server side"},
{p, [], "This is the code that needs to be installed and "
"execute on the server side. It nicely illustrates how "
"to return JSON structs to the client. "},
out(A) ->
L = yaws_api:parse_query(A),
dispatch(lkup(\"op\", L, false), A, L).
dispatch(\"ex1\", A, L) ->
ex1(A, L).
ex1(_A, L) ->
J = json2:encode(array(what(lkup(\"what\", L, false)))),
what(\"one\") -> one();
what(\"two\") -> one() ++ two();
what(\"three\") -> one() ++ two() ++ three().
array(L) -> {array, L}.
one() -> obj(\"one\").
two() -> obj(\"two\").
three() -> obj(\"three\").
obj(M) ->
obj(M, \"r\").
%%% How ::= \"r\" | \"a\" , r=replace, a=append
obj(M, How) ->
C = now2str(),
[{\"who\", M},
{\"how\", How},
{\"what\", C ++\" \"++M++\" content\"}]}].
return_json(Json) ->
\"application/json; charset=iso-8859-1\",
now2str() ->
{A,B,C} = erlang:now(),
i2l(I) when is_integer(I) -> integer_to_list(I);
i2l(L) when is_list(L) -> L.
lkup(Key, List, Def) ->
case lists:keysearch(Key, 1, List) of
{value,{_,Value}} -> Value;
_ -> Def
") ,
{h2, [], "The json library"},
{p, [],
["The Yaws JSON library contains 3 simple functions, "
" one for encoding and two for decoding. See source code ",
" for detailed instructions on usage."]}
{ssi, "END2",[],[]}