<?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>
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions 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>

