Created by Joel Aufrecht, last modified by Malte Sussdorff 07 Aug 2007, at 04:24 PM
To start developing new code in OpenACS, we build a new package. A package
is a a discrete collection of web pages, tcl code, and database tables and procedures.
A package with user interface is called an
application;
a package which provides functions to other packages and has no direct interface, a
service. A package can be installed, upgraded, and
removed. It communicates with other packages through an API. This chapter walks you through
the minimum steps to create a useful package, including writing documentation, setting up
database tables and procedures, writing web pages, debugging, and automatic regression testing.
Before start with this tutorial read up the introduction on OpenACS Packages and http://www.linuxjournal.com/article/6337.
This tutorial uses the content repository package. This
radically simplifies the database work, but forces us to work
around the content repository's limitations, including an
incomplete TCL API. So the tutorial is messier than we'd like
right now. Code that is temporary hackage is clearly marked.
In this tutorial, we will make an application package for
displaying a list of text notes.
You will need:
A computer with a working installation of
OpenACS. If you don't have this, see Chapter2, Installation Overview
.
Example files, which are included in the
standard OpenACS 5.2.3rc1 distribution.
We use the ACS Package Manager (APM) to add, remove, and
upgrade packages. It handles package meta-data, such as lists of
files that belong in the package. Each package is uniquely
identified by a package key. To start developing a new
package, use the APM to create an empty package with our new
package key, myfirstpackage. This will create
the initial directories, meta-information files, and database
entries for a new package. (More info on APM)
Browse to
http://yourserver:8000/acs-admin/apm
.
-
Click Create a New Package.
Fill in the fields listed below. Ignore the rest (and leave the check boxes alone).
(Some will change automatically. Don't mess with those.)
Package Key:
myfirstpackage
Package Name:
My First Package
Package Plural:
My First Package
Package Type:
Application
Initial Version:
0.1d
Summary:
This is my first package.
At the bottom, click
Create Package.
This creates a package rooted at
/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage
.
This is the "home directory" of our new package, and all
files in the package will be within this directory. More on the structure of
packages).
In order to see your work in progress, you must create a
map between the URL space of incoming requests and the package application instance.
You do this by adding the application in the main site administration). This
creates a link between the incoming URL requests and an
instance of the application. (More on applications and nodes)
You can have instances of a package on one site, each with a
different URL and different permissions, all sharing the same
code and tables. This requires that a package be developed
package-aware. You'll see how to do that
in this tutorial.
By mounting the package, we've caused all requests to
http://yourserver.test:8000/my-first-package
to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
The remainder of the tutorial walks you through each file one at a time as you create the package. You can skip all this, and get a working package, by doing the following:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql
cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/
mkdir ../../../../myfirstpackage/lib
cp note-list.* ../../../../myfirstpackage/lib/
cp myfirstpackage-*sql ../../../../myfirstpackage/sql/postgresql/
cp myfirstpackage-procs.tcl ../../../../myfirstpackage/tcl/test/
cp note-procs.tcl ../../../../myfirstpackage/tcl/
After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.
Created by Gustaf Neumann, last modified by Malte Sussdorff 07 Aug 2007, at 04:18 PM
A good detailed, yet somewhat outdated
article is written by
Reuven Lerner for the Linux Journal. It gives a good introduction, but
please read on !
OpenACS (Open Architecture Community System) is an
advanced toolkit for building scalable, community-oriented
web applications. If you're thinking of building an
enterprise-level web application, OpenACS is a solid,
scalable framework for building dynamic content driven
sites.
OpenACS is a collection of pre-built applications and
services that you can use to build your web
site/application. Through a modular architecture, OpenACS
has packages for user/groups management, content
management, e-commerce, news, FAQs, calendar, forums, bug
tracking, full-text searching, and much
more.
OpenACS relies on AOLserver, the
free, multithreaded, scalable, Tcl-enabled,
web/application server used by America Online for most of
its web sites, and a true ACID-compliant Relational
Database Management System (RDBMS). Currently OpenACS
supports PostgreSQL, an open source RDBMS, and Oracle and
is easily extensible to other databases which support a
comparable feature set.
The OpenACS toolkit is derived from the ArsDigita
Community System (ACS). ArsDigita (now part of Red Hat,
Inc.) kindly made their work available under the GPL,
making all of this possible.
The OpenACS project was born when Don Baccus, Ben Adida, and
others decided to port ACS from Oracle to PostgreSQL, thus
making it a fully open-source solution. With OpenACS 4,
Oracle and PostgreSQL support were combined in one code base
and with OpenACS 5, support for internationalization and
localization has been added.
A vibrant and productive community has sprung up around the
OpenACS software and there are many volunteer contributors
as well as a commercial companies able to provide support,
hosting, and custom development. Many of the production
users are actively funding and contributing work back to the
project. Formal, consensus driven governance has been
established (with semi-annual elections) which ensures the
project serves the needs of it's constituents.
The OpenACS community would like to hear your comments and
can help you in your endeavors with the system. Visit our
web site and feel
free to ask questions or provide feedback.
Created by Anett Szabo, last modified by Anett Szabo 30 Jul 2007, at 01:58 PM
OpenACS: robust web development framework
Author: Rocael Hernández, Galileo University, Guatemala / OpenACS Core Team, roc@viaro.net
Author: Andrew Grumet, OpenACS Core Team, aegrumet@alum.mit.edu
Tcl/Tk 2005 Conference, Portland, Oregon
Abstract:
OpenACS is a full featured web development framework to create scalable applications
oriented to collaboration and online communities. Is in use by many big players such as
greenpeace.org or the e-learning platform of the MIT Sloan School of Management.
While the system is not trivial, here are explained some of the most interesting and still
relatively simple facilities that the framework provides. Everything from templating,
separating the code from the presentation, database interactions according to the
programming language, auto-documentation features, automated test engine,
internationalization, and many more are written in Tcl, which has shown to be extremely
powerful for writing the foundation logic and the application pages.
Created by Anett Szabo, last modified by Anett Szabo 30 Jul 2007, at 01:57 PM
3.1. Serving files: packages, instances, site-map, request processor
Like other Web environments OpenACS can serve familiar file types such as .html and
.gif files from a document root. The OpenACS standard document root is
$OACS_HOME/www. Put a file at $OACS_HOME/www/hello.html and it will appear
at http://yourserver.example.com/hello.html.
OpenACS can also run scripts that set up variables and display them in HTML-like
templates, and also embed templates within other templates via include and master/slave
tags. These topics are covered in the Template system section above. In the sections
below we explore OpenACS more advanced mechanisms for serving files.
3.1.1. Packages
OpenACS is modularized into a set of packages that can be found in the
$OACS_HOME/packages subdirectory. Each package may contain SQL scripts, Tcl
libraries and visible pages, as illustrated in the abbreviated directory layout below:
$OACS_HOME/
packages/
acs-admin/ # Core package.
acs-api-browser/ # Core package.
...
forums/ # Forums package.
catalog/ # i18n message catalogs.
forums.info # Package specification file.
lib/ # Re-usable tcl/adp templates.
sql/ # Data model scripts.
tcl/ # Tcl library.
www/ # Package document root.
forum-view.tcl
forum-view.adp
...
www/ # Default document root.
This example draws attention to the forums package, one of dozens of application
packages available for use with OpenACS. Other available packages include a Webbased
files storage system (which also is WebDAV-enabled), calendaring, blog
authoring, assessment, news aggregation, wikis, photo galleries, RSS support, XMLRPC,
SOAP support and many more. A full list of packages can be browsed at
http://cvs.openacs.org/cvs/openacs-4/packages/.
Packages are managed with the OpenACS package manager, which handles upgrades and
tracks versions, dependencies and files much like Linux package managers do.
A view of the Package Manager:
3.1.2. Site map, package instances, request processor
Each package can have its own document root that functions like the default document
root at $OACS_HOME/www. The document root for the forums package is located at
$OACS_HOME/packages/forums/www, as illustrated in the abbreviated directory layout
above.
Package document roots are mapped to visible URLs through a set of database tables,
configuration data, libraries and administration Web pages known collectively as the site
map. Using the site map we can map $OACS_HOME/packages/forums/www to, for
example, http://yourserver.example.com/tclers-forums/. But it gets more interesting,
because the site map allows for re-use of packages at multiple URLs. Hence we can host
a discussion forum for C programmers by adding a new site map entry that maps the
forums package to http://yourserver.example.com/cprogrammers-forums/.
These mappings are referred to in OpenACS-speak as “package instances”. As the
terminology hints, the mapping to /tclers-forums has distinct configuration data from the
mapping to /cprogrammers-forums. Hence the /tclers-forums instance might contain a
Tcl Forum, a Tk Forum and an AOLserver Forum, while the /cprogrammers-forums
instance contains a Small and Fast Forum and a Some Compilation Required Forum.
Because package instances are OpenACS objects, they can be have different permission
settings, so that some users may be able to read and post to the /tclers-forums but not the
/cprogrammers-forums, and vice-versa. The OpenACS object system will be covered in
more detail below.
Before doing that, let’s take a brief diversion into the mechanics of how files are served,
Requests for OpenACS Web pages pass through a Request Processor, which is a global
filter and set of Tcl procs that respond to every incoming URL reaching the server. The
following diagram summarizes the stages of the request processor assuming a URL
request like http://yourserver.example.com/notes/somepage.adp.
The stages are:
1. Search the Site Map, to map the URL to the appropriate physical directory in the
filesystem.
2. Authenticate the user.
3. Authorize the possible specific defined permissions that the site node might have.
4. Process the URL, search for the appropriate file and server it.
3.2. Object system and services
Deep in OpenACS’ design is the notion that one should be able to build common services
that are useful across the toolkit. Hence a commenting engine ought work equally well
for blog posts as it does for images in photo galleries. Furthermore, any sufficiently
interesting piece of data in the system ought to carry basic accounting information with it,
such as who created it and timestamps for creation and modification.
The OpenACS object system addresses these requirements by defining a central SQL
table called acs_objects and giving this table a column for each generic bit of
information. Most importantly, acs_objects has a primary key column, named
object_id. This primary key is the anchor on which all other information about an
object rests. If the object is a blog post, the post body might live in a separate table
blog_posts whose primary key, post_id, is a reference back to
acs_objects.object_id. If the object is an image, it might contain a binary field
containing the image bits or alternatively a text field pointing to the physical storage
location of the image file, and also an image_id primary key that is a reference back to
acs_objects.object_id. Since each blog post and each image has a row in
acs_objects, comments on either can be inserted into a table that contains an
on_what_object column that points back to the object_id.
Any data that participates in the OpenACS object system can tell us its title, what kind of
object it is, when it was created and by whom. It can also be assigned permissions,
commented on, categorized, have files attached to it, and benefit from any other objectlevel
services that we can dream up.
The OpenACS object system, site map and instances are the foundation of OpenACS.
More information about these can be found at the following URLs:
http://openacs.org/doc/openacs-5-1/request-processor.html
http://openacs.org/doc/openacs-5-1/subsites.html
http://openacs.org/doc/openacs-5-1/packages.html
3.3. Developer Support
OpenACS provides a set of developer support tools to improve the development process,
debugging, testing, and searching of the API. These tools enhance many of the day to day
activities of the developers.
The functionalities that developer support provides are:
1. Time to serve a given request. Good for performance problem detection and
improvement.
2. Tracing database calls involved in a given request, where the involved queries
are located, what was the actual query executed and how long did it take to return
the data. Useful for improving queries that might be slowing your application
performance.
3. Tracing scripts involved in serving a given request. Showing the time taken to
perform a given script, its location, code, and error that it might bring. Especially
important for tuning applications performance.
4. ADP reveal, to show in the browser which part of the rendered html belongs to a
given script.
5. User Switching, as an admin account switch easily to another account to
reproduce and test actions, and then simply go back to the administrator account.
6. OpenACS Shell, which is a Tcl shell with all the API available within OpenACS,
in order to simplify the testing of small pieces of Tcl within your browser.
An screenshot of the ADP Reveal:
The Tracing Script view, information shown at the bottom of each server page:
OpenACS also provides an implicit mechanism to document any script or procedure that
you might create, and then display and search that scripts or procedures, its documented
information, expected inputs and outputs, and its code though a Web interface at your
own OpenACS installation, like yourserver.com/api-doc, have a look here:
http://openacs.org/api-doc/
Finally, using the package manager, the Web server can be instructed to reload Tcl
library files without a restart of the webserver, and keep watching them for subsequent
changes, which is quite useful for the developers.
3.5. Testing Framework
OpenACS provides a full featured testing framework to create, maintain and run
automated test in your applications. The main characteristics of it are:
- Define tests, as smoke, config, database, web, etc. in a per package basis. And
with the API provided by the test framework you have a UI to check results, and
log events when executing a test case.
- Test your application at the proc level, using specific Test API to define and
check if your procs are behaving as expected.
- Test your end-user web scripts using a third party tool, such as tclwebtest or
perl::mechanize, to test the end-user pages automatically simulating end user
navigation (clicks) through the application and finally check the outpus using the
Test API.
- Define procedures that many tests might call, in order to automate similar
activities that need to be done before running a test case.
- Rollback the generated data after executing a test case.
- Rollback code section, to perform actions that will rollback the actions done by
running a test case, specially designed for those situations where you cannot
encapsulate the database calls to rollback, like when you are calling the scripts
with an automated tool.
- Run tests by installation, package or by choosing an specific test case.
3.6. Internationalization
OpenACS provide a facility to internationalize its user interface texts (not the data stored)
to any desired language, right now OpenACS is translated to more than 20 languages.
The end users can change the language user interface by simply selecting it. Each
OpenACS package can be internationalized separately, maintaining a message keys
catalog, which consist in a specific XML DTD where each possible user interface
message is stored as a message key, and then translated to a given language. Although all
the data is stored in the xml file, everything is also stored in the database, for
performance reasons and to facilitate the edition of the message keys OpenACS provides
a simple UI for translation of message key. And exists an official translation server for
the community at: translate.openacs.org.
3.7. Callbacks
The callbacks are a simple method to execute procedures stored in each of the possible
installed packages that a given OpenACS installation might have. The objective is to give
the core applications to invoke in non-core packages that may or may not be installed, but
without cluttering core with code that belongs to other packages, making possible to have
independence among packages.
The architecture work as
-> Core proc for removing user
-> Invoke callbacks based on what's installed
-> Package A logic for removing user
-> Package B logic for removing user
-> Package C logic for removing user
...
-> Core logic for removing user
as opposed to this architecture
-> Package A proc for removing user
-> Package A logic for removing user
-> Call core proc for removing user
-> Package B proc for removing user
-> Package B logic for removing user
-> Call core proc for removing user
Callback implementations would be declared like this:
ad_proc -callback module::op -implementation implname { ... }
Where ad_proc is a wrapper of the normal TCL proc, which mainly gives autodocumentation
structure for any procedure.
Core uses tcl introspection to find which callbacks exist and invokes them. eg
foreach proc [info procs ::callback::module::op::impl::*] {
$proc $args
}
To invoke a callback you do this
callback [ -catch ] [ -impl impl ] callback [ args... ]
The callbacks is a great improvement in order to keep simple yet separated, coherent and
modular a web framework that constantly evolves and grows. The larger goal is to
promote reuse of standard pages and functions by removing the need to create perpackage
versions of these.
Created by Anett Szabo, last modified by Anett Szabo 30 Jul 2007, at 01:40 PM
4.1. Content Repository
The Content Repository (CR) is a central service application that can be used by other
applications to manage its content. The developer must define and declare the
interactions with the content repository. The main features that the content repository are:
- CR is capable to store any kind of information (files, data, text).
- Define application specific data structures that will use the CR features and
services within the application context.
- Revision control, which means that every addition and subsequent changes of an
application is registered, so the versions are kept and can be roll-backed.
- Ability to handle hierarchies, and folder structures, and inherit its properties.
- Easily interact with the CR and its specific defined structures through a welldefined
API, in order to add data or present it.
- Also handles publish states for content that might need it.
- Identify content through a content type definition.
- Associate the content with external applications.
- Store specific templates to use when displaying specific content types.
- Create relations between content repository items or external database objects.
- Embedded search facility to automatically expose the content to the search engine
the system might be using.
The process for an application to use the content repository goes as:
1. Define the database structure your application needs that will use some of the CR
features.
2. Use the standardized API (to add, edit, delete, present) to create scripts for your
CR-enabled-application.
The CR logic is stored in database functions and triggers, but it has a Tcl API that glue all
the involved database calls and makes straightforward for the developers to create
applications that use the CR.
4.2. Results: Vertical Applications
Within OpenACS a vertical application means a set packages that interact together to
provide a specific domain set of functionalities.
The following are good examples of vertical applications completely running in
OpenACS and using Tcl as the programming language:
4.2.1. Project Manager
Full featured Project manager, consist in a set of functionalities that can be summarized
as: track tasks, estimates and actual progress for a project. It consist in more that 5
packages. Features that are part f it: project creation, customers management, task
assignments, logs, comments, create processes, rates, etc.
4.2.2. Assessment Tool
Extremely powerful application to create several types of assessments such as online selftests,
surveys, tests and gathering of information in general. The main features of this
application are: IMS-QTI support for import and export of assessments, branching,
sections, several types of questions and many more are part of it. More information at:
http://cvs.openacs.org/cvs/*checkout*/openacs-
4/packages/assessment/www/doc/index.html?rev=1.6
4.2.3. Communities of Practice
Communities of Practice within OpenACS are represented by a set of tools available
through all the website to interact with any kind of applications. The main objective is to
give the power to the end user describe in many forms any object at the system and make
relations among them. Those tools are:
- Rate
- Comment
- Categorize
- Link
- Search
And those tools can be used in all the applications that the end user might have available,
such as forums, file storage, etc. For example, you can categorize a given file, and then
link it to a forum thread, which you are also rating and commenting. Then a third user
will search for given topic, and the first result will be the file, and when he looks at the
file, he’ll see as well all its related objects, such as the forum thread.
4.2.4. .LRN and the E-LANE project
.LRN (pronounced dot-learn, www.dotlrn.org) is a full featured LMS with extra
community building capabilities, uses packages available for OpenACS and integrate
other vertical applications described here. Its focus is to help the creation of learning and
research communities, and not just server as an LMS.
The E-LANE Project (European-Latin America New Education, www.e-lane.org) is
using .LRN as its foundation technology to promote and demonstrate e-learning within
this geographical area, the demonstration is based on three fundamental factors: the
learning methodology, the content development, and the technological platform, the three
of them brought together to use it in real scenarios for further improvement of .LRN.
As a contribution to the .LRN community, E-LANE has developed among other
applications the user-tracking package, which is mainly focused to “Analyze users
behavior and syndicate it by object type”.
This package is basically using Tcl to create the UI and the administrative actions, and
glue them with awstats (http://awstats.sourceforge.net/), which in this case is the log
analyzer used to parse the AOLserver request logs, and those logs contains a set of
special keys written on each http request logged, which is the base to generate specific
request reports for a given user and/or object type.
Created by Anett Szabo, last modified by Anett Szabo 30 Jul 2007, at 01:08 PM
The Open Architecture Community System (OpenACS) is a Web development
framework for building applications that support online communities.
OpenACS provides a robust infrastructure, building on top of the following standard
components: the Tcl programming language, a Postgres or Oracle database for storing the
application data, AOLserver for HTTP service and *nix or Windows operating systems.
Like other modern Web frameworks, OpenACS supports: templating for separating the
logic from the presentation, internationalization to present the user interface in the user’s
preferred language, a modular package system to create sub-applications, a role and
permissioning system, a content repository to store all manner of content and maintain
versioning.
