Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
182 lines (166 sloc) 7.73 KB
box(Str) ->
{pre,[], yaws_api:htmlize(Str)}}.
tbox(T) ->
out(A) ->
[{ssi, "", "%%",[{"yapp_intro", "choosen"}]},
{'div', [{id, "entry"}],
[{h1, [], "Yaws applications - Yapps"},
{p, [],
"Yaws applications, Yapps, are actually ordinary Erlang/OTP "
"applications with some optional information in their "
".app files and the web pages in the priv/docroot directory "
"as default. The Yaws applications handler takes care of adding, "
"and removing, the applications into a running server. "
" When anyone access the server with an URL that matches the path for an "
" added application, the docroot will be temporarily switched to where the web "
" pages for that application are located."},
{h2,[], "Using the application handler"},
{h3,[], "Installing"},
{p, [],
["The application handler is named just yapp and is located in the "
"directory yaws/applications/yapp. Yaws itself should have been built first, "
"then in the yapp directory we do",
{ol, [],[
{li,[],{pre,[], "make"}},
{li,[],[{pre,[], "make docs"}," - if we want documentation"]},
{li,[],[{pre,[], "make install"}," - unless yaws was installed with make local_install"]}
{h3,[], "Setting up yaws.conf"},
{p,[], "First we include the ebin directory of the yapp handler "
"application by adding the line "
box("ebin_dir = /<yaws_root>/{applications,lib}/yapp/ebin"),
"The \"applications\" part is used for a local_installed Yaws, and \"lib\""
" for a real installed one. Then we make sure that the yapp handler "
" application is started when Yaws is started, by using the runmod directive"},
box("runmod = yapp"),
"For every virtual server that we want to use yapps we add yapp as an "
"arg_rewrite_mod and set the opaque parameter yapp_server_id to a unique "
<server myexternalserver>
port = 8000
listen =
docroot = /yawsdocrootpath/www
arg_rewrite_mod = yapp
yapp_server_id = edo
"The web applications that are configured in the Yapp registry will be loaded "
"into Yaws configuration when the yapp application is started. A prerequisite "
"is that the applications are found in the Erlang code loader path. There is "
"also an option to define yapps in yaws.conf for every server directly by using "
"the opaque parameter bootstrap_yapps = webapp1, webapp2 etc. "},
"For instance the yapp handler application (named yapp) is a yapp in itself, "
"got it?, that provides a web gui to list active yapps and add/remove yapps "
"from the registry. But since we can not add itself to the registry before it "
"is added we have to bootstrap into the server when Yaws is started. "},
<server myinternalserver>
port = 8001
listen =
docroot = /docrootpath/www
arg_rewrite_mod = yapp
yapp_server_id = ido
bootstrap_yapps = yapp
"The current default Yapp registry implementation uses Mnesia, we have made "
"it easy to plug in other future registry implementations by configuring the "
" file, but Mnesia is recommended to be future proof for clustered "
"application servers. In order to use mnesia one has to prepare a schema, "
"we start an erlang shell with the same node name as Yaws is using: "},
"erl -sname node_name
1> mnesia:create_schema([node()])."}},
{p,[],["(we can leave out the -sname options, then the mnesia schema name will "
"be \"nonode@nohost\") then we exit and start yaws with the same name: ",
{pre,[],"yaws -sname node_name"}]},
{p,[],["Now we can access the yapp handler web console from a browser with url:",
{h2,[],"Making yapps"},
[ "In order to make a \"yapp\" we need to know how to make an ordinary Erlang "
"application, that is we will need a directory layout as specified by the ",
"design principles"},
" and a proper file in the ebin directory. "
"Yaws itself or yapp are standard applications and can serve as introductionary "
"examples. "]},
{h3,[], "Internal paths"},
"Making paths to other documents in the same web application using root paths "
"like href=\"/doc2.html\" will not work since a yapp is always below the top. "
"Instead use relative paths href=\"doc2.html\" or use the prepath library "
"function in any .yaws file: href=yapp:prepath(A) ++ \"doc2.html\", "
"where A is a <code>#arg</code> record."},
"The yapp handler takes care of throwing in \"private\" appmods for a yapp "
"when it is accessed. The appmods modules are put in the applications ebin "
"directory as any other Erlang module and configured in the .app file "
"with the the environment variable yapp_appmods. For instance; if we "
"have a yapp named yappx with root path \"/yappx\" and add: "},
{env, [
{p,[],"to the env part in the file, an access to the URL "
"http://servername/yappx/ctrl will cause a call to the "
"yappx_controller:out/1 function, while http://servername/yappy/ctrl "
"will not do it. "
{h3,[],"Opaque variables"},
"In a similar way the yapp handler adds \"private\" opaques for a yapp "
"with the the environment variable yapp_opaque. "
"As an example ", {a,[{href,""}], "ErlyWeb "},
"applications uses both appmods and opaques in yaws.conf. These can "
"be put in the .app file instead if one makes a yapp of it:"]},
{application, myapp1,
[{description,\"myapp1 is an erlyweb yapp\"},
{registered, []},
% {mod,{myapp1_app,[]}}, %% Only needed if the application needs to be started
{env, [
{p,[],"Also note that the docroot is www instead of the default priv/docroot in "
"ErlyWeb applications."},
{p,[],"Embedded ssi directives in ehtml parts will not work for now."},
"It may look as an extra complexity to use Erlang applications but in this way "
"we can benefit from Erlangs own framework for application handling. For instance, "
"in the future we hope to add features for release handling to "
"add/remove/upgrade/downgrade yapps on a running Yaws server, or even many clustered "
"servers. "}
{ssi, "END2",[],[]}
Jump to Line
Something went wrong with that request. Please try again.