Index: openacs-4/packages/dotlrndoc/www/doc/architecture-overview.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrndoc/www/doc/architecture-overview.adp,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/dotlrndoc/www/doc/architecture-overview.adp	14 Oct 2001 21:42:58 -0000	1.1
+++ openacs-4/packages/dotlrndoc/www/doc/architecture-overview.adp	24 Oct 2001 23:27:22 -0000	1.2
@@ -27,7 +27,8 @@
 <ul>
 <li> <strong>a group</strong>: this will serve to define membership
 and roles within the learning community. These groups are not
-necessarily all in the same group type.
+necessarily all in the same group type (well, they are all ROOTED in
+the same group type, <tt>dotlrn_community</tt>).
 <li> <strong>a site node</strong>: this will serve to define a
 consistent URL for the learning community, and to segment away each
 communities from one another. An example is <tt>/dotlrn/alumni-1998</tt>.
@@ -58,22 +59,23 @@
 The fist three parameters may be stored as separate items, all in one,
 or combined in some way. The current architectural direction is to
 separate Year and to group Term and Section, but this may change. In
-terms of the global architecture, this isn't very critical.
+terms of the global architecture, this isn't very important.
 
 <p>
 
 Since all class instances have a common basic set of parameters, the
 class instance groups should all be a single core group type, called
-<b><tt>Class</tt></b>. The <tt>Class</tt> group type defines the
-attributes above (year, term, section).
+<b><tt>dotlrn_class</tt></b>. The <tt>dotlrn_class</tt> group type defines the
+attributes above (year, term, section). <tt>dotlrn_class</tt> is a
+group type that subtypes <tt>dotlrn_community</tt>.
 
 <p>
 
 In addition, in order to group class instances by the class they refer
-to, the <tt>Class</tt> group type is subtyped into further group
+to, the <tt>dotlrn_class</tt> group type is subtyped into further group
 types, where one class is itself a group type. For example,
 <tt>6.001</tt> is a group type, whose parent group type is
-<tt>Class</tt>. Then, <tt>6.001</tt> is the group type that all
+<tt>dotlrn_class</tt>. Then, <tt>6.001</tt> is the group type that all
 instances of 6.001 belong to. <tt>6.001 - Spring 2002, Section B</tt>
 is a group of group type <tt>6.001</tt>. This architecture allows for:
 
@@ -93,7 +95,7 @@
 <p>
 
 Thus, unlike class instances, the group type structure for clubs can
-be much simplified. A root group type, called <tt>Club</tt> can
+be much simplified. A root group type, called <tt>dotlrn_club</tt> can
 encompass all club groups without any additional level of group typing.
 
 
@@ -106,21 +108,58 @@
 
 <p>
 
-Thus, a <strong>dotLRN Package</strong> is composed of two OpenACS 4
+Thus, a <strong>dotLRN Package</strong> is composed of <b>three</b> OpenACS 4
 packages:
 
 <ul>
-<li> an OpenACS 4 raw functionality package (e.g. bboard), whose
-dependencies are completely independent of the core dotLRN application.
-<li> a simple OpenACS 4 package (e.g. bboard-dotlrn), dependent on the core dotLRN
+<li> an OpenACS 4 raw functionality package whose
+dependencies are completely independent of the core dotLRN
+application (e.g. bboard).
+<li> an OpenACS 4 portlet, using the New Portal Architecture (NPA), whose
+role is to summarize the information in one portlet
+(e.g. bboard-portlet). This is dependent on the NPA, but not on dotLRN.
+<li> an OpenACS 4 package (e.g. bboard-dotlrn), dependent on the core dotLRN
 application, whose role is to wrap the raw OpenACS 4
 functionality in the required dotLRN APIs.
 </ul>
 
 <p>
 
+The relationship between the NPA and the portlet package are defined
+using <b>ACS Service Contract</b>. This is described in greater detail
+in The Portal Interface (futher down).
+
+<p>
+
+The relationship between dotLRN and the specific dotLRN-dependent
+packages (dotlrn-bboard, dotlrn-faq, etc...) is also defined using
+<b>ACS Service Contract</b>. ACS Service Contract defines a standard
+provider/consumer interface with special contract APIs. The dotLRN
+system defines the <b>dotLRN Applet Contract</b>, which includes the
+following operations:
+<ul>
+<li> <b>GetPrettyName</b>: Obtain a pretty, presentable name for the
+applet in question.
+<li> <b>AddCommunity</b>: Add the applet to a
+new community. This will most probably entail creating a new package for
+this functionality, mounted below the community's main mount point. It
+will also involve setting up applet-specific data structures (e.g. a
+new forum inside bboard).
+<li> <b>RemoveCommunity</b>: Remove the applet from the
+community. This will entail cleaning up any applet-specific data
+structures, removing the mount point and package instance.
+<li> <b>AddUser</b>: add a user to the community, and perform any
+applet-specific related actions. For applets that are represented via
+a portlet (which is often, but not always, the case), this will add
+the right portlet to the user's portal page for that community. It
+will also add the generic portlet to the user's main, cross-community
+workspace.
+</ul>
+
+<p>
+
 The specifics of creating a dotLRN package are described in the <a
-href=dotlrn-package-creation>dotLRN Package Creation Guide</a>.
+href=writing-a-dotlrn-package.adp>dotLRN Package Creation Guide</a>.
 
 <h2>The Portal Interface</h2>
 
@@ -138,7 +177,7 @@
 
 <h3>A Portal Page</h3>
 
-The <strong>New Portals Package (NPP)</strong> will feature the
+The <strong>New Portals Architecture (NPA)</strong> will feature the
 ability to programmatically create and edit single <strong>Portal
 Pages</strong>. A single Portal Page will be defined by:
 <ul>
@@ -156,7 +195,7 @@
 
 <h3>Portlets</h3>
 
-The NPP will require portlet packages much like the old portals
+The NPA will require portlet packages much like the old portals
 package. Each portlet package is responsible for:
 <ul>
 <li> rendering itself within a portal page
@@ -167,11 +206,20 @@
 
 <h2>The Per-User Interface</h2>
 
-Each user will have a single NPP interface which groups information
+Each user will have a single NPA interface which groups information
 from all dotLRN classes in one page. Given the subsited architecture
 of each class, the per-user interface must be subsite aware, and must
 be able to query information across subsites.
 
 <p>
 
+The per-user interface will use slightly different portlets than the
+community-specific ones, given that those portlets will require
+scanning information across package instances. There is some thought
+that this may be "not so kosher." As long as the cross-package
+information is kept to a minimum, though, it should be just
+fine. We'll make sure to keep associating packages with the
+communities they belong to.
+<p>
+
 <%= [dotlrn_footer] %>
Index: openacs-4/packages/dotlrndoc/www/doc/index.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrndoc/www/doc/index.adp,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/dotlrndoc/www/doc/index.adp	23 Oct 2001 16:58:51 -0000	1.2
+++ openacs-4/packages/dotlrndoc/www/doc/index.adp	24 Oct 2001 23:27:22 -0000	1.3
@@ -11,6 +11,9 @@
 <li> <a href=permission-overview.adp>Roles, Sections, and Permissions</a>
 <li> <a href=permission-portals.adp>Portal Permissions</a>
 <li> <a href=architecture-overview.adp>Architecture Overview</a>
+<p>
+<li> <a href=additional-modules.adp>Sloan - Additional Modules</a>
+
 </ul>
 
 
Index: openacs-4/packages/dotlrndoc/www/doc/permission-overview.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrndoc/www/doc/permission-overview.adp,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/dotlrndoc/www/doc/permission-overview.adp	14 Oct 2001 21:42:58 -0000	1.1
+++ openacs-4/packages/dotlrndoc/www/doc/permission-overview.adp	24 Oct 2001 23:27:22 -0000	1.2
@@ -20,13 +20,20 @@
 
 <h3>Unregistered Visitor</h3>
 An unregistered visitor is simply a user who browses the dotLRN
-application without login information.
+application without login information. An installation of dotLRN may
+disallow unregistered visitors, if it so chooses.
 
-<h3>Registered Visitor</h3>
-A registered visitor is one who has entered first name, last name,
-email address and password information, and how has logged in using
-those credentials.
+<h3>Registered dotLRN Guest</h3>
+A registered dotLRN guest is a registered user (first name, last name,
+email, password are entered) who has logged in and is using those
+credentials. This user is enabled only for a particular class or club,
+and does not have access to the generic dotLRN workspace.
 
+<h3>Registered dotLRN User</h3>
+A registered dotLRN user is a registered user how has logged in using
+those credentials. A dotLRN user can browse all available public
+classes and clubs.
+
 <h3>Registered Student of an Instance of a Class</h3>
 A registered student of a class is one who has requested association
 with a particular instance of a class (e.g. Micro-Economics, Spring
@@ -81,7 +88,8 @@
 <p>
 <h4>Permissions</h4>
 <ul>
-<li> All users can access this section
+<li> All registered dotLRN users can access this section
+<li> Guests or unregistered visitors cannot access this section
 </ul>
 
 
@@ -98,7 +106,8 @@
 <p>
 <h4>Permissions</h4>
 <ul>
-<li> All users can access this section
+<li> All registered dotLRN users can access this section
+<li> All guests of <b>that</b> class can access this section
 <li> Registered users associated with a class instance of this class
 will see specific links to the proper class instances
 </ul>
@@ -140,9 +149,12 @@
 <p>
 <h4>Permissions</h4>
 <ul>
-<li> All registered users can access this section
-<li> Only registered users associated with this class instance can
+<li> All registered dotLRN users can access this section
+<li> Guests for this class instance can see this section
+<li> Only registered users and guests associated with this class instance can
 access the full functionality
+<li> Certain functionality (like class rosters) are only accessible to
+full users, not to guests
 </ul>
 
 <h3>Per-Class-Instance Admin Page</h3>
@@ -201,7 +213,8 @@
 <p>
 <h4>Permissions</h4>
 <ul>
-<li> All registered users can access this section
+<li> All registered dotLRN users can access this section
+<li> Guests of this specific community can access this section
 <li> Only members of the community at hand can access
 community-specific chunks/links
 </ul>
Index: openacs-4/packages/dotlrndoc/www/doc/writing-a-dotlrn-package.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrndoc/www/doc/writing-a-dotlrn-package.adp,v
diff -u -N
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrndoc/www/doc/writing-a-dotlrn-package.adp	24 Oct 2001 23:27:22 -0000	1.1
@@ -0,0 +1,109 @@
+<%= [dotlrn_header "Writing a dotLRN Package"] %>
+<h2>Writing a dotLRN Package</h2>
+by <a href=mailto:ben@openforce.net>Ben Adida</a>.
+<hr><P>
+
+Writing a dotLRN package is a task that is meant to hook generic
+OpenACS 4 functionality into the framework of dotLRN communities. As
+much as possible, one should worry solely about that core
+functionality. As long as this functionality is made scopable as per
+the subsite approach in OpenACS 4, hooking into dotLRN is fairly
+straight-forward.
+
+<p>
+
+<h3>The Structure of a dotLRN Package/Applet</h3>
+
+As far as dotLRN is concerned, a dotLRN package is an
+<strong>applet</strong> (literally a "small application," nothing to
+do with Java applets) that must provide a simple
+API under the <tt>acs-service-contract</tt> mechanism. This API allows
+the dotLRN core to generically dispatch calls to each dotLRN applet
+when certain events happen.
+
+<p>
+
+Thus, a dotLRN applet must be able to respond to the following events:
+<ul>
+<li> the applet is added to a community
+<li> the applet is removed from a community
+<li> a user is added to a community for which the applet in question
+is enabled
+<li> a user is removed from a community for which the applet in
+question is enabled
+</ul>
+
+Additional events may be added in the future to further enhance
+generalized applet functionality.
+
+<p>
+
+Most dotLRN applets will want to offer an interface to their users (although
+it's very possible that some won't). To do so, the dotLRN core will
+use the New Portal Architecture of OpenACS 4. A dotLRN applet can
+simply add itself to the appropriate portal pages by providing an
+<strong>NPA portlet</strong>. <i>Note that the architecture of this
+portlet is dotLRN-independent!</i> The contents of the portlet may
+rely on dotLRN functionality, but the means by which the portlet is
+added to portal pages does not!
+
+<p>
+
+Also, it is highly recommended that functionality be added to dotLRN
+by first thinking of generic OpenACS 4 functionality, and eventually
+hooking it into the dotLRN core. Thus, a dotLRN package will be
+usually composed of <strong>three OpenACS 4 packages</strong>:
+
+<ul>
+<li> a core functionality package (e.g. bboard), independent of dotLRN functionality
+<li> a portlet package (e.g. bboard-portlet), whose interface to NPA
+is independent of dotLRN functionality, but whose content may be
+dotLRN-enhanced.
+<li> a dotLRN applet (e.g. dotlrn-bboard), dependent on dotLRN
+functionality and basically the glue between the dotLRN core and the
+core functionality of this new applet.
+</ul>
+
+<h3>Core Functionality</h3>
+
+There is only one guideline in writing core functionality for a dotLRN
+applet: <strong>make sure the package can be correctly scoped across
+multiple subsites</strong>. This means that any data should be scoped
+correctly to a particular package_id. Take a look at the standard
+bboard package for a clear way to do this.
+
+<h3>Portlet</h3>
+
+The portlet should be created in line with the New Portal
+Architecture. We want to strongly discourage developers from making
+this portlet package dependent on dotLRN functionality: portlets will
+be able to query parameter information from the NPA (such as the
+<tt>package_id</tt>), independently of any dotLRN functionality.
+
+<p>
+
+For more details on creating a portlet package, check the <a
+href=npa/>New Portals Architecture</a>
+
+<h3>dotLRN Applet</h3>
+
+A dotLRN applet is simply the glue that responds to specific
+requests. Let's take the example of the bboard applet to better
+understand what's going on.
+
+<p>
+
+First, we will write the actual procs that we expect to eventually
+hook into the dotLRN system.
+
+<p>
+
+The first proc is called when the bboard applet is added to a community
+
+<pre>
+ad_proc -public dotlrn_bboard::applet_add {community_id} {} {
+	# Instantiate bboard and mount it
+}
+</pre>
+
+<%= [dotlrn_footer] %>