![[Ericsson AB]](min_head.gif)
WebTool provides an easy and efficient way to implement web based tools with Erlang/OTP. WebTool configures and starts the webserver and the various web based tools.
All tools that shall run under WebTool must have a *.tool
file in the code path or in its priv directory. When WebTool
starts it searches the code path for such files. For each
ebin directory in the path, the priv directory is
also searched. The *.tool files contain the configuration data
for each web based tool.
Start WebTool by calling the function webtool:start/0 or
webtool:start/2. If webtool:start/0 is used the
start page of WebTool is available at
http://localhost:8888/ or
http://127.0.0.1:8888/, and the directory containing
the root directory for the webserver, is assumed to be
webtool-<vsn>/priv.
Use webtool:start/2 if the default path for the root
directory, port, ip-number or server name can not be used. See
the Reference Manual for webtool for more information.
WebTool, with the default configuration as in start/0,
can also be started with the start_webtool script which
is available in the priv directory of the WebTool
application. See the Reference Manual for start_webtool for further
information about this script. For Windows users, the batch file
start_webtool.bat can be used for the same purpose.
Start WebTool and point the browser to the corresponding URL. At the top of the page there is a frame with a link named WebTool. Click that link and a page where it is possible to start the available tools will appear in the main frame.
Click on the link labeled WebTool in the topmost frame, select the checkbox for each tool to start and click on the button labeled Start. A link to each tool that WebTool succeded to start will appear in the topmost frame.
Click on the link labeled WebTool in the topmost frame. Select Stop Tools in the left frame. Select the checkbox for each tool to stop and click on the button labeled Stop.
WebTool can be used as a framework when developing new web based tools.
A web based tool running under WebTool will typically consist of three parts.
In most cases it is a good idea to separate the code for creation of the html-pages and the code for the logic. This increases the readability of the code and the logic might be possible to reuse.
When WebTool starts it searches the current path for
*.tool files to find all available tools. The *.tool
file contains a version identifier and a list of tuples which
is the configuration data. The version identifier specifies
the *.tool file version, i.e. not the version of
webtool. Currently the only valid version is "1.2" and the
only valid configuration tag is
config_func. config_func specifies which
function WebTool must call to get further configuration data
for the tool. This means that a *.tool file generally must
look like this:
{version,"1.2"}.
[{config_func,{Module,Function,Arguments}}].
Module is the name of the module where the callback
function is defined. Function is the name of the
callback function, and Arguments is the list of
arguments to the callback function.
The *.tool file points out a configuration function. This function must return a list of configuration parameters (see the Reference Manual for webtool).
The web_data parameter is mandatory and it specifies
the name of the tool and the link to the tool's start
page. All other parameters are optional.
If the tool requires any processes to run, the start
parameter specifies the function that WebTool must call in
order to start the process(es).
The alias parameters are passed directly on to the
webserver (INETS). The webserver has three ways to create
dynamic web pages CGI, Eval Scheme and Erl Scheme. All tools
running under WebTool must use Erl Scheme.
Erl Scheme tries to resemble plain CGI. The big difference is that Erl Scheme can only execute Erlang code. The code will furthermore be executed on the same instance as the webserver.
An URL which calls an Erlang function with Erl Scheme can have the following syntax:
http://Servername:Port/ErlScriptAlias/Mod/Func<?QueryString>
An alias parameter in the configuration function can be
an ErlScriptAlias as used in the above URL. The definition of
an ErlScripAlias shall be like this:
{alias,{erl_alias,Path,[Modules]}}, e.g.
{alias,{erl_alias,"/testtool",[helloworld]}}
The following URL will then cause a call to the function helloworld:helloworld/2 (if WebTool is started with default settings i.e. servername "localhost" and port 8888):
http://localhost:8888/testtool/helloworld/helloworld
Note that the module helloworld must be in the code
path of the node running WebTool.
Functions that are called via the Erl Scheme must take two
arguments, Environment and Input.
Environment is a list of key/value tuples.
Input is the part of the URL after the "?", i.e. the
part of the URL containing name-value pairs. If the page was
called with the URL:
http://localhost:8888/testtool/helloworld/helloworld?input1=one&input2=two
Input will be the string
"input1=one&input2=two". In the module
httpd in the INETS application there is a function
parse_query which will parse such a string and return
a list of key-value tuples.
An alias parameter in the configuration function can
also be a normal path alias. This can e.g. be used to point
out a directory where HTML files are stored. The following
definition states that the URL
http://localhost:8888/mytool_home/ really points to the
directory /usr/local/otp/lib/myapp-1.0/priv:
{alias,{"/mytool_home","/usr/local/otp/lib/myapp-1.0/priv"}}
See the INETS documentation, especially the module
mod_esi, for a more in depht coverage of Erl Scheme.
A Hello World example that uses Erl Scheme would look like
this. Note that this example does not have a process running
and thus does not need a start parameter in the
configuration function.
helloworld.erl:
-module(helloworld).
-export([config_data/0]).
-export([helloworld/2]).
config_data()->
{testtool,
[{web_data,{"TestTool","/testtool/helloworld/helloworld"}},
{alias,{erl_alias,"/testtool",[helloworld]}}]}.
helloworld(_Env,_Input)->
[header(),html_header(),helloworld_body(),html_end()].
header() ->
header("text/html").
header(MimeType) ->
"Content-type: " ++ MimeType ++ "\r\n\r\n".
html_header() ->
"<HTML>
<HEAD>
<TITLE>Hello world Example </TITLE>
</HEAD>\n".
helloworld_body()->
"<BODY>Hello World</BODY>".
html_end()->
"</HTML>".
To use this example with WebTool a *.tool file must be created
and added to a directory in the current path, e.g. the same
directory as the compiled helloworld.beam.
testtool.tool:
{version,"1.2"}.
[{config_func, {helloworld,config_data,[]}}].
When helloworld.erl is compiled, start WebTool by
calling the function webtool:start() and point your
browser to http://localhost:8888/. Select WebTool in
the topmost frame and start TestTool from the web page. Click
on the link labeled TestTool in the topmost frame.