<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">

<book>
  <title>Tutorial Application</title>
  <bookinfo>
    <revhistory>
      <revision>
        <revnumber>1</revnumber>
        <date>27 Dec 2002</date>
        <authorinitials>Joel Aufrecht</authorinitials>
        <revremark>First Draft</revremark>
      </revision>
    </revhistory>
    <pubdate role="cvstag">($Id: package-documentation.xml,v 1.2 2003/04/28 04:02:44 joela Exp $)</pubdate>
    <authorgroup>
      <author>
	<firstname>Joel</firstname>
	<surname>Aufrecht</surname>
	<affiliation>
          <address><email>joel@aufrecht.org</email></address>
	</affiliation>
      </author>
    </authorgroup>
  </bookinfo>
  <chapter id="requirements" xreflabel="Requirements">
    <title>Requirements</title>

    <sect1 id="requirements-introduction">
      <title>Introduction</title>
      <para>
        This package lets users post blocks of text to the web, which
        others can then read.  It integrates with full text search.
        It is intended to show new developers how to accomplish basic
        tasks with OpenACS.
      </para>
    </sect1>
    <sect1 id="requirements-overview">
      <title>Overview</title>
      <para></para>

      <para>
        This package has a simple data component: text notes, stored
        in a table in the database.  The other component is the user
        interface.  It also needs support Full Text Search.  There is
        no administrative interface.
      </para>
      <para>
        This package depends on the core OpenACS functionality and on
        OpenFTS.  It is PostGreSQL-only - it has not been ported to
        Oracle.
      </para>
      <para>
        OpenFTS is the third-party PostGreSQL full text search engine.
      </para>
    </sect1>
    
    <sect1 id="requirements-cases">
      <title>Use-cases and User-scenarios</title>
      <itemizedlist>
        <listitem>
          <formalpara>
            <title>Author</title>
            <para>Authors write notes, which comprise titles and
            bodies, both of plain text.  Currently authors do this by
            ftping files to a web server, which generates many support
            calls.</para>
          </formalpara>
          <orderedlist>
            <listitem>
              <para>An Author creates a new note, such as the following:</para>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="sample.png" format="PNG"/>
                </imageobject>
                <textobject>
                  <formalpara>
                    <title>Hello World</title>
                    <para>This is my first OpenACS package.</para>
                  </formalpara>
                </textobject>
              </mediaobject>
            </listitem>
            <listitem>
              <para>An Author changes a note previously written.
              Authors can't change other authors' notes.</para>
            </listitem>
            <listitem>
              <para>An Author deletes a note that is no longer
              needed.  Unless explicitly deleted, notes should never disappear.</para>
            </listitem>
          </orderedlist>
        </listitem>
        <listitem>
          <formalpara>
            <title>Reader</title>
            <para>Readers can see all of the existing notes.
            Currently readers browse to a web page and read the
            notes.  They use the browser search function to find notes
            of interest.</para>
          </formalpara>
          <orderedlist>
            <listitem>
              <para>An Reader browses the notes.</para>
            </listitem>
            <listitem>
              <para>An Reader searches for notes.</para>
            </listitem>
          </orderedlist>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1>
      <title>Prioritized Requirements</title>

      <sect2>
        <title>System Interfaces</title>
        <sect3>
          <title>Full Text Search</title>
          <para>All text entered into the package should be searchable
          via OpenFTS.  The OpenFTS interface is specified at ???.
</para>
          <segmentedlist>
            <?dbhtml list-presentation="table"?>
            <segtitle>Number</segtitle>
            <segtitle>Priority</segtitle>
            <segtitle>Description</segtitle>
            <seglistitem><seg>100</seg><seg>A</seg><seg>The Title and
            Body fields are indexed by Full Text Search.</seg></seglistitem>
          </segmentedlist>
        </sect3>
      </sect2>

      <sect2>
        <title>User Interfaces</title>
        <sect3>
          <title>User 1 Interface</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="user-interface.png" format="PNG"/>
            </imageobject>
            <textobject>
              <para>A picture of the user interface.</para>
            </textobject>
          </mediaobject>
          <para>An Author browses to the home page of the package and
          sees a list of existing notes.</para>
          <segmentedlist>
            <?dbhtml list-presentation="table"?>
            <seglistitem><seg>200</seg><seg>A</seg><seg>An Author can
            see all existing notes.</seg></seglistitem>
            <seglistitem><seg>210</seg><seg>A</seg><seg>An Author can
            add a new note.</seg></seglistitem>
            <seglistitem><seg>220</seg><seg>A</seg><seg>If an author
            wrote a note, the author can edit that note.</seg></seglistitem>
            <seglistitem><seg>225</seg><seg>A</seg><seg>If an author
            wrote a note, the author can delete that note.</seg></seglistitem>
            <seglistitem><seg>230</seg><seg>A</seg><seg>Authors must
            be OpenACS site members.</seg></seglistitem>
            <seglistitem><seg>235</seg><seg>A</seg><seg>Authors
            authenticate themselves via the OpenACS login
            system.</seg></seglistitem>
          </segmentedlist>
        </sect3>
        <sect3>
          <title>Reader Interface</title>
          <para>An Reader can see all existing notes.</para>
          <segmentedlist>
            <?dbhtml list-presentation="table"?>
            <seglistitem><seg>300</seg><seg>A</seg><seg>A Reader can
            see all existing notes.</seg></seglistitem>
          </segmentedlist>
        </sect3>
      </sect2>

      <sect2>
        <title>Internationalization</title>
          <segmentedlist>
            <?dbhtml list-presentation="table"?>
            <seglistitem><seg>400</seg><seg>B</seg><seg>Postings can
            be in any language.</seg></seglistitem>
          </segmentedlist>
      </sect2>

      <sect2>
        <title>Security</title>
        <para>The only security need is that authors not be able to
        change or delete other authors' notes.  This can be enforced
        with built-in OpenACS security.</para>
          <segmentedlist>
            <?dbhtml list-presentation="table"?>
            <seglistitem><seg>500</seg><seg>A</seg><seg>There is no logging.</seg></seglistitem>
          </segmentedlist>
      </sect2>

    </sect1>

  </chapter>
  <chapter id="filename" xreflabel="Name of Document">
    <title>Design</title>


  <sect1 id="design-data-model">
    <title>Data Model</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="data-model.png" format="PNG"/>
        </imageobject>
        <textobject>
          <para>A picture of the data model</para>
        </textobject>
      </mediaobject>

      <sect2>
        <title>Tutorialnote</title>
        <para>This table holds the notes.  Each note is one
        record.</para>
          <segmentedlist>
            <?dbhtml list-presentation="table"?>
          <segtitle>Field</segtitle>
          <segtitle>Description</segtitle>
          <segtitle>Relationships</segtitle>
          <segtitle>Type</segtitle>
          <segtitle>Sample Value</segtitle>
          <segtitle></segtitle>
          <seglistitem>
            <seg>tutorialnote_id</seg>
            <seg></seg>
            <seg>Primary Key. References acs_objects(object_id).</seg>
          </seglistitem>
          <seglistitem>
            <seg>owner_id</seg>
            <seg>Indicates the owner of
            the note.</seg>
            <seg>References users(user_id).</seg>
          </seglistitem>
          <seglistitem>
            <seg>title</seg>
            <seg>Plain text title of the note</seg>
            <seg></seg>
            <seg>varchar(255)</seg>
            <seg>Hello, world</seg>
          </seglistitem>
          <seglistitem>
            <seg>body</seg>
            <seg>Body text of the note</seg>
            <seg></seg>
            <seg>varchar(2024)</seg>
            <seg>This is my first package</seg>
          </seglistitem>

          </segmentedlist>
        <para>Each note is an acs object.  <emphasis>This means that
        each record in the note table has a corresponding set of
        entries in the core acs tables, where security and other
        things are handled.  This integrates our package with OpenACS
        to use the existing security stuff.  It complicates our
        database scripts, because there are extra steps to create and
        delete records.  It also greatly complicates dropping the
        package because we have to carefully clean out any matching
        records - in the correct order to avoid breaking dependent
        relationships - before dropping our new table.</emphasis></para>
        <para>Use the standard stored procedures for add, delete, and
        name.</para>
        <para>Use ??? for full text search integration.</para>
      </sect2>
      
    </sect1>
    
    <sect1 id="design-ui">
      <title>User Interface</title>
      
      <mediaobject>
        <imageobject>
          <imagedata fileref="page-map.png" format="PNG"/>
        </imageobject>
        <textobject>
          <para>A picture of the page map.</para>
        </textobject>
      </mediaobject>

      <sect2>
        <title>index</title>
        <para>Fetch all existing notes and display them.  For each
        note, if the viewer has write permission on the note, show an
        edit link.  At the bottom of the page, if the viewer has
        permission to create new notes, show a "new" link.  </para>
      </sect2>

      <sect2>
        <title>add-edit</title>
        <para>This page is used show a form for editing notes, to show
        a form for creating new notes, and to process both forms after
        submission.</para>
        <orderedlist>
          <listitem>
            <para>If a note id is passed in, make sure that the
            current user has permission to edit that note.  If not,
            make sure that the current user has permission to create
            new notes.</para>
          </listitem>
          <listitem>
            <para>Use the template system to generate a form for
            editing/creating a note.  If an existing note id was
            passed in, populate the form fields wih that note's
            values.
</para>
          </listitem>
        </orderedlist>
      </sect2>
  </sect1>

  </chapter>

  <chapter id="user-guide" xreflabel="User Guide">
    <title>User Guide</title>
    <para>Documentation for an end user.</para>
  </chapter>

  <chapter id="admin-guide" xreflabel="Administrator Guide">
    <title>Administrator's guide</title>
    <para>No administrative tasks are needed or possible</para>
  </chapter>
  
  <bibliography>
    <biblioentry id="openacs-requirements">
      <title>Openacs Requirements Specification</title>
    </biblioentry>

    <biblioentry id="openacs-design">
      <title>Openacs Design Specification</title>
    </biblioentry>

    <biblioentry id="construx-requirements">
      <title>Software Requirements Specification</title>
      <author>
        <affiliation>Construx Software Builders, Inc.
        </affiliation>
      </author>
      <pubdate>2002</pubdate>
      <releaseinfo><ulink
      url="http://www.construx.com/cxone/basic/requirements.php"></ulink></releaseinfo>
    </biblioentry>

    <biblioentry id="construx-design">
      <title>Software Design Specification</title>
      <author>
        <othername>Construx Software Builders, Inc.</othername>
      </author>
      <pubdate>2002</pubdate>
      <releaseinfo><ulink
      url="http://www.construx.com/docs/member/cxone/CxTemp_SoftwareDesignSpecification.doc"></ulink></releaseinfo>
    </biblioentry>
  </bibliography>

</book>
