package-documentation.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?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.5 2024/09/11 06:15:47 gustafn 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 with 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>
