Index: openacs-4/packages/acs-core-docs/www/xml/files/samplenote/index.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/files/samplenote/Attic/index.xml,v diff -u -r1.1.2.1 -r1.1.2.2 --- openacs-4/packages/acs-core-docs/www/xml/files/samplenote/index.xml 2 Apr 2003 17:54:38 -0000 1.1.2.1 +++ openacs-4/packages/acs-core-docs/www/xml/files/samplenote/index.xml 7 Apr 2003 16:26:14 -0000 1.1.2.2 @@ -3,42 +3,23 @@ "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"> - YourApplication + Tutorial Application 1 - 26 Dec 2002 + 27 Dec 2002 Joel Aufrecht - Consolidated and shortened existing OpenACS - documentation; added some ideas from Construx + First Draft - - 0.3 - 5 Sep 2000 - Kai Wu - Edited further, incorporated feedback from Michael Yoon - - - 0.2 - 22 Aug 2000 - Kai Wu - Edited - - - 0.1 - 21 Aug 2000 - Josh Finkler, Audrey McLoghlin - Created - ($Id$) - Your - Name + Joel + Aufrecht -
youremail
+
joel@aufrecht.org
 @@ -49,94 +30,105 @@ Introduction - This package does .... Summarize the rest of this - document in one paragraph. + 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. Overview - The components of this package are ... List the - major components and their functions. + 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. - This package depends on ... List other packages, - other software, and any external processes that the package - needs. + This package depends on the core OpenACS functionality and on + OpenFTS. It is PostGreSQL-only - it has not been ported to + Oracle. - Define any abbreviations or other special terms. + OpenFTS is the third-party PostGreSQL full text search engine. Use-cases and User-scenarios - List some people who would use this package. - Describe how they would use it, how it would be better than what - they are doing now, and how it compares to alternatives. - Include specific, real sample data if possible. - User 1 - This user will accomplish X with the package. - Currently, the user does X with product Y, which takes - several hours and costs too much. + Author + 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. - User 1 adds and edits stuff ... + An Author creates a new note, such as the following: + + + + + + + Hello World + This is my first OpenACS package. + + + - User1 Views stuff ... + An Author changes a note previously written. + Authors can't change other authors' notes. + + An Author deletes a note that is no longer + needed. Unless explicitly deleted, notes should never disappear. + + + + Reader + 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. + + + + An Reader browses the notes. + + + An Reader searches for notes. + + + - Sample Data - An example of data stored in the package is ... - - - Prioritized Requirements - A list of requirements, split up into functional - areas. In the ideal requirements document, all requirements are - sufficiently specific, detailed, precise, and comprehensive that - the package can be designed and built without any other - directions, and two different packages built to meet the same - requirements will be similar internally and have identical - APIs. Requirements are prioritized relative to a release - cycle. All priority A requirements must be satisfied before the - package can be released. Priority B requirements are - desired but should be cut as soon as possible if the schedule is - threatened. Priority X requirements should not be implemented - in this cycle; at the beginning of the next cycle, they should - be promoted to A or B or removed. - + System Interfaces - Describe all of the interfaces between the - package and other OpenACS packages, the OpenACS API, the host - computer, and network clients. Include sample conversations - for any external APIs. Describe any API the package will - provide. - Interface1 - General description. + Full Text Search + All text entered into the package should be searchable + via OpenFTS. The OpenFTS interface is specified at ???. + Number Priority Description - 100AA critical requirement. - 110BAn optional requirement. - 120XA requirement deferred for - this cycle. + 100AThe Title and + Body fields are indexed by Full Text Search. @@ -145,41 +137,64 @@ User Interfaces User 1 Interface - Use storyboards and drawings to describe - what a typical user will see and how User 1 will use the product. - This includes web interfaces, email. + + + + + + A picture of the user interface. + + + An Author browses to the home page of the package and + sees a list of existing notes. + + + 200AAn Author can + see all existing notes. + 210AAn Author can + add a new note. + 220AIf an author + wrote a note, the author can edit that note. + 225AIf an author + wrote a note, the author can delete that note. + 230AAuthors must + be OpenACS site members. + 235AAuthors + authenticate themselves via the OpenACS login + system. + - Administrator Interface + Reader Interface + An Reader can see all existing notes. + + + 300AA Reader can + see all existing notes. + - - Instance Customization - - Customization - What will have to change in a typical - installation? What are reasonable defaults? - - - - Internationalization + + + 400BPostings can + be in any language. + Security - How sensitive is the data stored? Can users - see or edit each other's data? What cryptography is required? - What logs should be kept, who should monitor them, and how? - + 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. + + + 500AThere is no logging. + - - Data Storage - - @@ -189,120 +204,114 @@ Data Model + + + + + + A picture of the data model + + - - The data model discussion should address the intended usage - of each entity (table, trigger, view, procedure, etc.) when this - information is not obvious from an inspection of the data model - itself. - - If a core service or other subsystem is being used (e.g., the - new parties and groups, permissions, etc.) this should also be - mentioned. - - Any default permissions should be identified herein. - - Discuss any data model extensions which tie into other - packages. - - - - Transactions - Discuss modifications which the database may undergo from - your package. Consider grouping legal transactions according to - the invoking user class, i.e. transactions by an OpenACS-admin, by - subsite-admin, by a user, by a developer, etc. - - - - - Table1 - Description of table. - - + Tutorialnote + This table holds the notes. Each note is one + record. + + Field Description Relationships Type Sample Value - fieldname - Indicates ... - Primary Key... References ... - int + tutorialnote_id + Primary Key. References acs_objects(object_id). + + owner_id + Indicates the owner of + the note. + References users(user_id). + + + title + Plain text title of the note + + varchar(255) + Hello, world + + + body + Body text of the note + + varchar(2024) + This is my first package + - + Each note is an acs object. 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. + Use the standard stored procedures for add, delete, and + name. + Use ??? for full text search integration. User Interface - - In this section, discuss user interface issues and pages to be built; - you can organize by the expected classes of users. These may include: - - - Developers - OpenACS administrators (previously known as site-wide administrators) - Subsite administrators - End users - - - - You may want to include page mockups, site-maps, or other visual aids. - Ideally this section is informed by some prototyping you've done, to - establish the package's usability with the client and other interested - parties. - - - - Note: In order that developer documentation be uniform across - different system documents, these users should herein be designated as - "the developer," "the OpenACS-admin," "the sub-admin," and "the user," - respectively. - + + + + + + A picture of the page map. + + - - Finally, note that as our templating system becomes more entrenched - within the OpenACS, this section's details are likely to shift from UI - specifics to template interface specifics. - - + + index + 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. + - - Configuration/Parameters - - - - Under OpenACS 4.5, parameters are set at two levels: at the global level by - the OpenACS-admin, and at the subsite level by a sub-admin. In this - section, list and discuss both levels of parameters. - + + add-edit + 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. + + + 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. + + + 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. + + + + - - Future Improvements/Areas of Likely Change - - - - If the system presently lacks useful/desirable features, note details - here. You could also comment on non-functional improvements to the - package, such as usability. - - - - Note that a careful treatment of the earlier "competitive analysis" - section can greatly facilitate the documenting of this section. - - -