<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2001</year>
<year>2013</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
The Initial Developer of the Original Code is Ericsson AB.
</legalnotice>
<title>webtool</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<module>webtool</module>
<modulesummary>WebTool is a tool used to simplify the implementation of web based tools with Erlang/OTP.</modulesummary>
<description>
<p>WebTool makes it easy to use web based tools with Erlang/OTP. WebTool
configures and starts the webserver httpd.</p>
</description>
<funcs>
<func>
<name>start()-> {ok,Pid}| {stop,Reason}</name>
<fsummary>Start WebTool.</fsummary>
<desc>
<p>Start WebTool with default data, i.e. port 8888, ip-number
127.0.0.1, and server-name <c>localhost</c>. If port 8888 is
in use, port 8889 is tried instead. If 8889 is also in use,
8890 is tried and so on. Max number of ports tried is 256.
</p>
<p>The <c>mime.types</c> file and WebTool's own HTML files
are assumed to be in the directory
<c><![CDATA[webtool-<vsn>/priv/root/conf]]></c>.</p>
</desc>
</func>
<func>
<name>start(Path,Data)->{ok,Pid}|{stop,Reason}</name>
<fsummary>Start WebTool with default configuration.</fsummary>
<type>
<v>Path = string() | standard_path</v>
<v>Data = [Port,Address,Name] | PortNumber | standard_data</v>
<v>Port = {port,PortNumber}</v>
<v>Address = {bind_address,IpNumber}</v>
<v>Name = {server_name,ServerName}</v>
<v>PortNumber = integer()</v>
<v>IpNumber = tuple(), e.g. {127,0,0,1}</v>
<v>ServerName = string()</v>
<v>Pid = pid()</v>
</type>
<desc>
<p>Use this function to start WebTool if the default port,
ip-number,servername or path can not be used.</p>
<p><c>Path</c> is the directory where the <c>mime.types</c>
file and WebTool's own HTML files are located. By default
this is <c><![CDATA[webtool-<vsn>/priv]]></c>, and in most cases there
is no need to change this. If <c>Path</c> is set to
<c>standard_path</c> the default will be used.</p>
<p>If <c>Data</c> is set to <c>PortNumber</c>, the default data
will be used for ip-number (<c>127.0.0.1</c>) and server
name (<c>localhost</c>).</p>
</desc>
</func>
<func>
<name>stop()->void</name>
<fsummary>Stop WebTool.</fsummary>
<desc>
<p>Stop WebTool and the tools started by WebTool.</p>
</desc>
</func>
<func>
<name>debug_app(Module)->void</name>
<fsummary>Debug a WebTool application.</fsummary>
<type>
<v>Module = atom()</v>
</type>
<desc>
<p>Debug a WebTool application by tracing all functions in the
given module which are called from WebTool.</p>
</desc>
</func>
<func>
<name>stop_debug()->void</name>
<fsummary>Stop debugging an application and format the trace log.</fsummary>
<desc>
<p>Stop the tracing started by <c>debug_app/1</c>, and format
the trace log.</p>
</desc>
</func>
</funcs>
<section>
<title>CALLBACK FUNCTIONS</title>
<p>The following callback function must be implemented by each web
based tool that will be used via WebTool. When started, WebTool
searches the Erlang code path for *.tool files to locate all web
based tools and their callback functions. See the <seealso marker="webtool_chapter">WebTool User's Guide</seealso> for more
information about the *.tool files.</p>
</section>
<funcs>
<func>
<name>Module:Func(Data)-> {Name,WebData}|error</name>
<fsummary>Returns configuration data needed by WebTool to configure and start a tool.</fsummary>
<type>
<v>Data = term()</v>
<v>Name = atom()</v>
<v>WebData = [WebOptions]</v>
<v>WebOptions = LinkData | Alias | Start</v>
<v>LinkData = {web_data,{ToolName,Url}}</v>
<v>Alias = {alias,{VirtualPath,RealPath}} | {alias,{erl_alias,Path,[Modules]}</v>
<v>Start = {start,StartData}</v>
<v>ToolName = Url = VirtualPath = RealPath = Path = string()</v>
<v>Modules = atom()</v>
<v>StartData = AppData | ChildSpec | Func</v>
<v>AppData = {app,AppName}</v>
<v>ChildSpec = {child,child_spec()}</v>
<d>See the Reference Manual for the module supervisor in the STDLIB application for details about child_spec().</d>
<v>Func = {func,{StartMod,StartFunc,StartArg}, {StopMod,StopFunc,StopArg}}</v>
<v>AppName = StartMod = StartFunc = StopMod = StopFunc =atom()</v>
<v>StartArg = StopArg = [term()]</v>
</type>
<desc>
<p>This is the configuration function (<c>config_func</c>)
which must be stated in the <c>*.tool</c> file.</p>
<p>The function is called by WebTool at startup to retrieve the
data needed to start and configure the tool. <c>LinkData</c> is
used by WebTool to create the link to the tool. <c>Alias</c> is
used to create the aliases needed by the webserver. <c>Start</c>
is used to start and stop the tool.</p>
</desc>
</func>
</funcs>
<section>
<title>See Also</title>
<p><seealso marker="start_webtool">start_webtool(1)</seealso>,
<seealso marker="webtool_chapter">WebTool User's Guide</seealso></p>
</section>
</erlref>
