Index: openacs-4/packages/dotlrn/www/doc/architecture-overview.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/architecture-overview.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/architecture-overview.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,186 @@
+<master src="master">
+<property name="title">dotLRN Architecture</property>
+<h2>dotLRN Architecture</h2>
+by <a href=mailto:ben@openforce.net>Ben Adida</a> and <a href=arjun@openforce.net>Arjun Sanyal</a>, part of <a href=./>dotLRN Documentation</a>.
+<hr><p>
+
+
+dotLRN is built on OpenACS 4.x, a modular architecture for
+community-oriented web applications. dotLRN is also
+<strong>modular</strong> in that new course management functionality
+can be added as desired. Since dotLRN modules must function within the
+dotLRN architecture, dotLRN modularity must be built on top of OpenACS
+modularity.
+
+<p>
+
+The dotLRN architecture attempts to define a framework within which
+learning communities develop. A learning community may take many
+different forms but remains the crux of the architecture.
+
+
+<h2>dotLRN Community</h2>
+
+A <strong>dotLRN Community</strong> is architected as a series of
+OpenACS components, with a heavy use of the <strong>subsite</strong>
+concept. One community is represented by:
+
+<ul>
+<li> <strong>an OpenACS group</strong>: this serves to define membership
+and roles within the learning community.
+<li> <strong>a site node</strong>: this serves 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>.
+<li> <strong>an instance of the dotLRN Community Manager
+package</strong>: this serves to display community-specific data
+in a way that is clearly segmented away from the other learning
+communities using the <i>acs-subsite</i> constructs.
+</ul>
+
+<h3>OpenACS Group</h3>
+
+The core dotLRN group type is <tt>dotlrn_community</tt>. This group
+type defines some basic attributes that all communities have:
+<ul>
+<li> <b>a short name</b>: a simple name with no spaces, no special
+characters, usually all lowercase. e.g. finance-101
+<li> <b>a pretty name</b>: a name that is used in pretty
+presentation. e.g. Finance 101
+<li> <b>start and end dates</b>: for communities that have certain
+validity periods, a start date and end date.
+</ul>
+
+There are two different types of learning communities in the basic
+dotLRN release: <strong>class instances</strong> and
+<strong>clubs</strong>. While Clubs need no additional attributes,
+Class Instances require information concerning the Term and Year of
+the Class Instance.
+
+<h3>Site Node</h3>
+
+In dotLRN, a community is mounted only at one particular node. In the
+future, if communities end up being multi-mounted, there will have to
+remain a canonical location for the community in order to ensure
+maximal modularity - specifically the ability to point to a
+community's URL using only the <tt>community_id</tt> as a starting
+point.
+
+<h3>Instance of dotLRN Community Manager</h3>
+
+The core dotLRN OpenACS package is called <tt>dotlrn</tt>
+(surprisingly enough). This package is meant to be remounted to handle
+community types and specific communities. A <tt>package_id</tt>
+corresponds to each community.
+
+<p>
+
+The group types for these two dotLRN Community Types are
+<tt>dotlrn_class_instance</tt> and <tt>dotlrn_club</tt>.
+
+<h2>Use of NPA</h2>
+
+dotLRN makes heavy use of the <b>New Portal Architecture</b>.
+
+<p>
+
+Each full-access user has a personal portal where all data from all
+communities is centralized in one place. This is called the <b>dotLRN
+User Portal</b>.
+
+<p>
+
+Each community has a non-member portal which displays information
+to those browsing the system and wanting to find out more about a
+community before joining it. This is called the <b>dotLRN Community
+Non-Member Portal</b>.
+
+<p>
+
+Each community also has an administrative portal which centralizes all
+administrative functionality for that community. This is called the
+<b>dotLRN Community Admin Portal</b>.
+
+<p>
+
+Finally, each community member has her own <b>dotlrn Community Member
+Portal</b>. The important distinction here is that there is a
+different portal for each member of this community. Thus, if a
+community has 100 members, there are 100 individually managed
+portals. These portals are initially created from the <b>dotLRN
+Community Portal Template</b> that administrators of the community control.
+
+<h2>dotLRN Applets</h2>
+
+dotLRN Communities have various packages of functionality. These
+packages (<b>dotLRN applets</b>) are much like existing OpenACS 4
+packages, but with added specifications, special callback interfaces,
+and predictable APIs that not every OpenACS 4 package will have.
+
+<p>
+
+Thus, a <strong>dotLRN Applet</strong> is composed of <b>three</b>
+pieces that may each be a separate OpenACS package:
+
+<ul>
+<li> <b>OpenACS raw functionality</b>, to provide discussion
+forum functionality. As much as possible, this shouldn't depend on
+other dotLRN components. (e.g. bboard)
+
+<li> <b>OpenACS portlet</b>, using the New Portal Architecture (NPA),
+to provide the ability to display the raw functionality in a portal
+interface. This obviously depends on the the NPA, but should otherwise
+be as independent as possible from dotLRN. (e.g. bboard-portlet)
+
+<li> <b>dotLRN functionality hooks</b>, to link the raw functionality
+into the appropriate dotLRN structure. This obviously depends on
+dotLRN, but should be as thin a layer as possible on top of the the
+previous two components. (e.g. dotlrn-bboard).
+</ul>
+
+<p>
+
+<h3>NPA Interactions</h3>
+
+The relationship between the NPA and the portlet functionality is
+explored in the <a href=npa-architecture.adp>NPA Architecture Manual</a>.
+
+<p>
+
+<h3>dotLRN Applet API</h3>
+
+The relationship between dotLRN and the specific dotLRN-dependent
+packages (dotlrn-bboard, dotlrn-faq, etc...) is 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>AddAppletToCommunity</b>: Add the applet to a
+new community. This will most probably entail instantiating 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>RemoveAppletFromCommunity</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 dotLRN in general. This user has
+not yet joined any community, but may need user-specific functionality
+enabled (a private folder for files, a personal calendar, etc..)
+<li> <b>RemoveUser</b>: remove a user from dotLRN in general. This
+cleans up the AddUser operation.
+<li> <b>AddUserToCommunity</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.
+<li> <b>RemoveUserFromCommunity</b>: remove a user from a community,
+and thus clean up the actions of AddUserToCommunity.
+</ul>
+
+<p>
+
+The specifics of creating a dotLRN package are described in the <a
+href=writing-a-dotlrn-package.adp>dotLRN Package Creation Guide</a>.
Index: openacs-4/packages/dotlrn/www/doc/dotlrn-faq.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/dotlrn-faq.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/dotlrn-faq.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,209 @@
+<master src="master">
+<property name="title">dotLRN FAQ</property>
+<div class="indent">
+
+ <h2>The dotLRN FAQ</h2>
+
+ <p class="indent">part of <a href=../>dotLRN</a>
+
+ <p class="indent"><small>Last updated: $Date: 2003/01/22 14:23:38 $</small>
+
+ <p class="heading">Contents
+
+ <ul>
+ <li><a href=dotlrn-faq.adp#basics>Basics</a>
+ <li><a href=dotlrn-faq.adp#development>State of dotLRN Development</a>
+ <li><a href=dotlrn-faq.adp#openforce>The OpenForce Role in dotLRN</a>
+ <li><a href=dotlrn-faq.adp#openacs>dotLRN and OpenACS</a>
+ <li><a href=dotlrn-faq.adp#licensing>Licensing</a>
+ <li><a href=dotlrn-faq.adp#misc>Miscellaneous</a>
+ </ul>
+
+
+ <p class="heading"><a class="plain" name="basics">Basics</a>
+
+ <p class="question">Q: What is dotLRN?
+ <p class="answer">
+
+ dotLRN is a full-featured application for rapidly developing
+ web-based learning communities, specifically in the context of
+ Course Management. The dotLRN software relies on a development
+ version of <a
+ href=http://openacs.org>OpenACS v4.5</a> and includes data model,
+ application logic, and templates to get you up and running very
+ quickly.
+
+ <p class="question">Q: Is dotLRN usable?
+ <p class="answer">
+
+ dotLRN is currently in <strong>alpha</strong> state. The
+ target audience at this time is mostly early
+ adopters. <strong>No backwards-compatibility will be ensured
+ until a beta version</strong>. That said, dotLRN is quite
+ stable as is and can most certainly be used to determine
+ near-term usability in a production environment.
+
+ <p class="question">Q: When will dotLRN ship?
+ <p class="answer">
+
+ dotLRN beta is planned for May 1st, 2002. dotLRN v1.0 is
+ planned for August 1st, 2002.
+
+ <p class="question">Q: How can I contribute?
+ <p class="answer">
+
+ We are currently developing our contribution mechanisms.
+ <p class="answer">If you are actively interested in helping us
+ develop these mechanisms, please contact us at <a
+ href=mailto:dotlrn@openforce.net>dotlrn@openforce.net</a>.
+
+ <p class="question">Q: What about this dotLRN Governance discussion?
+ <p class="answer">
+
+ The discussion is still under way. MIT Sloan will be providing
+ the framework for this in the very near future.
+
+
+ <p class="heading"><a class="plain" name="development">State of dotLRN
+ Development</a>
+
+ <p class="question">Q: So what version of OpenACS do I need to use?
+ <p class="answer">
+
+ dotLRN will work with:
+
+ <ul>
+ <li>The latest development CVS sources
+ (i.e. HEAD). Instructions to check out the latest
+ development CVS sources are on the <a
+ href="dotlrn-install.adp">dotLRN installation</a> page.
+ </ul>
+
+ <p class="answer">
+ dotLRN will probably work with:
+
+ <ul>
+ <li>A recent OpenACS <a
+ href="http://openacs.org/sdm/nightly-tarballs.tcl?package_id=9">nightly
+ tarball</a> But we don't test this, and all the warnings on
+ the page apply
+ </ul>
+
+ <p class="answer">
+ dotLRN will <strong>NOT</strong> work with:
+
+ <ul>
+ <li>The OACS v4.5 beta CVS branch
+ <li>Any OACS v4.5 beta tarballs
+ </ul>
+
+ <p class="note">
+
+ When dotLRN is released as a complete tarball, we will specify
+ exactly which OpenACS tarball or other package you'll
+ be able to use.
+
+ <p class="question">Q: When will dotLRN be compatible with PostgreSQL?
+ <p class="answer">
+
+ PostgreSQL compatibility porting continues rapidly and will be
+ completed in the coming weeks. A partial port is in the CVS
+ tree, with more progress daily.
+
+ <p class="question">Q: Can I use ACS Classic 4.2/4.3?
+ <p class="answer">
+
+ Due to numerous fixes and enhancements made by the OpenACS
+ developers, dotLRN will <strong>not</strong> work with ACS
+ Classic. However, ACS Classic and OpenACS are similar enough
+ so that code and skills based on one are very transferable
+ to the other.
+
+ <p class="question">Q: Can I get a tarball of the dotLRN CVS?
+ <p class="answer">
+
+ Contact us at <a
+ href=mailto:dotlrn@openforce.net>dotlrn@openforce.net</a> if
+ you are interested in a tarball.
+
+
+ <p class=heading><a class=plain name=openforce> The OpenForce Role
+ in dotLRN</a>
+
+ <p class="question">
+ Q: What's the relationship between MIT Sloan and OpenForce?
+ <p class="answer">
+
+ MIT Sloan hired OpenForce to develop dotLRN to replace the aging
+ SloanSpace v1, which itself was built on ACS v3.
+
+ <p class="question">Q: How will OpenForce work with other OpenACS
+ developers?
+ <p class="answer">
+
+ OpenForce will continually provide anonymous CVS access to the
+ dotLRN development tree. OpenForce will continue to provide
+ architectural direction and goals for dotLRN. Over time, OpenForce
+ will qualify and include new developers in the core development
+ process. OpenForce expects to lead - but not monopolize - the dotLRN
+ process. OpenForce will also provide a repository of dotLRN
+ applications available for all to obtain existing dotLRN extensions
+ and provide new ones to the community.
+
+ <p class="question">Q: Will OpenForce develop, support, and/or host
+ dotLRN commercially?
+ <p class="answer"> Absolutely.
+
+ <p class="question">Q: Will OpenForce preclude me from providing
+ my own services surrounding dotLRN?
+ <p class="answer"> Absolutely not.
+
+ <p class="question">Q: But Why? Aren't you crazy to throw away
+ such clear business opportunity?
+ <p class="answer">
+
+ We are not in the business of selling packaged closed-source
+ software. We believe that open-source software and a strong
+ developer community provides plenty of opportunity for numerous
+ commercial services. We intend to stick to the Open-Source track
+ 100%. No tricks here.
+
+
+ <p class=heading><a class=plain name=openacs>dotLRN and OpenACS</a>
+
+ <p class="question">Q: Is dotLRN a part of the OpenACS project?
+ <p class="answer">
+
+ dotLRN is not part of the OpenACS project, but it is an OpenACS
+ application. This means that dotLRN will install on a vanilla
+ OpenACS without additional modifications and through the regular,
+ accepted OpenACS API. While dotLRN developers happen to also be
+ core OpenACS developers, the dotLRN team is taking all possible
+ measures to ensure that any modification suggested to the OpenACS
+ core is approved by other OpenACS developers that do not have a
+ direct stake in dotLRN.
+
+ <p class="question">Q: Will dotLRN be merged into OpenACS?
+ <p class="answer">
+ This is a question to be answered by the OpenACS community.
+
+
+ <p class=heading><a class=plain name=licensing>Licensing</a>
+
+ <p class="question">Q: What are the terms of use for dotLRN?
+ <p class="answer">
+ dotLRN is distributed under the GNU General Public License version 2.
+
+
+ <p class=heading><a class=plain name=misc>Miscellaneous</a>
+
+ <p class="question">Q: How is dotLRN spelled and pronounced?
+ <p class="answer">
+
+ It's sometimes written as <tt>.LRN</tt>, but the spelling and
+ capitalization <tt>dotLRN</tt> is preferred. hackers who type a
+ lot usually write <tt>dotlrn</tt>. <tt>dotLRN</tt> is pronounced
+ "daught-learn" We are currently accepting voice
+ applications for the dotLRN MP3 pronounciation file.
+
+</div>
Index: openacs-4/packages/dotlrn/www/doc/dotlrn-install.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/dotlrn-install.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/dotlrn-install.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,381 @@
+<master src="master">
+<property name="title">Installing dotLRN - OpenForce</property>
+
+<div class="indent">
+
+ <h2>Installing dotLRN</h2>
+
+ <p class="indent">part of <a href="../">dotLRN</a></p>
+
+ <p class="indent"><small>Last updated: $Date: 2003/01/22 14:23:38 $</small>
+
+ <p class="heading">Contents</p>
+
+ <ul>
+ <li>Read the dotLRN FAQ
+ <li>Get and Install OpenACS from development CVS
+ <li>Get dotLRN from CVS
+ <li>Install dotLRN on your system
+ <li>Explore dotLRN
+ <li>Reinstalling dotLRN
+ </ul>
+
+
+ <p class="heading">Read the <a href="/faq">dotLRN FAQs</a></p>
+
+ <p class="heading">Get and Install OpenACS from development CVS</p>
+
+ <p class="note">
+ If you have a working OpenACS installation from the latest
+ development CVS, make sure that you have all the packages required
+ below then skip to the next section.
+ </p>
+
+ <p class="indent">
+
+ If you are installing OpenACS, follow the extensive
+ installation <a
+ href="http://openacs.org/doc/openacs-4">documentation</a>.
+ <strong>Stop</strong> at the <a
+ href="http://openacs.org/doc/openacs-4/openacs.html">point</a>
+ where the OpenACS installation instructions tell you to
+ "download OpenACS". Don't use the "Quick
+ Downloads"! Continue on with this document.
+
+ <p class="indent">
+
+ <pre>
+ cvs -d :pserver:anonymous@openacs.org:/cvsroot login
+ (just hit return for the password)
+ cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot checkout acs-core
+ </pre>
+
+ <p class="note">
+ CVS commandlines are given in terms of anonymous users, if you have an
+ account on openacs.org, use your login where appropriate. Don't forget to
+ set the CVS_RSH variable in your shell envrioment to "ssh".
+
+ <p class="indent">
+
+ dotLRN requires some more modules that are not in
+ <tt>acs-core</tt>, but not all of the packages in the OpenACS
+ source tree. Next are the commands to get these modules.
+
+ <p class="indent">
+ Here's the current list of non-core packages needed for dotlrn:
+
+ <p class="indent">
+ <pre>
+ acs-datetime
+ acs-developer-support (optional)
+ acs-events
+ acs-mail-lite
+ attachments
+ bulk-mail
+ calendar
+ faq
+ file-storage
+ forums
+ general-comments
+ news
+ notifications
+ ref-timezones
+ user-preferences
+ </pre>
+ </p>
+
+ <p class="note">
+ <strong>Do not install</strong> or, if installed, <strong>remove</strong> these
+ packages since they conflict with dotlrn packages: <tt>portal</tt>
+ (conflicts with new-portal) and <tt>spam</tt>
+ (conflicts with bulk-mail)
+ </p>
+
+ <p class="indent">
+ <tt>cd</tt> to the newly created <tt>/openacs-4/packages</tt>
+ directory before the next command.
+
+ <p class="indent">
+ <pre>
+ cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co \
+ acs-datetime acs-developer-support acs-events acs-mail-lite \
+ attachments bulk-mail calendar faq file-storage forums general-comments \
+ news notifications ref-timezones user-preferences
+ </pre>
+
+ <p class="note">
+ Installation timesaver: In the <tt>/packages/ref-timezones/sql/common/</tt>
+ directory, cut down the files to a few <tt>insert</tt> statements apiece.
+ This is fine for test system, and will save you a lot of time in the
+ installation process.
+
+ <p class="indent">
+ You will now have an <tt>/openacs-4</tt> directory with all of
+ OpenACS required by dotLRN. To double check, your
+ <tt>/openacs-4/packages</tt> directory should look similar to this:
+
+ <pre>
+ $ ls
+ acs-admin acs-kernel acs-templating forums
+ acs-api-browser acs-mail acs-util general-comments
+ acs-bootstrap-installer acs-mail-lite acs-workflow news
+ acs-content acs-messaging attachments notifications
+ acs-content-repository acs-notification bulk-mail page
+ acs-core-docs acs-reference calendar ref-timezones
+ acs-datetime acs-service-contract CVS search
+ acs-developer-support acs-subsite faq skin
+ acs-events acs-tcl file-storage user-preferences
+ </pre>
+
+ <p class="heading">Get dotLRN from CVS</p>
+
+ <p class="indent">
+ Getting dotLRN from CVS is just like getting OpenACS from CVS
+ with a different CVSROOT.
+
+ <p class="indent">
+
+ Change to your <tt>/openacs-4/packages</tt> directory issue the
+ following commands:
+
+ <pre>
+ cvs -d :pserver:anonymous@dotlrn.openforce.net:/dotlrn-cvsroot login
+ (hit return for prompted for password)
+ cvs -z3 -d :pserver:anonymous@dotlrn.openforce.net:/dotlrn-cvsroot co dotlrn-core
+ </pre>
+
+ <p class="indent">
+ This will fetch the following packages to your
+ <tt>/openacs-4/packages</tt> directory<BR>
+ <font color=red>(Updated August 29: removed research-portlet and dotlrn-research)</font>:
+
+ <p class="indent">
+
+ <pre>
+ dotlrn
+ dotlrn-syllabus
+ new-portal
+ profile-provider
+ user-profile
+ bm-portlet
+ dotlrn-bm
+ calendar-portlet
+ dotlrn-calendar
+ dotlrn-portlet
+ dotlrn-dotlrn
+ faq-portlet
+ dotlrn-faq
+ forums-portlet
+ dotlrn-forums
+ fs-portlet
+ dotlrn-fs
+ news-portlet
+ dotlrn-news
+ static-portlet
+ dotlrn-static
+ </pre>
+
+ <p class="indent">
+
+ A few minor
+ modifications of the OpenACS code needs to be done here. First,
+ in the <tt>/openacs-4</tt> directory (where you see the <tt>bin,
+ CVS, packages ...</tt> directories), make sure a directory named
+ <tt>content-repository-content-files</tt> exists. If not, create
+ it with the same permissions as the other dirs. Second, create a
+ <tt>graphics</tt> directory inside the <tt>www</tt>
+ directory. Third, copy all the files in
+ <tt>/packages/dotlrn/www/graphics</tt> into the
+ <tt>graphics</tt> directory you just created.
+
+ <p class="indent">
+ Next, copy the <tt>/openacs-4</tt> directory to where ever you
+ prefer your webserver root to be, traditionally
+ <tt>/web</tt>. Now you can continue with the OACS <a
+ href="http://openacs.org/doc/openacs-4/openacs.html">installation
+ document</a> at the third bullet point. Continue with the
+ standard OACS installation process until your reach the
+ "Congratulations!" front page, then return here.
+
+ <p class="heading">Install dotLRN on your system</p>
+ <p class="indent">
+
+ Go the the "ACS Package Manager" (APM) on your system
+ at <tt>http://yourserver/acs-admin/apm</tt> and hit the
+ "Install packages" link. After the installer loads, you
+ will see a list of the packages you just got from CVS. Click the
+ button at the bottom of the page to Install them. You do not
+ have to restart your server at ths point.
+ </p>
+
+ <p class="indent">
+
+ Next go to the "Site Map" on your system at
+ <tt>http://yourserver/admin/site-map</tt>. Click the "new
+ sub folder" link to the right of the "Main Site"
+ link at the top of the table. Enter <tt>dotlrn</tt> in the
+ textbox, and hit the button.
+
+ </p>
+
+ <p class="indent">
+
+ There will be a new entry in the URL column for
+ "dotlrn" with "(none)" in the application
+ column, to the right of this, click the "New
+ Application" link. Enter <tt>dotlrn</tt> into the textbox
+ and select "dotLRN" from the drop-down list and hit the
+ button.
+
+ </p>
+
+ <p class="indent">
+
+ There will now be "dotlrn" in the application column to
+ the right of the "dotlrn/" URL.
+
+ </p>
+
+ <p class="indent">
+
+ Install the
+ "notifications" and "attachments" packages at
+ the URL "/notifications" and
+ "/attachments"the same way you installed
+ "dotlrn"
+
+ </p>
+
+ <!-- Add note about developer-support here -->
+
+ <p class="indent">
+
+ Next you must set some parameters from the <tt>Site Map</tt>
+ page.
+
+ <ul>
+
+ For the "Main
+ site" (the first row of the table at
+ the top of the page), set the "DefaultMaster" parameter
+ from <tt>/www/default-master</tt> to
+ <tt>/packages/dotlrn/www/dotlrn-master</tt>.
+
+ <li>For the <tt>ACS Kernel</tt> (the first item in the list below
+ the table) in the <tt>system-information</tt> section, set the
+ <tt>CommunityMemberURL</tt> from <tt>/shared/community-member</tt> to
+ <tt>/dotlrn/community-member</tt>
+
+ <li>In the same <tt>system-information</tt> section, set the
+ <tt>CommunityMemberAdminURL</tt> from <tt>/acs-admin/users/one</tt> to
+ <tt>/dotlrn/admin/user</tt>
+
+ </ul>
+ </p>
+
+ <p class="indent">
+
+ <b>You must now restart your server, wait a few minutes, and
+ reload the "Site Map" page in your browser</b> After
+ the server restarts, refresh the "Site Map". You will
+ see a "(+)" to the left of the dotlrn/ URL and a new
+ URL: "portal/" with application "new-portal".
+
+ </p>
+
+ <p class="note">
+
+ Aren't seeing the "(+)" beside <tt>dotlrn/</tt>?
+ Something went wrong. Did you restart your server? Restart again
+ while doing a <tt>tail -f</tt> of the error log with debug turned
+ on in your AOLServer configuration. Please report all errors you
+ encounter to <a href="/bugs">the Bug Tracker</a>.
+ </p>
+
+ <!-- TODO: re-vamp this section -->
+
+ <p class="heading">Explore dotLRN</p>
+
+ <p class="indent">
+
+ Go to dotLRN Administration at
+ <tt>http://yourserver/dotlrn/admin</tt>. Make some dotLRN
+ users, terms, departments, classes.
+
+ </p>
+
+ <p class="indent">
+
+ Here are some suggestions for things to check out in dotlrn:
+
+ </p>
+
+ <p class="indent">
+
+ Goto /dotlrn your "workspace". Click the "Control Panel" link at
+ the top and try the "Customize this portal" link there. Goto
+ the admin pages for a class or community and try the "Manage
+ Membership" link. Create a new sugroup for a class or community.
+ Edit or create new "Custom Portlets".
+
+ </p>
+
+
+ <p class="indent">
+
+ Enjoy!
+
+ </p>
+
+ <p class="heading">Automatated Installation</p>
+
+ <p class="indent">
+
+
+ <font color=red>(new Oct 11)</font>
+ As an alternative to the manual installation above. Peter Marklund
+ (peter_marklund@fastmail.fm) has developed scripts to automate installation.
+ If you are just starting out with dotlrn, it would be a good idea to
+ go through the manual installation a few times before trying to use
+ the automated scripts.
+
+ To get the scripts, use the following commandline:
+
+ <pre>cvs -d :pserver:anonymous:@dotlrn.collaboraid.biz:/cvsroot checkout dotlrn-install</pre>
+
+ </p>
+
+
+ <p class="heading">Manual Re-installation</p>
+
+ <p class="indent">
+
+ Sometimes you have to dump your DB. Here's the dotLRN reinstall
+ process.
+
+ <p class="indent">
+ <strong>Important note:</strong>If you have the dotlrn-survey,
+ and/or survey-portlet directories on your system, please delete them as
+ they are no longer part of the <tt>dotlrn-core</tt> packages. If you
+ are not using simple-survey aside from dotlrn, you can delete that too.
+
+ <ol>
+ <li>Stop <tt>aolserver</tt> and any open <tt>sqlplus</tt>
+ sessions <li>Create a drop/create user script. Lars has a swift
+ <a href="http://pinds.com/acs-tips/oracle-statements">tool</a>
+ to help you create one. <li>In a shell, type:
+ <pre class="code">
+ % sqlplus internal < my-drop-create-script.sql
+ </pre>
+
+ Verify that your database user was droped and created
+ successfully. If you get an error saying: <tt>Cannot drop a
+ user that is currently connected</tt>, close all open
+ <tt>sqlplus</tt> sessions and repeat the command above.
+ <li>Now would be a good time to <tt>cvs update</tt> OpenACS and dotLRN
+ <li>Re-start <tt>aolserver</tt>, wait 20 seconds or so, and
+ do the standard OpenACS installation.
+ <li>Go to the <strong>Install dotLRN on your system</strong>
+ section of this document and continue from there.
+
+</div>
Index: openacs-4/packages/dotlrn/www/doc/index.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/index.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/index.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,15 @@
+<master src="master">
+<property name="title">dotLRN Documentation</property>
+<h2>dotLRN Documentation</h2>
+part of <a href=../>dotLRN</a>
+<hr><p>
+
+<ul>
+<li> <a href="dotlrn-install">Installation</a>
+<li> <a href="dotlrn-faq">FAQ</a>
+<li> <a href="nomenclature">Nomenclature</a>
+<li> <a href="permission-api">Permissions API</a>
+<li> <a href="permission-overview">Permissions Overview</a>
+<li> <a href="permission-portals">Permissions Portals</a>
+<li> <a href="writing-a-dotlrn-package">Writing a dotLRN Package</a>
+</ul>
Index: openacs-4/packages/dotlrn/www/doc/master.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/master.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/master.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,2 @@
+<master>
+<slave>
\ No newline at end of file
Index: openacs-4/packages/dotlrn/www/doc/nomenclature.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/nomenclature.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/nomenclature.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,286 @@
+<master src="master">
+<property name="title">dotLRN Nomenclature</property>
+
+<h1>dotLRN Nomenclature: a dotLRN Primer</h1>
+by <a href=mailto:ben@openforce.net>Ben Adida</a>, part of <a
+href=./>dotLRN Documentation</a>. (last updated: <i>28 February 2002</i>)
+<hr><P>
+
+dotLRN is a <strong>Learning Community Management System</strong>
+which means it helps manage communities of users and the exchange of
+information therein. This document defines the
+<strong>nomenclature</strong> in the dotLRN project, with specific
+examples of how this nomenclature can be used in the context of
+dotLRN's primary use: that of a Course Management System.
+
+<p>
+<h2>1. dotLRN Communities</h2>
+The core concept within dotLRN is the <b>dotLRN User Community</b>.
+
+<h3>Community</h3>
+
+A community is a group of users that work together and exchange
+various types of information. There may be different types of
+communities, but all have basic properties, such as a community name
+and community ID.
+
+<p>
+
+<h3>Class</h3>
+
+A <b>class</b> is a topic of instruction, such as "Finance 101." A
+class is <b><i>not</i></b> a community (this will become clearer
+soon).
+
+<p>
+
+<h3>Class Instances and Clubs</h3>
+
+Two basic types of communities implemented in core dotLRN are
+<b>Class Instances</b> and <b>Clubs</b>. Class Instances are
+for structured groups of students, while Clubs are for unstructured
+student activities. A Class Instance, as its name indicates, is a
+specific instance of a Class. "Finance 101 - Spring 2002" is an
+instance of "Finance 101." It doesn't make sense for "Finance 101,"
+the topic of instruction, to be itself a community, since Finance 101
+Fall 2000 and Finance 101 Spring 2005 will probably have nothing to do
+with on another apart from teaching approximately the same material.
+
+<p>
+
+<h3>Open, Wait, Closed Communities</h3>
+
+Communities can have one of three <b>Join Policies</b>. A join policy
+defines the process by which a dotLRN User can become a member of the
+community. For now, we will consider only <b>dotLRN Full Access
+Users</b> (see below for more information on other types of dotLRN
+users).
+
+<p>
+
+A community with <b>open join policy</b> is visible in read-only
+state to non-members. Any full-access user can join the community at
+will, without the intervention of any other user.
+
+<p>
+
+A community with <b>wait join policy</b> is visible in read-only state
+to non-members. A full-access user can apply to join the
+community. The application must be approved by an administrator of the
+community.
+
+<p>
+
+A communty with <b>closed join policy</b> is not visible to
+non-members. Users become members only when explicitly added by the
+community administrator.
+
+<p>
+
+<h3><i>in MIT SloanSpace</i>: Class Instances and Communities</h3>
+
+In MIT SloanSpace, dotLRN Communities are referred to as <b>SloanSpace
+Groups</b>, while dotLRN Clubs are referred to as <b>SloanSpace
+Communities</b>.
+
+<p>
+
+The reason for this potential nomenclature confusion is historical:
+SloanSpace v1.0 used a certain terminology. It would be unacceptable
+to change it for SloanSpace v2.0. Similarly, it would be unacceptable
+to stick to the SloanSpace nomenclature and impose it to all users of
+dotLRN.
+
+<p>
+
+Thus, dotLRN nomenclature, although internally self-consistent, is
+entirely configurable by the user using global parameters.
+
+<h2>2. dotLRN Users</h2>
+
+A <b>dotLRN User</b> is an individual with an email address username and a
+password to the dotLRN system. Each user is uniquely identified by
+email address.
+
+<h3>Access Level: Limited or Full</h3>
+
+dotLRN users can have either <b>Limited Access</b> or <b>Full
+Access</b>.
+
+<p>
+
+A <b>limited-access user</b> is one who has access only to class instances
+and communities she is registered for and has no ability to
+browse any other section of the dotLRN application. This applies even
+to open communities: if a limited-access user is not a member of a
+given open community, she will not be able to browse any page that may
+enable her to become a member.
+
+<p>
+
+A <b>full-access user</b> is one who has access to all browsing
+sections of the dotLRN application. A full-access user can surf around
+and register for open communities, apply to be accepted into wait
+communities, etc... A full-access user also has the ability to store
+user-specific information, like personal files and personal calendar events.
+
+<p>
+
+<h3>Access to Private Information</h3>
+
+Certain users of the system may be <b>dotLRN Guests</b>, meaning that
+they do not belong to the parent organization that runs the dotLRN
+instance. These guests may participate in the community as
+full-fledged members but, for certain legal or privacy reasons, may
+not be allowed to view other users' private information.
+
+Any dotLRN user can be a guest or a non-guest. Full-access members can
+be guests. The only difference between a guest and non-guest is
+whether private user information (email address, address, phone #,
+etc...) can be read by these guests.
+
+<h3>System-Wide Roles</h3>
+
+dotLRN users have system-wide profile information. For example, in the
+context of a Course Management System like MIT SloanSpace, they may be
+<b>Professors</b>, <b>Students</b>, or <b>Administrative Staff</b>.
+These system-wide roles define the user's specific profile in the
+system as a whole, without regards to community-specific roles.
+
+<p>
+
+<h3>Community-Specific Roles</h3>
+
+dotLRN users have specific roles within the communities they belong
+to. These roles are classified in two main categories: <b>dotLRN
+Community Members</b> and <b>dotLRN Community Admins</b>.
+
+<p>
+
+<b>dotLRN Community Members</b> of a given community have normal
+read/write access to a community. They cannot perform administrative
+functions, like create a new forum, add group calendar events, create
+a new survey, etc... However, they can contribute to existing
+discussion forums, view calendar events, and respond to surveys.
+
+<p>
+
+<b>dotLRN Community Admins</b> have all the privileges of normal
+community members <i>plus</i> complete administrative rights over all
+components of the community. dotLRN Community Admins completely
+control a community: they need no further help from any other users to
+add data, applications, or users to their workspace.
+
+
+<h2>3. dotLRN Applets</h2>
+
+A dotLRN community is mostly a container of users and applets. A
+<b>dotLRN Applet</b> (nothing to do with a Java applet) is a small
+application that can be added to the community to enable new
+functionality.
+
+<p>
+
+Examples of existing applets include: Discussion Forums, Surveys,
+FAQs, News, Calendaring. These applets are <b>scoped</b> in order to
+correctly segment communities from one another. Data that belongs to
+one community is not viewable by another: it is as if it doesn't exist
+unless you are in the appropriate community.
+
+<p>
+
+Certain applets are <b>community-centric</b> in that they offer
+functionality that makes sense only in the context of a given
+community. Discussion Forums is one solid example of this: a
+discussion forum must pertain to a given community.
+
+<p>
+
+Other applets are <b>user-centric</b> in that they also manage data
+that is user-related, not linked to any given community. Calendaring
+is one such applet: although there are community events, there are
+also personal events.
+
+<p>
+
+<h2>4. Portals</h2>
+
+The entire dotLRN architecture is based on the <b>New Portal
+Architecture</b>. The design and specifics of this architecture are
+described in another document, but the basic terminology and concepts
+are as follows.
+
+<p>
+
+<h3>Portal Page</h3>
+
+A <b>Portal Page</b> is a single page display of portal boxes. A
+portal page has a <b>Portal Layout</b> that defines how the boxes are
+arranged on the page. Common layout schemes include 2-column,
+3-column, 3-column-with-header. New portal layouts can be implemented
+at will.
+
+<p>
+
+A portal page can be configured so that the portal boxes can be moved
+around the page by someone with appropriate permissions.
+
+<h3>Portal</h3>
+
+A <b>Portal</b> is a set of portal pages that are tied together so
+that a browser may navigate easily between the various portal
+pages. This is particularly useful when portal boxes need to be
+organized by functionality theme.
+
+<h3>Portlet or Portal Datasource</h3>
+
+A <b>Portlet</b> or <b>Portal Datasource</b> is a set of functionality
+that is presented in the form of a portal box. A bboard portlet, for
+example, is functionality that displays discussion forums inside a
+portal box.
+
+<h3>Portal Element</h3>
+
+A <b>Portal Element</b> is a single box on a given portal page. A box
+that display discussion forum information on Jane Doe's personal
+portal page #2 is <b><i>one</i></b> portal element that corresponds to
+the instantiation of portlet within a portal page.
+
+<p>
+
+A portal element can be moved, shaded, or hidden altogether, given the
+appropriate permissions. It can be moved to a different page of the
+same portal. While a portlet can be instantiated multiple times within
+a given portal, a portal element is unique per portal as it represents
+a single instance of the portlet: thus, a portal element can appear on
+only one page of the portal in one location. To appear in more than
+one place, a new instance of the portlet would have to be instantiated.
+
+<h3>Portal Themes</h3>
+
+A portal page can be rendered in a given <b>Portal Theme</b> that
+determines the look-and-feel of each box. The layout is <b>NOT</b>
+determined here, only the specific look-and-feel of portal element
+borders, buttons, and internals.
+
+<h3>Portlet Parameters; Portal Element Parameter Values</h3>
+
+For each portlet, there is a set of <b>Portlet Parameters</b>. For
+example, the calendar portlet has a <tt>calendar_view</tt> parameter
+that indicates whether the portlet should display data in the form of
+a list, day-, week-, or month- view.
+
+<p>
+
+Each Portal Element has <b>Portal Element Parameter Values</b> for
+each parameter of the portlet it instantiates. For example, the
+calendar portal element on Jane Doe's personal portal may have a value
+of "day" for the <tt>calendar_view</tt> parameter.
+
+<p>
+
+<h3>Portal Template</h3>
+
+A portal template is much like any other portal, except that it is
+used as a template for creating other portals.
+
Index: openacs-4/packages/dotlrn/www/doc/permission-api.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/permission-api.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/permission-api.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,89 @@
+<master src="master">
+<property name="title">dotLRN Roles, Sections, and Permissions</property>
+
+<h2>dotLRN Permission API</h2>
+by <a href=mailto:ben@openforce.net>Ben Adida</a>.
+<hr><P>
+
+The dotLRN access control mechanism will rely on OpenACS's permissions
+system, but will be completely layered. This means the underlying
+permission scheme can change.
+
+<p>
+
+<h3>Relational Segments & Context IDs</h3>
+
+In order to make things much cleaner with respect to permissions, we
+use relational segments and context IDs. The goal of relational
+segments will be to determine groups of users to whom permissions
+are granted. The goal of context IDs will be to create a hierarchy of
+objects so that as new components are added to subcommunities,
+permissions are naturally extended in appropriate ways.
+
+<p>
+
+For this to work, the actual privileges used throughout dotLRN and all
+of its modules must be <b>consistent</b>. Since permissions follow an
+inheritance path, we must make sure everything bootstraps off the
+basic read, write, create, delete, admin privileges.
+
+<p>
+
+To better explain the situation, we want the following to happen:
+<ul>
+<li> Hal is a member of "Intro to Computer Science Spring 2002" group, with relationship
+type <tt>dotlrn_instructor_rel</tt> to that group.
+<li> An FAQ about the Computer Science Program is created for "Intro
+to Computer Science Spring 2002", with <tt>context_id</tt> pointing to
+the course.
+<li> A relational segment "Intro to CS Spring 2002 Instructors" is
+created on the "Intro to CS Spring 2002" group and
+<tt>dotlrn_instructor_rel</tt> relationship type.
+<li> The privilege <tt>faq_admin</tt> exists, inheriting from
+the core OpenACS <tt>admin</tt> privilege.
+<li> A permission is granted: "Intro to CS Spring 2002 Instructors"
+are given the <tt>admin</tt> privilege on the course "Intro to
+CS Spring 2002".
+<li> <b>Thus</b>, automatically, Hal has the right to admin the FAQ,
+because the admin privilege translates to the faq_admin privilege by
+inheritance, Hal is part of the relational segment in question, and
+the FAQ in question has a context_id pointing to the course. It's BEAUTIFUL!
+</ul>
+
+<h3>General Roles API</h3>
+
+These are fairly straight-forward:
+<ul>
+<li> <tt>dotlrn::user_add user_id</tt>
+<li> <tt>dotlrn::user_remove user_id</tt>
+<p>
+<li> <tt>dotlrn::guest_add community_id user_id</tt>
+<li> <tt>dotlrn::guest_remove community_id user_id</tt>
+</ul>
+
+<h3>Access Control API</h3>
+
+<ul>
+<li> <tt>dotlrn::user_can_browse_p ?user_id?</tt>
+<li> <tt>dotlrn::require_user_browse ?user_id?</tt>
+<p>
+<li> <tt>dotlrn::user_can_read_sensitive_data ?user_id?</tt>
+<li> <tt>dotlrn::require_user_read_sensitive_data ?user_id?</tt>
+<p>
+<li> <tt>dotlrn::user_can_read_community_type_p community_type ?user_id?</tt>
+<li> <tt>dotlrn::require_user_read_community_type community_type
+?user_id?</tt>
+<p>
+<li> <tt>dotlrn::user_can_read_community_p community_id ?user_id?</tt>
+<li> <tt>dotlrn::require_user_read_community community_id
+?user_id?</tt>
+<p>
+<li> <tt>dotlrn::user_community_member_p community_id ?user_id?</tt>
+<li> <tt>dotlrn::require_user_community_member community_id
+?user_id?</tt>
+<p>
+<li> <tt>dotlrn::user_can_admin_community_p community_id
+?user_id?</tt>
+<li> <tt>dotlrn::require_user_admin_community community_id ?user_id?</tt>
+
+</ul>
Index: openacs-4/packages/dotlrn/www/doc/permission-overview.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/permission-overview.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/permission-overview.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,248 @@
+<master src="master">
+<property name="title">dotLRN Roles, Sections, and Permissions</property>
+
+<h2>dotLRN Roles, Sections, and Permissions</h2>
+by <a href=mailto:ben@openforce.net>Ben Adida</a>, part of <a href=./>dotLRN Documentation</a>.
+<hr><P>
+
+dotLRN includes significant components of functionality and an
+architecture for integrating these components. Around these
+components, there must be a coherent and consistent model for roles
+and permissions throughout the system. This document defines the
+necessary roles, application sections, and rules for access in the
+dotLRN application.
+
+<h2>Roles</h2>
+
+Roles in the dotLRN system are considered from a logical
+standpoint. It is perfectly conceivable that an actual user take on
+more than one role. It is also conceivable that a logical role is
+represented by multiple physical underlying roles and permissions.
+<p>
+
+<h3>Unregistered Visitor</h3>
+An unregistered visitor is simply a user who browses the dotLRN
+application without login information. An installation of dotLRN may
+disallow unregistered visitors, if it so chooses.
+
+<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
+2002 Section A), and who has been approved (usually by a professor, a
+TA, or an administrator).
+
+<h3>TA of a Class Instance</h3>
+A TA of an instance of a class is a registered user who serves as a
+Teaching Assistant for the class, having some administrative
+responsibilities. TAs are usually designated by professors or
+administrators of a class's instance.
+
+<h3>Administrator of a Class Instance</h3>
+An administrator of an instance of a class is a registered user who
+serves to perform organizational/administrative duties for the class,
+including registration, schedule and venue arrangements, etc...
+
+<h3>Instructor of a Class Instance</h3>
+An instructor of an instance of a class is a registered user who
+teaches the actual class instance in question. Instructors are often
+professors, but may not be (thus the use of the more functional term
+"Instructor" rather than the status term "Professor").
+
+<h3>Member of a Graduating Year</h3>
+A member of a graduating year is a registered user who is a student of
+a particular graduating year. This grouping may be needed for mass
+mailings, alumni clubs, etc...
+
+<h3>Member of a Community</h3>
+A member of a community is a registered user who has signed up (and
+been approved) to be part of one of the dotLRN communities. A
+community functions much like a class instance, but without the
+association to the teaching of a particular subject.
+
+<h3>Administrator of a Community</h3>
+An administrator of a community is a registered user assigned to
+coordinate a particular community.
+
+
+<h2>Sections of the Application</h2>
+
+The dotLRN Application is composed of a number of sections which
+serve various roles. These sections can be described with a varying
+level of granularity. The following description matches the necessary
+level of granularity for matching permissions and roles.
+
+<h3>Main Public Site</h3>
+
+Every dotLRN site will have a completely public section that describes
+the general purpose of the application. This will be mostly
+information material, with very little interactivity of any kind.
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> All registered dotLRN users can access this section
+<li> Guests or unregistered visitors cannot access this section
+</ul>
+
+
+<h3>Per-Class Main Page</h3>
+
+Each class (e.g. Micro-Economics) will have a section in the dotLRN
+application. This section will describe the goals of the class,
+general information about it, and will remain unrelated to any
+specific instance of the class.
+<p>
+A registered student of an instance of that class will be presented
+with links to the proper instance-specific sections.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<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>
+
+
+<h3>Per-Class Admin Page</h3>
+
+Each class will have an administrative section in the dotLRN
+application which will enable users to:
+<ul>
+<li> create new instances of the class
+<li> assign instructors, TAs, and administrators to existing instances
+of classes
+<li> edit standard class information (description blurb, etc...)
+</ul>
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> Only dotLRN system administrators can access this section
+</ul>
+
+<h3>Per-Class-Instance Main Page</h3>
+
+Each class instance (e.g. Micro-Economics, Spring 2002 Section A) will
+have a section in the dotLRN application. This section will look very
+different depending on the state of the visitor.
+<p>
+For a <strong>registered student, TA, or Instructor</strong> of the
+class instance, the section will present all available options for the
+particular instance, including discussion forums, file storage, FAQ,
+surveys,etc...
+<p>
+For a <strong>user not registered with this class instance</strong>,
+the section will present general information about the class instance,
+possibly some public files (like a syllabus), and the ability to
+request registration for the class.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<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>
+
+Each class instance will have an administrative section which will
+allow for:
+<ul>
+<li> membership management (approval, rejections, etc...)
+<li> access to various subpackage administration (bboard, FAQ, news, etc..)
+<li> general information updates (class instance blurbs)
+</ul>
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> Only class instance administrators, TAs, and instructors can
+access this section
+</ul>
+
+<h3>Per-Class-Instance-Package Main Page</h3>
+
+Each package within a class instance defines a section of the dotLRN
+application (e.g. bboards for Micro-Economics, Spring 2002 Section
+A). The functionality for these sections will be specific to the
+subpackages involved.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> Only registered users associated with this class instance can
+access this section
+</ul>
+
+<h3>Per-Class-Instance-Package Admin Page</h3>
+
+By the same token, each package within a class instance defines a
+section of the dotLRN application for administration. The
+functionality is subpackage-specific.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> Only instructors, TAs, and administrators of the class instance
+in question can access this section
+</ul>
+
+
+<h3>Per-Community Main Page</h3>
+
+dotLRN will also support communities, each of which will have its own
+section, much like a class instance. This section will lead to all
+subpackages supported by this community. Users who are members of the
+community will access all functionality, while other users will only
+see basic community information.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<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>
+
+
+<h3>Per-Community Admin Page</h3>
+
+By the same token, each community will have an admin section that
+allows community administrators to manage community membership,
+general information and subpackages.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> Only community administrators can access this section
+</ul>
+
+
+<h3>Per-User Main Page</h3>
+
+Each user will have a main page that centralizes access to all of that
+user's class instances, communities, and all the data within these
+sections. This is a personal view on every piece of user-relevant data.
+
+<p>
+<h4>Permissions</h4>
+<ul>
+<li> Only the user in question can access her main page.
+</ul>
Index: openacs-4/packages/dotlrn/www/doc/permission-portals.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/permission-portals.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/permission-portals.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,98 @@
+<master src="master">
+<property name="title">dotLRN Portal Permissions</property>
+
+<h2>dotLRN Portal Permissions</h2>
+by <a href=mailto:arjun@openforce.net>Arjun Sanyal</a> and <a href=mailto:ben@openforce.net>Ben Adida</a>, part of <a href=./>dotLRN Documentation</a>.
+<hr><P>
+
+dotLRN presents itself to users by way of portals, i.e. pages that
+aggregate data from disparate sources, shown as "boxes" on the page,
+and allow these sources to be added, removed, and altered in various
+ways. Permissioning issues arise frequently: "Is a student allowed to
+remove the "Class Announcements" element of her portal?" is an example
+of a permissioning issue.
+<P>
+In general the system of permissions should be simple enough for the
+users to understand, but flexible enought to support all of the
+required features.
+<P>
+Also, the scope of this document is the permissions system related to
+the portal-based parts of dotLRN, for more documentation on the
+general permission scheme of dotLRN, see <a href=permission-overview.adp>dotLRN Roles, Sections, and Permissions</a>
+
+<h2>Some General Portal Ideas</h2>
+
+Students will have the ability to alter their personal portal, but up
+to the point specified by a class administrator. In the example given
+above, a class administrator could "lock" the "Class Announcements"
+element in student's personal portals so they would not have the power
+to remove it or alter its position. In this case, the administrator
+would have contol over <strong>more than one</strong> portal, i.e. her
+own personal portal and a "default" portal that is "cloned", including
+the "lock", to create each student's portal when she registers for the
+class.
+
+<P>
+
+Non-administrative users cannot grant any permission to anyone. Thus,
+an "Student X lets student Y read her portal" scenarios are avoided.
+
+<h2>Administrative Permissions</h2>
+
+The administrative permissions CREATE and DELETE are only given to
+those users whose roles are such that they would need to create and
+destroy portals for scenarios such as the one given above.
+
+<h3>CREATE</h3>
+<ul>
+<li>User can create a new portal. Used for creating default class portals
+<li>Granted to: Administrator role <strong>only</strong>, by default
+<li>Implies: DELETE, and READ, EDIT, ADMIN on newly created portals
+</ul>
+
+<h3>DELETE</h3>
+<ul>
+<li>User can destory this portal. Not granted to non-admin users.
+<li>Granted to: Admin users who have CREATE
+</ul>
+
+<h2>Portal-level Permissons for Non-Admin Users</h2>
+
+These permissions are at the level of individual portals for users
+such as students.
+
+<h3>READ</h3>
+<ul>
+<li>Grantee can read (view) this portal.
+<li>Granted to: A User for her individual portal.
+</ul>
+
+<h3>EDIT</h3>
+<ul>
+<li>Grantee can:
+ <ul>
+ <li>Add "Available" datasources
+ <li>Remove "unlocked" elements
+ <li>Move (shuffle) "unlocked" elements
+ <li>Edit user-editable element parameters
+ </ul>
+<li>Granted to: A User for her individual portal. Aggregates the
+permissions that a non-admin user will have, other than "READ".
+</ul>
+
+<h2>Portal-level Permissons for Admin Users</h2>
+
+Admin users with the CREATE permission will be granted the following
+permisson on the newly created portal.
+
+<h3>ADMIN</h3>
+<ul>
+<li>Grantee can:
+ <ul>
+ <li>Toggle "lock" on a portal element
+ <li>Set this portal page to be "cloned" from
+ <li>Set "non-user" parameters for elements
+ <li>Toggle portal element "availability"
+ </ul>
+<li>Granted to: A portal created with the CREATE permisson.
+</ul>
Index: openacs-4/packages/dotlrn/www/doc/writing-a-dotlrn-package.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/dotlrn/www/doc/writing-a-dotlrn-package.adp,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/dotlrn/www/doc/writing-a-dotlrn-package.adp 22 Jan 2003 14:23:38 -0000 1.1
@@ -0,0 +1,109 @@
+<master src="master">
+<property name="title">Writing a dotLRN Package</property>
+
+<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>