path: root/lib/webtool/doc/src/webtool_chapter.xml

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2001</year><year>2011</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.
    
    </legalnotice>

    <title>WebTool User Guide</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>webtool_chapter.xml</file>
  </header>

  <section>
    <title>Introduction </title>
    <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
      <c>ebin</c> directory in the path, the <c>priv</c> directory is
      also searched. The *.tool files contain the configuration data
      for each web based tool.</p>
  </section>

  <section>
    <title>Starting WebTool</title>
    <p>Start WebTool by calling the function <c>webtool:start/0</c> or
      <c>webtool:start/2</c>.  If <c>webtool:start/0</c> is used the
      start page of WebTool is available at
      <em>http://localhost:8888/</em> or
      <em>http://127.0.0.1:8888/</em>, and the directory containing
      the root directory for the webserver, is assumed to be
      <c><![CDATA[webtool-<vsn>/priv]]></c>.</p>
    <p>Use <c>webtool:start/2</c> if the default path for the root
      directory, port, ip-number or server name can not be used. See
      the Reference Manual for <seealso marker="webtool">webtool</seealso> for more information.</p>
    <p>WebTool, with the default configuration as in <c>start/0</c>,
      can also be started with the <c>start_webtool</c> script which
      is available in the <c>priv</c> directory of the WebTool
      application. See the Reference Manual for <seealso marker="start_webtool">start_webtool</seealso> for further
      information about this script. For Windows users, the batch file
      <c>start_webtool.bat</c> can be used for the same purpose.</p>
  </section>

  <section>
    <title>Using WebTool</title>
    <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 
      <em>WebTool</em>. Click that link and a page where it is
      possible to start the available tools will appear in the main
      frame.</p>
  </section>

  <section>
    <title>Start a web based tool</title>
    <p>Click on the link labeled <em>WebTool</em> in the topmost  frame,
      select the checkbox for each tool to start and
      click on the button labeled <em>Start</em>. A link to each tool
      that WebTool succeeded to start will appear in the topmost frame.</p>
  </section>

  <section>
    <title>Stop a web based tool</title>
    <p>Click on the link labeled <em>WebTool</em> in the topmost
      frame. Select <em>Stop Tools</em> in the left frame. Select the
      checkbox for each tool to stop and click on the button labeled
      <em>Stop</em>.</p>
  </section>

  <section>
    <title>Develop new web based tools</title>
    <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>
    <list type="bulleted">
      <item>A *.tool file which defines how WebTool can find the tool's
       configuration data</item>
      <item>The Erlang code generating the web interface to the tool (HTML
       code)</item>
      <item>The tool itself.</item>
    </list>
    <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>

    <section>
      <title>The *.tool file</title>
      <p>When WebTool starts it searches the current path for
        <c>*.tool</c> 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
        <c>config_func</c>. <c>config_func</c> 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>
      <code type="none">
   {version,"1.2"}.
   [{config_func,{Module,Function,Arguments}}].      </code>
      <p><c>Module</c> is the name of the module where the callback
        function is defined. <c>Function</c> is the name of the
        callback function, and <c>Arguments</c> is the list of
        arguments to the callback function.</p>
    </section>

    <section>
      <title>The configuration function</title>
      <p>The *.tool file points out a configuration function. This
        function must return a list of configuration parameters (see
        the Reference Manual for <seealso marker="webtool">webtool</seealso>).</p>
      <p>The <c>web_data</c> 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 <c>start</c>
        parameter specifies the function that WebTool must call in
        order to start the process(es).</p>
      <p>The <c>alias</c> 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>
      <code type="none"><![CDATA[
http://Servername:Port/ErlScriptAlias/Mod/Func<?QueryString>      ]]></code>
      <p>An <c>alias</c> 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><c>{alias,{erl_alias,Path,[Modules]}}</c>, e.g.</p>
      <p><c>{alias,{erl_alias,"/testtool",[helloworld]}}</c></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><c>http://localhost:8888/testtool/helloworld/helloworld</c></p>
      <p>Note that the module <c>helloworld</c> 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, <c>Environment</c> and <c>Input</c>. 
        </p>
      <list type="bulleted">
        <item><c>Environment</c> is a list of key/value tuples.</item>
        <item><c>Input</c> 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></br>
<c><![CDATA[http://localhost:8888/testtool/helloworld/helloworld?input1=one&amp;input2=two]]></c>        <br></br>
<c>Input</c> will be the string
        <c><![CDATA["input1=one&amp;input2=two"]]></c>.  In the module
        <c>httpd</c> in the INETS application there is a function
        <c>parse_query</c> which will parse such a string and return
         a list of key-value tuples.</item>
      </list>
      <p>An <c>alias</c> 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
        <c>http://localhost:8888/mytool_home/</c> really points to the
        directory <c>/usr/local/otp/lib/myapp-1.0/priv</c>:</p>
      <p><c>{alias,{"/mytool_home","/usr/local/otp/lib/myapp-1.0/priv"}}</c></p>
      <p>See the INETS documentation, especially the module
        <c>mod_esi</c>, for a more in depth coverage of the Erl Scheme.</p>
    </section>

    <section>
      <title>A small example</title>
      <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 <c>start</c> parameter in the
        configuration function.
        </p>
      <p><em>helloworld.erl:</em></p>
      <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)-&gt;
            [header(),html_header(),helloworld_body(),html_end()].

        header() -&gt;
            header("text/html").

        header(MimeType) -&gt;
            "Content-type: " ++ MimeType ++ "\r\n\r\n".

        html_header() -&gt;    
            "&lt;HTML&gt;
               &lt;HEAD&gt;
                  &lt;TITLE&gt;Hello world Example &lt;/TITLE&gt;
               &lt;/HEAD&gt;\n".

        helloworld_body()-&gt;
            "&lt;BODY&gt;Hello World&lt;/BODY&gt;".

        html_end()-&gt;
            "&lt;/HTML&gt;".
      </pre>
      <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 <c>helloworld.beam</c>.</p>
      <p><em>testtool.tool:</em></p>
      <code type="none">
        {version,"1.2"}.
        [{config_func, {helloworld,config_data,[]}}].
      </code>
      <p>When <c>helloworld.erl</c> is compiled, start WebTool by
        calling the function <c>webtool:start()</c> and point your
        browser to <em>http://localhost:8888/</em>. Select WebTool in
        the topmost frame and start TestTool from the web page.  Click
        on the link labeled <em>TestTool</em> in the topmost frame.</p>
    </section>
  </section>
</chapter>