package-documentation.xml
Delivered as text/xml
[ hide source ]
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.3.2.1 2021/10/05 07:01:19 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>