<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- WebTool User Guide</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/webtool-0.8.9.1.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>WebTool</strong><br><strong>User's Guide</strong><br><small>Version 0.8.9.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu"><li id="loadscrollpos" title="WebTool User Guide" expanded="true">WebTool User Guide<ul>
<li><a href="webtool_chapter.html">
Top of chapter
</a></li>
<li title="Introduction "><a href="webtool_chapter.html#id61158">Introduction </a></li>
<li title="Starting WebTool"><a href="webtool_chapter.html#id61298">Starting WebTool</a></li>
<li title="Using WebTool"><a href="webtool_chapter.html#id57990">Using WebTool</a></li>
<li title="Start a web based tool"><a href="webtool_chapter.html#id61822">Start a web based tool</a></li>
<li title="Stop a web based tool"><a href="webtool_chapter.html#id61216">Stop a web based tool</a></li>
<li title="Develop new web based tools"><a href="webtool_chapter.html#id61239">Develop new web based tools</a></li>
</ul>
</li></ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 WebTool User Guide</h1>
<h3><a name="id61158">1.1
Introduction </a></h3>
<p>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.</p>
<p>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
<span class="code">ebin</span> directory in the path, the <span class="code">priv</span> directory is
also searched. The *.tool files contain the configuration data
for each web based tool.</p>
<h3><a name="id61298">1.2
Starting WebTool</a></h3>
<p>Start WebTool by calling the function <span class="code">webtool:start/0</span> or
<span class="code">webtool:start/2</span>. If <span class="code">webtool:start/0</span> is used the
start page of WebTool is available at
<strong>http://localhost:8888/</strong> or
<strong>http://127.0.0.1:8888/</strong>, and the directory containing
the root directory for the webserver, is assumed to be
<span class="code">webtool-<vsn>/priv</span>.</p>
<p>Use <span class="code">webtool:start/2</span> if the default path for the root
directory, port, ip-number or server name can not be used. See
the Reference Manual for <span class="bold_code"><a href="webtool.html">webtool</a></span> for more information.</p>
<p>WebTool, with the default configuration as in <span class="code">start/0</span>,
can also be started with the <span class="code">start_webtool</span> script which
is available in the <span class="code">priv</span> directory of the WebTool
application. See the Reference Manual for <span class="bold_code"><a href="start_webtool.html">start_webtool</a></span> for further
information about this script. For Windows users, the batch file
<span class="code">start_webtool.bat</span> can be used for the same purpose.</p>
<h3><a name="id57990">1.3
Using WebTool</a></h3>
<p>Start WebTool and point the browser to the corresponding URL.
At the top of the page there is a frame with a link named
<strong>WebTool</strong>. Click that link and a page where it is
possible to start the available tools will appear in the main
frame.</p>
<h3><a name="id61822">1.4
Start a web based tool</a></h3>
<p>Click on the link labeled <strong>WebTool</strong> in the topmost frame,
select the checkbox for each tool to start and
click on the button labeled <strong>Start</strong>. A link to each tool
that WebTool succeeded to start will appear in the topmost frame.</p>
<h3><a name="id61216">1.5
Stop a web based tool</a></h3>
<p>Click on the link labeled <strong>WebTool</strong> in the topmost
frame. Select <strong>Stop Tools</strong> in the left frame. Select the
checkbox for each tool to stop and click on the button labeled
<strong>Stop</strong>.</p>
<h3><a name="id61239">1.6
Develop new web based tools</a></h3>
<p>WebTool can be used as a framework when developing new web based
tools.</p>
<p>A web based tool running under WebTool will typically consist of
three parts.</p>
<ul>
<li>A *.tool file which defines how WebTool can find the tool's
configuration data</li>
<li>The Erlang code generating the web interface to the tool (HTML
code)</li>
<li>The tool itself.</li>
</ul>
<p>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.</p>
<h4>The *.tool file</h4>
<p>When WebTool starts it searches the current path for
<span class="code">*.tool</span> 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
<span class="code">config_func</span>. <span class="code">config_func</span> 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:</p>
<div class="example"><pre>
{version,"1.2"}.
[{config_func,{Module,Function,Arguments}}]. </pre></div>
<p><span class="code">Module</span> is the name of the module where the callback
function is defined. <span class="code">Function</span> is the name of the
callback function, and <span class="code">Arguments</span> is the list of
arguments to the callback function.</p>
<h4>The configuration function</h4>
<p>The *.tool file points out a configuration function. This
function must return a list of configuration parameters (see
the Reference Manual for <span class="bold_code"><a href="webtool.html">webtool</a></span>).</p>
<p>The <span class="code">web_data</span> 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.</p>
<p>If the tool requires any processes to run, the <span class="code">start</span>
parameter specifies the function that WebTool must call in
order to start the process(es).</p>
<p>The <span class="code">alias</span> 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.</p>
<p>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.</p>
<p>An URL which calls an Erlang function with Erl Scheme can have
the following syntax:</p>
<div class="example"><pre>
http://Servername:Port/ErlScriptAlias/Mod/Func<?QueryString> </pre></div>
<p>An <span class="code">alias</span> parameter in the configuration function can be
an ErlScriptAlias as used in the above URL. The definition of
an ErlScriptAlias shall be like this:</p>
<p><span class="code">{alias,{erl_alias,Path,[Modules]}}</span>, e.g.</p>
<p><span class="code">{alias,{erl_alias,"/testtool",[helloworld]}}</span></p>
<p>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):</p>
<p><span class="code">http://localhost:8888/testtool/helloworld/helloworld</span></p>
<p>Note that the module <span class="code">helloworld</span> must be in the code
path of the node running WebTool.</p>
<p>Functions that are called via the Erl Scheme must take two
arguments, <span class="code">Environment</span> and <span class="code">Input</span>.
</p>
<ul>
<li>
<span class="code">Environment</span> is a list of key/value tuples.</li>
<li>
<span class="code">Input</span> 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:
<br>
<span class="code">http://localhost:8888/testtool/helloworld/helloworld?input1=one&amp;input2=two</span> <br>
<span class="code">Input</span> will be the string
<span class="code">"input1=one&amp;input2=two"</span>. In the module
<span class="code">httpd</span> in the INETS application there is a function
<span class="code">parse_query</span> which will parse such a string and return
a list of key-value tuples.</li>
</ul>
<p>An <span class="code">alias</span> 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
<span class="code">http://localhost:8888/mytool_home/</span> really points to the
directory <span class="code">/usr/local/otp/lib/myapp-1.0/priv</span>:</p>
<p><span class="code">{alias,{"/mytool_home","/usr/local/otp/lib/myapp-1.0/priv"}}</span></p>
<p>See the INETS documentation, especially the module
<span class="code">mod_esi</span>, for a more in depth coverage of the Erl Scheme.</p>
<h4>A small example</h4>
<p>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 <span class="code">start</span> parameter in the
configuration function.
</p>
<p><strong>helloworld.erl:</strong></p>
<div class="example"><pre>
-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>".
</pre></div>
<p>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 <span class="code">helloworld.beam</span>.</p>
<p><strong>testtool.tool:</strong></p>
<div class="example"><pre>
{version,"1.2"}.
[{config_func, {helloworld,config_data,[]}}].
</pre></div>
<p>When <span class="code">helloworld.erl</span> is compiled, start WebTool by
calling the function <span class="code">webtool:start()</span> and point your
browser to <strong>http://localhost:8888/</strong>. Select WebTool in
the topmost frame and start TestTool from the web page. Click
on the link labeled <strong>TestTool</strong> in the topmost frame.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2001-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
1566
