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 @@ + +dotLRN Architecture +

dotLRN Architecture

+by Ben Adida and Arjun Sanyal, part of dotLRN Documentation. +

+ + +dotLRN is built on OpenACS 4.x, a modular architecture for +community-oriented web applications. dotLRN is also +modular 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. + +

+ +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. + + +

dotLRN Community

+ +A dotLRN Community is architected as a series of +OpenACS components, with a heavy use of the subsite +concept. One community is represented by: + + + +

OpenACS Group

+ +The core dotLRN group type is dotlrn_community. This group +type defines some basic attributes that all communities have: + + +There are two different types of learning communities in the basic +dotLRN release: class instances and +clubs. While Clubs need no additional attributes, +Class Instances require information concerning the Term and Year of +the Class Instance. + +

Site Node

+ +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 community_id as a starting +point. + +

Instance of dotLRN Community Manager

+ +The core dotLRN OpenACS package is called dotlrn +(surprisingly enough). This package is meant to be remounted to handle +community types and specific communities. A package_id +corresponds to each community. + +

+ +The group types for these two dotLRN Community Types are +dotlrn_class_instance and dotlrn_club. + +

Use of NPA

+ +dotLRN makes heavy use of the New Portal Architecture. + +

+ +Each full-access user has a personal portal where all data from all +communities is centralized in one place. This is called the dotLRN +User Portal. + +

+ +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 dotLRN Community +Non-Member Portal. + +

+ +Each community also has an administrative portal which centralizes all +administrative functionality for that community. This is called the +dotLRN Community Admin Portal. + +

+ +Finally, each community member has her own dotlrn Community Member +Portal. 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 dotLRN +Community Portal Template that administrators of the community control. + +

dotLRN Applets

+ +dotLRN Communities have various packages of functionality. These +packages (dotLRN applets) 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. + +

+ +Thus, a dotLRN Applet is composed of three +pieces that may each be a separate OpenACS package: + +

+ +

+ +

NPA Interactions

+ +The relationship between the NPA and the portlet functionality is +explored in the NPA Architecture Manual. + +

+ +

dotLRN Applet API

+ +The relationship between dotLRN and the specific dotLRN-dependent +packages (dotlrn-bboard, dotlrn-faq, etc...) is defined using +ACS Service Contract. ACS Service Contract defines a standard +provider/consumer interface with special contract APIs. The dotLRN +system defines the dotLRN Applet Contract, which includes the +following operations: + + +

+ +The specifics of creating a dotLRN package are described in the dotLRN Package Creation Guide. 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 @@ + +dotLRN FAQ +

+ +

The dotLRN FAQ

+ +

part of dotLRN + +

Last updated: $Date: 2003/01/22 14:23:38 $ + +

Contents + +

+ + +

Basics + +

Q: What is dotLRN? +

+ + 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 OpenACS v4.5 and includes data model, + application logic, and templates to get you up and running very + quickly. + +

Q: Is dotLRN usable? +

+ + dotLRN is currently in alpha state. The + target audience at this time is mostly early + adopters. No backwards-compatibility will be ensured + until a beta version. That said, dotLRN is quite + stable as is and can most certainly be used to determine + near-term usability in a production environment. + +

Q: When will dotLRN ship? +

+ + dotLRN beta is planned for May 1st, 2002. dotLRN v1.0 is + planned for August 1st, 2002. + +

Q: How can I contribute? +

+ + We are currently developing our contribution mechanisms. +

If you are actively interested in helping us + develop these mechanisms, please contact us at dotlrn@openforce.net. + +

Q: What about this dotLRN Governance discussion? +

+ + The discussion is still under way. MIT Sloan will be providing + the framework for this in the very near future. + + +

State of dotLRN + Development + +

Q: So what version of OpenACS do I need to use? +

+ + dotLRN will work with: + +

+ +

+ dotLRN will probably work with: + +

+ +

+ dotLRN will NOT work with: + +

+ +

+ + When dotLRN is released as a complete tarball, we will specify + exactly which OpenACS tarball or other package you'll + be able to use. + +

Q: When will dotLRN be compatible with PostgreSQL? +

+ + 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. + +

Q: Can I use ACS Classic 4.2/4.3? +

+ + Due to numerous fixes and enhancements made by the OpenACS + developers, dotLRN will not 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. + +

Q: Can I get a tarball of the dotLRN CVS? +

+ + Contact us at dotlrn@openforce.net if + you are interested in a tarball. + + +

The OpenForce Role + in dotLRN + +

+ Q: What's the relationship between MIT Sloan and OpenForce? +

+ + MIT Sloan hired OpenForce to develop dotLRN to replace the aging + SloanSpace v1, which itself was built on ACS v3. + +

Q: How will OpenForce work with other OpenACS + developers? +

+ + 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. + +

Q: Will OpenForce develop, support, and/or host + dotLRN commercially? +

Absolutely. + +

Q: Will OpenForce preclude me from providing + my own services surrounding dotLRN? +

Absolutely not. + +

Q: But Why? Aren't you crazy to throw away + such clear business opportunity? +

+ + 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. + + +

dotLRN and OpenACS + +

Q: Is dotLRN a part of the OpenACS project? +

+ + 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. + +

Q: Will dotLRN be merged into OpenACS? +

+ This is a question to be answered by the OpenACS community. + + +

Licensing + +

Q: What are the terms of use for dotLRN? +

+ dotLRN is distributed under the GNU General Public License version 2. + + +

Miscellaneous + +

Q: How is dotLRN spelled and pronounced? +

+ + It's sometimes written as .LRN, but the spelling and + capitalization dotLRN is preferred. hackers who type a + lot usually write dotlrn. dotLRN is pronounced + "daught-learn" We are currently accepting voice + applications for the dotLRN MP3 pronounciation file. + +

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 @@ + +Installing dotLRN - OpenForce + +
+ +

Installing dotLRN

+ +

part of dotLRN

+ +

Last updated: $Date: 2003/01/22 14:23:38 $ + +

Contents

+ +
    +
  • Read the dotLRN FAQ +
  • Get and Install OpenACS from development CVS +
  • Get dotLRN from CVS +
  • Install dotLRN on your system +
  • Explore dotLRN +
  • Reinstalling dotLRN +
+ + +

Read the dotLRN FAQs

+ +

Get and Install OpenACS from development CVS

+ +

+ 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. +

+ +

+ + If you are installing OpenACS, follow the extensive + installation documentation. + Stop at the point + where the OpenACS installation instructions tell you to + "download OpenACS". Don't use the "Quick + Downloads"! Continue on with this document. + +

+ + 

      
+      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
+
+ +

+ 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". + +

+ + dotLRN requires some more modules that are not in + acs-core, but not all of the packages in the OpenACS + source tree. Next are the commands to get these modules. + +

+ Here's the current list of non-core packages needed for dotlrn: + +

+ 

+      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
+
+

+ +

+ Do not install or, if installed, remove these + packages since they conflict with dotlrn packages: portal + (conflicts with new-portal) and spam + (conflicts with bulk-mail) +

+ +

+ cd to the newly created /openacs-4/packages + directory before the next command. + +

+ 

 
+      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
+
+ +

+ Installation timesaver: In the /packages/ref-timezones/sql/common/ + directory, cut down the files to a few insert statements apiece. + This is fine for test system, and will save you a lot of time in the + installation process. + +

+ You will now have an /openacs-4 directory with all of + OpenACS required by dotLRN. To double check, your + /openacs-4/packages directory should look similar to this: + + 

+      $ 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
+
+ +

Get dotLRN from CVS

+ +

+ Getting dotLRN from CVS is just like getting OpenACS from CVS + with a different CVSROOT. + +

+ + Change to your /openacs-4/packages directory issue the + following commands: + + 

+      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       
+
+ +

+ This will fetch the following packages to your + /openacs-4/packages directory
+ (Updated August 29: removed research-portlet and dotlrn-research): + +

+ + 

+        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
+
+ +

+ + A few minor + modifications of the OpenACS code needs to be done here. First, + in the /openacs-4 directory (where you see the bin, + CVS, packages ... directories), make sure a directory named + content-repository-content-files exists. If not, create + it with the same permissions as the other dirs. Second, create a + graphics directory inside the www + directory. Third, copy all the files in + /packages/dotlrn/www/graphics into the + graphics directory you just created. + +

+ Next, copy the /openacs-4 directory to where ever you + prefer your webserver root to be, traditionally + /web. Now you can continue with the OACS installation + document at the third bullet point. Continue with the + standard OACS installation process until your reach the + "Congratulations!" front page, then return here. + +

Install dotLRN on your system

+

+ + Go the the "ACS Package Manager" (APM) on your system + at http://yourserver/acs-admin/apm 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. +

+ +

+ + Next go to the "Site Map" on your system at + http://yourserver/admin/site-map. Click the "new + sub folder" link to the right of the "Main Site" + link at the top of the table. Enter dotlrn in the + textbox, and hit the button. + +

+ +

+ + 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 dotlrn into the textbox + and select "dotLRN" from the drop-down list and hit the + button. + +

+ +

+ + There will now be "dotlrn" in the application column to + the right of the "dotlrn/" URL. + +

+ +

+ + Install the + "notifications" and "attachments" packages at + the URL "/notifications" and + "/attachments"the same way you installed + "dotlrn" + +

+ + + +

+ + Next you must set some parameters from the Site Map + page. + +

    + + For the "Main + site" (the first row of the table at + the top of the page), set the "DefaultMaster" parameter + from /www/default-master to + /packages/dotlrn/www/dotlrn-master. + +
  • For the ACS Kernel (the first item in the list below + the table) in the system-information section, set the + CommunityMemberURL from /shared/community-member to + /dotlrn/community-member + +
  • In the same system-information section, set the + CommunityMemberAdminURL from /acs-admin/users/one to + /dotlrn/admin/user + +
+

+ +

+ + You must now restart your server, wait a few minutes, and + reload the "Site Map" page in your browser 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". + +

+ +

+ + Aren't seeing the "(+)" beside dotlrn/? + Something went wrong. Did you restart your server? Restart again + while doing a tail -f of the error log with debug turned + on in your AOLServer configuration. Please report all errors you + encounter to the Bug Tracker. +

+ + + +

Explore dotLRN

+ +

+ + Go to dotLRN Administration at + http://yourserver/dotlrn/admin. Make some dotLRN + users, terms, departments, classes. + +

+ +

+ + Here are some suggestions for things to check out in dotlrn: + +

+ +

+ + 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". + +

+ + +

+ + Enjoy! + +

+ +

Automatated Installation

+ +

+ + + (new Oct 11) + 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: + + 

cvs -d :pserver:anonymous:@dotlrn.collaboraid.biz:/cvsroot checkout dotlrn-install
+ +

+ + +

Manual Re-installation

+ +

+ + Sometimes you have to dump your DB. Here's the dotLRN reinstall + process. + +

+ Important note: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 dotlrn-core packages. If you + are not using simple-survey aside from dotlrn, you can delete that too. + +

    +
  1. Stop aolserver and any open sqlplus + sessions
  2. Create a drop/create user script. Lars has a swift + tool + to help you create one.
  3. In a shell, type: + 
    +           % sqlplus internal < my-drop-create-script.sql
+
    + + Verify that your database user was droped and created + successfully. If you get an error saying: Cannot drop a + user that is currently connected, close all open + sqlplus sessions and repeat the command above. +
  4. Now would be a good time to cvs update OpenACS and dotLRN +
  5. Re-start aolserver, wait 20 seconds or so, and + do the standard OpenACS installation. +
  6. Go to the Install dotLRN on your system + section of this document and continue from there. + +
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 @@ + +dotLRN Documentation +

dotLRN Documentation

+part of dotLRN +

+ +

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 @@ + + \ 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 @@ + +dotLRN Nomenclature + +

dotLRN Nomenclature: a dotLRN Primer

+by Ben Adida, part of dotLRN Documentation. (last updated: 28 February 2002) +

+ +dotLRN is a Learning Community Management System +which means it helps manage communities of users and the exchange of +information therein. This document defines the +nomenclature 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. + +

+

1. dotLRN Communities

+The core concept within dotLRN is the dotLRN User Community. + +

Community

+ +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. + +

+ +

Class

+ +A class is a topic of instruction, such as "Finance 101." A +class is not a community (this will become clearer +soon). + +

+ +

Class Instances and Clubs

+ +Two basic types of communities implemented in core dotLRN are +Class Instances and Clubs. 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. + +

+ +

Open, Wait, Closed Communities

+ +Communities can have one of three Join Policies. A join policy +defines the process by which a dotLRN User can become a member of the +community. For now, we will consider only dotLRN Full Access +Users (see below for more information on other types of dotLRN +users). + +

+ +A community with open join policy 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. + +

+ +A community with wait join policy 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. + +

+ +A communty with closed join policy is not visible to +non-members. Users become members only when explicitly added by the +community administrator. + +

+ +

in MIT SloanSpace: Class Instances and Communities

+ +In MIT SloanSpace, dotLRN Communities are referred to as SloanSpace +Groups, while dotLRN Clubs are referred to as SloanSpace +Communities. + +

+ +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. + +

+ +Thus, dotLRN nomenclature, although internally self-consistent, is +entirely configurable by the user using global parameters. + +

2. dotLRN Users

+ +A dotLRN User is an individual with an email address username and a +password to the dotLRN system. Each user is uniquely identified by +email address. + +

Access Level: Limited or Full

+ +dotLRN users can have either Limited Access or Full +Access. + +

+ +A limited-access user 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. + +

+ +A full-access user 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. + +

+ +

Access to Private Information

+ +Certain users of the system may be dotLRN Guests, 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. + +

System-Wide Roles

+ +dotLRN users have system-wide profile information. For example, in the +context of a Course Management System like MIT SloanSpace, they may be +Professors, Students, or Administrative Staff. +These system-wide roles define the user's specific profile in the +system as a whole, without regards to community-specific roles. + +

+ +

Community-Specific Roles

+ +dotLRN users have specific roles within the communities they belong +to. These roles are classified in two main categories: dotLRN +Community Members and dotLRN Community Admins. + +

+ +dotLRN Community Members 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. + +

+ +dotLRN Community Admins have all the privileges of normal +community members plus 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. + + +

3. dotLRN Applets

+ +A dotLRN community is mostly a container of users and applets. A +dotLRN Applet (nothing to do with a Java applet) is a small +application that can be added to the community to enable new +functionality. + +

+ +Examples of existing applets include: Discussion Forums, Surveys, +FAQs, News, Calendaring. These applets are scoped 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. + +

+ +Certain applets are community-centric 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. + +

+ +Other applets are user-centric 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. + +

+ +

4. Portals

+ +The entire dotLRN architecture is based on the New Portal +Architecture. The design and specifics of this architecture are +described in another document, but the basic terminology and concepts +are as follows. + +

+ +

Portal Page

+ +A Portal Page is a single page display of portal boxes. A +portal page has a Portal Layout 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. + +

+ +A portal page can be configured so that the portal boxes can be moved +around the page by someone with appropriate permissions. + +

Portal

+ +A Portal 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. + +

Portlet or Portal Datasource

+ +A Portlet or Portal Datasource 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. + +

Portal Element

+ +A Portal Element 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 one portal element that corresponds to +the instantiation of portlet within a portal page. + +

+ +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. + +

Portal Themes

+ +A portal page can be rendered in a given Portal Theme that +determines the look-and-feel of each box. The layout is NOT +determined here, only the specific look-and-feel of portal element +borders, buttons, and internals. + +

Portlet Parameters; Portal Element Parameter Values

+ +For each portlet, there is a set of Portlet Parameters. For +example, the calendar portlet has a calendar_view parameter +that indicates whether the portlet should display data in the form of +a list, day-, week-, or month- view. + +

+ +Each Portal Element has Portal Element Parameter Values 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 calendar_view parameter. + +

+ +

Portal Template

+ +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 @@ + +dotLRN Roles, Sections, and Permissions + +

dotLRN Permission API

+by Ben Adida. +

+ +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. + +

+ +

Relational Segments & Context IDs

+ +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. + +

+ +For this to work, the actual privileges used throughout dotLRN and all +of its modules must be consistent. Since permissions follow an +inheritance path, we must make sure everything bootstraps off the +basic read, write, create, delete, admin privileges. + +

+ +To better explain the situation, we want the following to happen: +

    +
  • Hal is a member of "Intro to Computer Science Spring 2002" group, with relationship +type dotlrn_instructor_rel to that group. +
  • An FAQ about the Computer Science Program is created for "Intro +to Computer Science Spring 2002", with context_id pointing to +the course. +
  • A relational segment "Intro to CS Spring 2002 Instructors" is +created on the "Intro to CS Spring 2002" group and +dotlrn_instructor_rel relationship type. +
  • The privilege faq_admin exists, inheriting from +the core OpenACS admin privilege. +
  • A permission is granted: "Intro to CS Spring 2002 Instructors" +are given the admin privilege on the course "Intro to +CS Spring 2002". +
  • Thus, 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! +
+ +

General Roles API

+ +These are fairly straight-forward: +
    +
  • dotlrn::user_add user_id +
  • dotlrn::user_remove user_id +

    +

  • dotlrn::guest_add community_id user_id +
  • dotlrn::guest_remove community_id user_id +
+ +

Access Control API

+ +
    +
  • dotlrn::user_can_browse_p ?user_id? +
  • dotlrn::require_user_browse ?user_id? +

    +

  • dotlrn::user_can_read_sensitive_data ?user_id? +
  • dotlrn::require_user_read_sensitive_data ?user_id? +

    +

  • dotlrn::user_can_read_community_type_p community_type ?user_id? +
  • dotlrn::require_user_read_community_type community_type +?user_id? +

    +

  • dotlrn::user_can_read_community_p community_id ?user_id? +
  • dotlrn::require_user_read_community community_id +?user_id? +

    +

  • dotlrn::user_community_member_p community_id ?user_id? +
  • dotlrn::require_user_community_member community_id +?user_id? +

    +

  • dotlrn::user_can_admin_community_p community_id +?user_id? +
  • dotlrn::require_user_admin_community community_id ?user_id? + +
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 @@ + +dotLRN Roles, Sections, and Permissions + +

dotLRN Roles, Sections, and Permissions

+by Ben Adida, part of dotLRN Documentation. +

+ +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. + +

Roles

+ +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. +

+ +

Unregistered Visitor

+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. + +

Registered dotLRN Guest

+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. + +

Registered dotLRN User

+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. + +

Registered Student of an Instance of a Class

+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). + +

TA of a Class Instance

+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. + +

Administrator of a Class Instance

+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... + +

Instructor of a Class Instance

+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"). + +

Member of a Graduating Year

+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... + +

Member of a Community

+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. + +

Administrator of a Community

+An administrator of a community is a registered user assigned to +coordinate a particular community. + + +

Sections of the Application

+ +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. + +

Main Public Site

+ +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. +

+

Permissions

+
    +
  • All registered dotLRN users can access this section +
  • Guests or unregistered visitors cannot access this section +
+ + +

Per-Class Main Page

+ +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. +

+A registered student of an instance of that class will be presented +with links to the proper instance-specific sections. + +

+

Permissions

+
    +
  • All registered dotLRN users can access this section +
  • All guests of that class can access this section +
  • Registered users associated with a class instance of this class +will see specific links to the proper class instances +
+ + +

Per-Class Admin Page

+ +Each class will have an administrative section in the dotLRN +application which will enable users to: +
    +
  • create new instances of the class +
  • assign instructors, TAs, and administrators to existing instances +of classes +
  • edit standard class information (description blurb, etc...) +
+ +

+

Permissions

+
    +
  • Only dotLRN system administrators can access this section +
+ +

Per-Class-Instance Main Page

+ +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. +

+For a registered student, TA, or Instructor of the +class instance, the section will present all available options for the +particular instance, including discussion forums, file storage, FAQ, +surveys,etc... +

+For a user not registered with this class instance, +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. + +

+

Permissions

+
    +
  • All registered dotLRN users can access this section +
  • Guests for this class instance can see this section +
  • Only registered users and guests associated with this class instance can +access the full functionality +
  • Certain functionality (like class rosters) are only accessible to +full users, not to guests +
+ +

Per-Class-Instance Admin Page

+ +Each class instance will have an administrative section which will +allow for: +
    +
  • membership management (approval, rejections, etc...) +
  • access to various subpackage administration (bboard, FAQ, news, etc..) +
  • general information updates (class instance blurbs) +
+ +

+

Permissions

+
    +
  • Only class instance administrators, TAs, and instructors can +access this section +
+ +

Per-Class-Instance-Package Main Page

+ +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. + +

+

Permissions

+
    +
  • Only registered users associated with this class instance can +access this section +
+ +

Per-Class-Instance-Package Admin Page

+ +By the same token, each package within a class instance defines a +section of the dotLRN application for administration. The +functionality is subpackage-specific. + +

+

Permissions

+
    +
  • Only instructors, TAs, and administrators of the class instance +in question can access this section +
+ + +

Per-Community Main Page

+ +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. + +

+

Permissions

+
    +
  • All registered dotLRN users can access this section +
  • Guests of this specific community can access this section +
  • Only members of the community at hand can access +community-specific chunks/links +
+ + +

Per-Community Admin Page

+ +By the same token, each community will have an admin section that +allows community administrators to manage community membership, +general information and subpackages. + +

+

Permissions

+
    +
  • Only community administrators can access this section +
+ + +

Per-User Main Page

+ +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. + +

+

Permissions

+
    +
  • Only the user in question can access her main page. +
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 @@ + +dotLRN Portal Permissions + +

dotLRN Portal Permissions

+by Arjun Sanyal and Ben Adida, part of dotLRN Documentation. +

+ +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. +

+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. +

+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 dotLRN Roles, Sections, and Permissions + +

Some General Portal Ideas

+ +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 more than one 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. + +

+ +Non-administrative users cannot grant any permission to anyone. Thus, +an "Student X lets student Y read her portal" scenarios are avoided. + +

Administrative Permissions

+ +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. + +

CREATE

+
    +
  • User can create a new portal. Used for creating default class portals +
  • Granted to: Administrator role only, by default +
  • Implies: DELETE, and READ, EDIT, ADMIN on newly created portals +
+ +

DELETE

+
    +
  • User can destory this portal. Not granted to non-admin users. +
  • Granted to: Admin users who have CREATE +
+ +

Portal-level Permissons for Non-Admin Users

+ +These permissions are at the level of individual portals for users +such as students. + +

READ

+
    +
  • Grantee can read (view) this portal. +
  • Granted to: A User for her individual portal. +
+ +

EDIT

+
    +
  • Grantee can: +
      +
    • Add "Available" datasources +
    • Remove "unlocked" elements +
    • Move (shuffle) "unlocked" elements +
    • Edit user-editable element parameters +
    +
  • Granted to: A User for her individual portal. Aggregates the +permissions that a non-admin user will have, other than "READ". +
+ +

Portal-level Permissons for Admin Users

+ +Admin users with the CREATE permission will be granted the following +permisson on the newly created portal. + +

ADMIN

+
    +
  • Grantee can: +
      +
    • Toggle "lock" on a portal element +
    • Set this portal page to be "cloned" from +
    • Set "non-user" parameters for elements +
    • Toggle portal element "availability" +
    +
  • Granted to: A portal created with the CREATE permisson. +
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 @@ + +Writing a dotLRN Package + +

Writing a dotLRN Package

+by Ben Adida. +

+ +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. + +

+ +

The Structure of a dotLRN Package/Applet

+ +As far as dotLRN is concerned, a dotLRN package is an +applet (literally a "small application," nothing to +do with Java applets) that must provide a simple +API under the acs-service-contract mechanism. This API allows +the dotLRN core to generically dispatch calls to each dotLRN applet +when certain events happen. + +

+ +Thus, a dotLRN applet must be able to respond to the following events: +

    +
  • the applet is added to a community +
  • the applet is removed from a community +
  • a user is added to a community for which the applet in question +is enabled +
  • a user is removed from a community for which the applet in +question is enabled +
+ +Additional events may be added in the future to further enhance +generalized applet functionality. + +

+ +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 +NPA portlet. Note that the architecture of this +portlet is dotLRN-independent! The contents of the portlet may +rely on dotLRN functionality, but the means by which the portlet is +added to portal pages does not! + +

+ +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 three OpenACS 4 packages: + +

    +
  • a core functionality package (e.g. bboard), independent of dotLRN functionality +
  • a portlet package (e.g. bboard-portlet), whose interface to NPA +is independent of dotLRN functionality, but whose content may be +dotLRN-enhanced. +
  • 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. +
+ +

Core Functionality

+ +There is only one guideline in writing core functionality for a dotLRN +applet: make sure the package can be correctly scoped across +multiple subsites. 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. + +

Portlet

+ +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 +package_id), independently of any dotLRN functionality. + +

+ +For more details on creating a portlet package, check the New Portals Architecture + +

dotLRN Applet

+ +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. + +

+ +First, we will write the actual procs that we expect to eventually +hook into the dotLRN system. + +

+ +The first proc is called when the bboard applet is added to a community + +

+ad_proc -public dotlrn_bboard::applet_add {community_id} {} {
+	# Instantiate bboard and mount it
+}
+