1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>WebTool User Guide</title>
34
<title>Introduction </title>
35
<p>WebTool provides an easy and efficient way to implement web
36
based tools with Erlang/OTP. WebTool configures and starts the
37
webserver and the various web based tools.</p>
38
<p>All tools that shall run under WebTool must have a *.tool
39
file in the code path or in its priv directory. When WebTool
40
starts it searches the code path for such files. For each
41
<c>ebin</c> directory in the path, the <c>priv</c> directory is
42
also searched. The *.tool files contain the configuration data
43
for each web based tool.</p>
47
<title>Starting WebTool</title>
48
<p>Start WebTool by calling the function <c>webtool:start/0</c> or
49
<c>webtool:start/2</c>. If <c>webtool:start/0</c> is used the
50
start page of WebTool is available at
51
<em>http://localhost:8888/</em> or
52
<em>http://127.0.0.1:8888/</em>, and the directory containing
53
the root directory for the webserver, is assumed to be
54
<c><![CDATA[webtool-<vsn>/priv]]></c>.</p>
55
<p>Use <c>webtool:start/2</c> if the default path for the root
56
directory, port, ip-number or server name can not be used. See
57
the Reference Manual for <seealso marker="webtool">webtool</seealso> for more information.</p>
58
<p>WebTool, with the default configuration as in <c>start/0</c>,
59
can also be started with the <c>start_webtool</c> script which
60
is available in the <c>priv</c> directory of the WebTool
61
application. See the Reference Manual for <seealso marker="start_webtool">start_webtool</seealso> for further
62
information about this script. For Windows users, the batch file
63
<c>start_webtool.bat</c> can be used for the same purpose.</p>
67
<title>Using WebTool</title>
68
<p>Start WebTool and point the browser to the corresponding URL.
69
At the top of the page there is a frame with a link named
70
<em>WebTool</em>. Click that link and a page where it is
71
possible to start the available tools will appear in the main
76
<title>Start a web based tool</title>
77
<p>Click on the link labeled <em>WebTool</em> in the topmost frame,
78
select the checkbox for each tool to start and
79
click on the button labeled <em>Start</em>. A link to each tool
80
that WebTool succeded to start will appear in the topmost frame.</p>
84
<title>Stop a web based tool</title>
85
<p>Click on the link labeled <em>WebTool</em> in the topmost
86
frame. Select <em>Stop Tools</em> in the left frame. Select the
87
checkbox for each tool to stop and click on the button labeled
92
<title>Develop new web based tools</title>
93
<p>WebTool can be used as a framework when developing new web based
95
<p>A web based tool running under WebTool will typically consist of
97
<list type="bulleted">
98
<item>A *.tool file which defines how WebTool can find the tool's
99
configuration data</item>
100
<item>The Erlang code generating the web interface to the tool (HTML
102
<item>The tool itself.</item>
104
<p>In most cases it is a good idea to separate the code for
105
creation of the html-pages and the code for the logic. This
106
increases the readability of the code and the logic might be
107
possible to reuse.</p>
110
<title>The *.tool file</title>
111
<p>When WebTool starts it searches the current path for
112
<c>*.tool</c> files to find all available tools. The *.tool
113
file contains a version identifier and a list of tuples which
114
is the configuration data. The version identifier specifies
115
the *.tool file version, i.e. not the version of
116
webtool. Currently the only valid version is "1.2" and the
117
only valid configuration tag is
118
<c>config_func</c>. <c>config_func</c> specifies which
119
function WebTool must call to get further configuration data
120
for the tool. This means that a *.tool file generally must
124
[{config_func,{Module,Function,Arguments}}]. </code>
125
<p><c>Module</c> is the name of the module where the callback
126
function is defined. <c>Function</c> is the name of the
127
callback function, and <c>Arguments</c> is the list of
128
arguments to the callback function.</p>
132
<title>The configuration function</title>
133
<p>The *.tool file points out a configuration function. This
134
function must return a list of configuration parameters (see
135
the Reference Manual for <seealso marker="webtool">webtool</seealso>).</p>
136
<p>The <c>web_data</c> parameter is mandatory and it specifies
137
the name of the tool and the link to the tool's start
138
page. All other parameters are optional.</p>
139
<p>If the tool requires any processes to run, the <c>start</c>
140
parameter specifies the function that WebTool must call in
141
order to start the process(es).</p>
142
<p>The <c>alias</c> parameters are passed directly on to the
143
webserver (INETS). The webserver has three ways to create
144
dynamic web pages CGI, Eval Scheme and Erl Scheme. All tools
145
running under WebTool must use Erl Scheme.</p>
146
<p>Erl Scheme tries to resemble plain CGI. The big difference is
147
that Erl Scheme can only execute Erlang code. The code will
148
furthermore be executed on the same instance as the webserver.</p>
149
<p>An URL which calls an Erlang function with Erl Scheme can have
150
the following syntax:</p>
151
<code type="none"><![CDATA[
152
http://Servername:Port/ErlScriptAlias/Mod/Func<?QueryString> ]]></code>
153
<p>An <c>alias</c> parameter in the configuration function can be
154
an ErlScriptAlias as used in the above URL. The definition of
155
an ErlScripAlias shall be like this:</p>
156
<p><c>{alias,{erl_alias,Path,[Modules]}}</c>, e.g.</p>
157
<p><c>{alias,{erl_alias,"/testtool",[helloworld]}}</c></p>
158
<p>The following URL will then cause a call to the function
159
helloworld:helloworld/2 (if WebTool is started with default
160
settings i.e. servername "localhost" and port 8888):</p>
161
<p><c>http://localhost:8888/testtool/helloworld/helloworld</c></p>
162
<p>Note that the module <c>helloworld</c> must be in the code
163
path of the node running WebTool.</p>
164
<p>Functions that are called via the Erl Scheme must take two
165
arguments, <c>Environment</c> and <c>Input</c>.
167
<list type="bulleted">
168
<item><c>Environment</c> is a list of key/value tuples.</item>
169
<item><c>Input</c> is the part of the URL after the "?", i.e. the
170
part of the URL containing name-value pairs. If the page was
173
<c><![CDATA[http://localhost:8888/testtool/helloworld/helloworld?input1=one&input2=two]]></c> <br></br>
174
<c>Input</c> will be the string
175
<c><![CDATA["input1=one&input2=two"]]></c>. In the module
176
<c>httpd</c> in the INETS application there is a function
177
<c>parse_query</c> which will parse such a string and return
178
a list of key-value tuples.</item>
180
<p>An <c>alias</c> parameter in the configuration function can
181
also be a normal path alias. This can e.g. be used to point
182
out a directory where HTML files are stored. The following
183
definition states that the URL
184
<c>http://localhost:8888/mytool_home/</c> really points to the
185
directory <c>/usr/local/otp/lib/myapp-1.0/priv</c>:</p>
186
<p><c>{alias,{"/mytool_home","/usr/local/otp/lib/myapp-1.0/priv"}}</c></p>
187
<p>See the INETS documentation, especially the module
188
<c>mod_esi</c>, for a more in depht coverage of Erl Scheme.</p>
192
<title>A small example</title>
193
<p>A Hello World example that uses Erl Scheme would look like
194
this. Note that this example does not have a process running
195
and thus does not need a <c>start</c> parameter in the
196
configuration function.
198
<p><em>helloworld.erl:</em></p>
201
\011-export([config_data/0]).
202
\011-export([helloworld/2]).
206
\011 [{web_data,{"TestTool","/testtool/helloworld/helloworld"}},
207
\011 {alias,{erl_alias,"/testtool",[helloworld]}}]}.
209
\011helloworld(_Env,_Input)->
210
\011 [header(),html_header(),helloworld_body(),html_end()].
213
\011 header("text/html").
215
\011header(MimeType) ->
216
\011 "Content-type: " ++ MimeType ++ "\\r\
220
\011html_header() ->
223
\011 <TITLE>Hello world Example </TITLE>
227
\011helloworld_body()->
228
\011 "<BODY>Hello World</BODY>".
231
\011 "</HTML>".
233
<p>To use this example with WebTool a *.tool file must be created
234
and added to a directory in the current path, e.g. the same
235
directory as the compiled <c>helloworld.beam</c>.</p>
236
<p><em>testtool.tool:</em></p>
239
[{config_func, {helloworld,config_data,[]}}].
241
<p>When <c>helloworld.erl</c> is compiled, start WebTool by
242
calling the function <c>webtool:start()</c> and point your
243
browser to <em>http://localhost:8888/</em>. Select WebTool in
244
the topmost frame and start TestTool from the web page. Click
245
on the link labeled <em>TestTool</em> in the topmost frame.</p>
added
removed
lib/webtool/doc/src/webtool_chapter.xml
