<?xml version='1.0' ?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>


  <sect1 id="tutorial-newpackage">
    <title>Creating an Application Package</title>
    
    <authorblurb>
      <para>by <ulink url="mailto:joel@aufrecht.org">Joel Aufrecht</ulink></para>
    </authorblurb>
    
<sect2 id="tutorial-picture">
  <title>The intended page map</title>
  <mediaobject>
  <imageobject>
          <imagedata fileref="../images/openacs-best-practice.png" format="PNG"/>
  </imageobject>
  </mediaobject>
</sect2>

    <sect2>
      <title>Overview</title>
      <para>To start developing new code in OpenACS, we build a new package. A package 
      is a a discrete collection of web pages, tcl code, and database tables and procedures.
      A package with user interface is called an <emphasis role="strong">application</emphasis>; 
      a package which provides functions to other packages and has no direct interface, a
      <emphasis role="strong">service</emphasis>.  A package can be installed, upgraded, and 
      removed.  It communicates with other packages through an API.  This chapter walks you through 
      the minimum steps to create a useful package, including writing documentation, setting up 
      database tables and procedures, writing web pages, debugging, and automatic regression testing.
      </para>
      
      <para>
        This tutorial uses the content repository package.  This
        radically simplifies the database work, but forces us to work
        around the content repository's limitations, including an
        incomplete TCL API.  So the tutorial is messier than we'd like
        right now.  Code that is temporary hackage is clearly marked.
      </para>
      
    <para>In this tutorial, we will make an application package for
    displaying a list of text notes.
</para>
  </sect2>

  <sect2><title>Before you begin</title>
    <para>You will need:</para>
    <itemizedlist>
      <listitem><para>A computer with a working installation of
	  OpenACS.  If you don't have this, see <xref linkend="install-overview"/>.
	  </para></listitem>
      <listitem><para>Example files, which are included in the
standard OpenACS &version; distribution.
	  </para></listitem>
    </itemizedlist>
    <figure>
      <title>Assumptions in this section</title>
      <informaltable>
        <tgroup cols="2">
          <tbody>
            <row>
              <entry>Fully qualified domain name of your server</entry>
              <entry><replaceable>yourserver.test</replaceable></entry>
            </row>
            <row>
              <entry>URL of your server</entry>
              <entry><replaceable>http://yourserver.test:8000</replaceable></entry>
            </row>

            <row>
              <entry>Name of development account</entry>
              <entry><replaceable>$OPENACS_SERVICE_NAME</replaceable></entry>
            </row>
            <row>
              <entry>New Package key</entry>
              <entry><replaceable>myfirstpackage</replaceable></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </figure>
  </sect2>

  <sect2>
    <title>Use the APM to initialize a new package</title>
    <para>We use the <ulink url="packages.html">ACS Package Manager</ulink> (APM) to add, remove, and
    upgrade packages.  It handles package meta-data, such as lists of
    files that belong in the package.  Each package is uniquely
    identified by a package key.  To start developing a new
    package, use the APM to create an empty package with our new
    package key, <replaceable>myfirstpackage</replaceable>.  This will create
    the initial directories, meta-information files, and database
    entries for a new package.  (<ulink
    url="apm-requirements.html">More info on APM</ulink>)
</para>
    <orderedlist>
      <listitem>
        <para>Browse to
        <computeroutput>http://<replaceable>yourserver:8000</replaceable><ulink
        url="/acs-admin/apm">/acs-admin/apm</ulink></computeroutput>.
</para>
      </listitem>
      <listitem>
        <para>Click <computeroutput>Create a New Package</computeroutput>.</para>
        <para>Fill in the fields listed below.   <emphasis role="strong">Ignore the rest (and leave the check boxes alone).</emphasis>
        (Some will change automatically.  Don't mess with those.)
</para>
        <itemizedlist>
          <listitem><para>
              <computeroutput>Package Key</computeroutput>:
              <userinput>myfirstpackage</userinput></para>
            </listitem>
            <listitem><para>
              <computeroutput>Package Name</computeroutput>:
              <userinput>My First Package</userinput>
            </para></listitem>
            <listitem><para>
              <computeroutput>Package Plural</computeroutput>:
              <userinput>My First Package</userinput></para></listitem>
            <listitem><para>
              <computeroutput>Package Type</computeroutput>:
              <userinput>Application</userinput>
            </para></listitem>
            <listitem><para>	  
              <computeroutput>Initial Version</computeroutput>:
              <userinput>0.1d</userinput>
            </para></listitem>
            <listitem><para><computeroutput>Summary</computeroutput>:
              <userinput>This is my first package.</userinput>
            </para></listitem>
          </itemizedlist>
          <para>At the bottom, click
        <computeroutput><guibutton>Create Package</guibutton></computeroutput>.
        </para>
      </listitem>
    </orderedlist>
      <para>This creates a package rooted at
          <computeroutput>/var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/<replaceable>myfirstpackage</replaceable></computeroutput>.
          This is the "home directory" of our new package, and all
          files in the package will be within this directory. <ulink
          url="packages.html">More on the structure of
          packages</ulink>). </para>
    </sect2>
    <sect2>
      <title>Add an Application Instance to the Server</title>
      <para>In order to see your work in progress, you must create a
      map between the URL space of incoming requests and the package application instance.
      You do this by adding the application in the main site administration).  This
      creates a link between the incoming URL requests and an
      <emphasis>instance</emphasis> of the application.  (<ulink
      url="rp-design.html">More on applications and nodes</ulink>)</para>
      <para>You can have instances of a package on one site, each with a
      different URL and different permissions, all sharing the same
      code and tables.  This requires that a package be developed
      <emphasis>package-aware</emphasis>.  You'll see how to do that
      in this tutorial.</para>
      <orderedlist>
        <listitem><para>Browse to
<computeroutput><replaceable>http://yourserver.test:8000</replaceable><ulink
        url="/admin/applications/application-add">/admin/applications/application-add/</ulink></computeroutput>.</para>
        </listitem>
        <listitem>
          <para>Choose "My First Package" from the list and click OK (the other fields are optional).</para>
        </listitem>
      </orderedlist>
      <para>By mounting the package, we've caused all requests to
      <computeroutput>http://yourserver.test:8000/myfirstpackage</computeroutput>
      to be satisfied from the files at <computeroutput>/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www</computeroutput>.</para>
    </sect2>
    <sect2>
      <title>Quick start</title>
      <para>The remainder of the tutorial walks you through each file one at a time as you create the package.  You can skip all this, and get a working package, by doing the following:</para>
    <screen>cd /var/lib/aolserver/<replaceable>$OPENACS_SERVICE_NAME</replaceable>/packages/acs-core-docs/www/files/tutorial
psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f myfirstpackage-create.sql
cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/
mkdir ../../../../myfirstpackage/lib
cp note-list.* ../../../../myfirstpackage/lib/
cp myfirstpackage-*sql ../../../../myfirstpackage/sql/postgresql/
cp myfirstpackage-procs.tcl ../../../../myfirstpackage/tcl/test/
cp note-procs.tcl ../../../../myfirstpackage/tcl/</screen>
<para>After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.</para>
  </sect2>
  </sect1>
