ࡱ > : y } @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x I bjbj 4 8 ? , *1 *1 m>
w> A A A $ E E E I cL 4 E 2 N
Z Z Z Z # ֢ b 2 2 2 2 2 2 2 6 89 2 A * { L * * 2 > > Z Z 2 * > t Z ( A Z 2 * 2 M% t @ * Z - E ( ^ {2 2 0 2 ) J: X J: * * J: A + * * * * * * * 2 2 * * * 2 * * * * J: * * * * * * * * * *1 3= :
Getting Started with OpenACS: your quick guide to a powerful framework.
Contents
TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc229650957"Getting Started with OpenACS: your quick guide to a powerful framework. PAGEREF _Toc229650957 \h 2
HYPERLINK \l "_Toc229650958"How this Tutorial is Organized PAGEREF _Toc229650958 \h 5
HYPERLINK \l "_Toc229650959"Day 1 PAGEREF _Toc229650959 \h 6
HYPERLINK \l "_Toc229650960"Objectives PAGEREF _Toc229650960 \h 6
HYPERLINK \l "_Toc229650961"Section 1 PAGEREF _Toc229650961 \h 6
HYPERLINK \l "_Toc229650962"On this Section You Will Learn PAGEREF _Toc229650962 \h 6
HYPERLINK \l "_Toc229650963"Installation PAGEREF _Toc229650963 \h 6
HYPERLINK \l "_Toc229650964"Linux: Installing on a Ubuntu system PAGEREF _Toc229650964 \h 6
HYPERLINK \l "_Toc229650965"Windows Installer PAGEREF _Toc229650965 \h 7
HYPERLINK \l "_Toc229650966"Basic Tcl PAGEREF _Toc229650966 \h 7
HYPERLINK \l "_Toc229650967"What is Tcl? PAGEREF _Toc229650967 \h 7
HYPERLINK \l "_Toc229650968"Why Tcl? PAGEREF _Toc229650968 \h 8
HYPERLINK \l "_Toc229650969"Example and Resources PAGEREF _Toc229650969 \h 8
HYPERLINK \l "_Toc229650970"My First Page PAGEREF _Toc229650970 \h 8
HYPERLINK \l "_Toc229650971"My First ADP PAGEREF _Toc229650971 \h 8
HYPERLINK \l "_Toc229650972"Examples PAGEREF _Toc229650972 \h 8
HYPERLINK \l "_Toc229650973"Passing Variables between pages PAGEREF _Toc229650973 \h 11
HYPERLINK \l "_Toc229650974"Day 2 PAGEREF _Toc229650974 \h 13
HYPERLINK \l "_Toc229650975"Objectives: PAGEREF _Toc229650975 \h 13
HYPERLINK \l "_Toc229650976"Section 2 PAGEREF _Toc229650976 \h 13
HYPERLINK \l "_Toc229650977"On this Section You Will Learn PAGEREF _Toc229650977 \h 13
HYPERLINK \l "_Toc229650978"My First Package PAGEREF _Toc229650978 \h 13
HYPERLINK \l "_Toc229650979"The To Do Application PAGEREF _Toc229650979 \h 13
HYPERLINK \l "_Toc229650980"Creating a New Package PAGEREF _Toc229650980 \h 14
HYPERLINK \l "_Toc229650981"Mounting our new package PAGEREF _Toc229650981 \h 16
HYPERLINK \l "_Toc229650982"Section 3 PAGEREF _Toc229650982 \h 18
HYPERLINK \l "_Toc229650983"On this Section You Will Learn PAGEREF _Toc229650983 \h 18
HYPERLINK \l "_Toc229650984"To Do Data model PAGEREF _Toc229650984 \h 18
HYPERLINK \l "_Toc229650985"Adding some test Entries PAGEREF _Toc229650985 \h 19
HYPERLINK \l "_Toc229650986"Day 3 PAGEREF _Toc229650986 \h 20
HYPERLINK \l "_Toc229650987"Objectives PAGEREF _Toc229650987 \h 20
HYPERLINK \l "_Toc229650988"Section 4 PAGEREF _Toc229650988 \h 20
HYPERLINK \l "_Toc229650989"On this Section You Will Learn PAGEREF _Toc229650989 \h 20
HYPERLINK \l "_Toc229650990"Creating user accessible pages PAGEREF _Toc229650990 \h 20
HYPERLINK \l "_Toc229650991"Deleting Items PAGEREF _Toc229650991 \h 40
HYPERLINK \l "_Toc229650992"Updating the Status PAGEREF _Toc229650992 \h 41
HYPERLINK \l "_Toc229650993"Section 5 PAGEREF _Toc229650993 \h 42
HYPERLINK \l "_Toc229650994"On This Section You Will Learn PAGEREF _Toc229650994 \h 42
HYPERLINK \l "_Toc229650995"Adding a Tcl API to our package PAGEREF _Toc229650995 \h 42
HYPERLINK \l "_Toc229650996"Day 4 PAGEREF _Toc229650996 \h 45
HYPERLINK \l "_Toc229650997"Objectives: PAGEREF _Toc229650997 \h 45
HYPERLINK \l "_Toc229650998"Section 6 PAGEREF _Toc229650998 \h 45
HYPERLINK \l "_Toc229650999"On This Section You Wil Learn PAGEREF _Toc229650999 \h 45
HYPERLINK \l "_Toc229651000"ACS Objects PAGEREF _Toc229651000 \h 45
HYPERLINK \l "_Toc229651001"How tu use objects? PAGEREF _Toc229651001 \h 45
HYPERLINK \l "_Toc229651002"Using Objects PAGEREF _Toc229651002 \h 46
HYPERLINK \l "_Toc229651003"Changes to the packages Pages PAGEREF _Toc229651003 \h 50
HYPERLINK \l "_Toc229651004"Section 7 PAGEREF _Toc229651004 \h 59
HYPERLINK \l "_Toc229651005"On This Section You Wil Learn PAGEREF _Toc229651005 \h 59
HYPERLINK \l "_Toc229651006"Integrating with other services PAGEREF _Toc229651006 \h 59
HYPERLINK \l "_Toc229651007"Permissions PAGEREF _Toc229651007 \h 63
HYPERLINK \l "_Toc229651008"Finishing the transition PAGEREF _Toc229651008 \h 64
HYPERLINK \l "_Toc229651009"Conclusions PAGEREF _Toc229651009 \h 66
HYPERLINK \l "_Toc229651010"Appendix A PAGEREF _Toc229651010 \h 67
HYPERLINK \l "_Toc229651011"OpenACS on Windows PAGEREF _Toc229651011 \h 67
HYPERLINK \l "_Toc229651012"APPENDIX B PAGEREF _Toc229651012 \h 68
HYPERLINK \l "_Toc229651013"Connecting to postgresQL on Windows and Ubuntu PAGEREF _Toc229651013 \h 68
How this Tutorial is Organized:
The tutorial is divided in 4 days (actually 3.5 days! although is known that many people finish it sooner). Each day has two sections, in total there are 7 sections, each section will guide you through a set of activities that will keep you learning OpenACS powerful software development features.
This tutorial was written with an OpenACS system running on an Ubuntu system as reference, so the examples, default directories, screenshots, etc are aimed at an Ubuntu installation, but this do not limit the reach of this tutorial to just Linux at the end of the tutorial you'll find a table with the important directories listed both on Ubuntu and Windows, this can help you if you are using Windows as your base system.
On each section you will find different elements, a typical section will consist of:
The day number we expect the section to be accomplished.
What you will learn on this section.
Little notes about related topics.
Files we will be working on.
And the Try It! icon.Sometimes after describing an example your will find a: Try It! icon, SHAPE \* MERGEFORMAT , this means to go ahead and try what we just did, we will usually give a url to try, this URL will be the one of the reference system, something like: HYPERLINK "http://localhost:8000/helloworld"http://localhost:8000/helloworld if no url is present then try again the last page we have been working on.
Day 1
Objectives:
On this first day we want to get you up and running with an OpenACS system and have you to test how to create your very first web pages using OpenACS.
Section 1
On this Section You Will Learn:
How to set up your own OpenACS test site
What is Tcl and where to learn it
How to create basic web pages with OpenACS
Installation
Linux: Installing on a Ubuntu system:
You can get the whole system up and running in just a few minutes with it.Follow these steps to install in Ubuntu, the installer is designed to work with Ubuntu 8.04 (Hardy Heron) but it can easily work on newer releases with slight adjustments.
Follow these steps for Ubuntu 8.04 and Ubuntu 8.10:
SHAPE \* MERGEFORMAT
Follow these steps for Ubuntu 9.04:
SHAPE \* MERGEFORMAT
You can find the most up to date instructions on the installer's Wiki Page:
HYPERLINK "http://openacs.org/xowiki/ubuntu"http://openacs.org/xowiki/ubuntu
After you do this, please go to: HYPERLINK "http://localhost:8000"http://localhost:8000 and fill out the form that will be on that page, this starts the installation process of the actual service you will be using, it basically populates the database and sets everything up. After you do this, you will need to restart your openacs service, do it this way:
sudo /etc/init.d/openacs restart
Your normal Ubuntu user probably will not have write permission on the openacs directories, to correct this execute the next commands:
sudo usermod -a -G www-data ubuntuuser
sudo chmod -R 775 /usr/share/openacs/www
Windows Installer:
You can download an all in one installer for Windows (XP and Vista 32 bits), this installer gets you set up with everything you need.
For detailed installation instructions please go to HYPERLINK "http://www.friendlybits.com/en/inf_tec_en/win32openacs_en/"http://www.friendlybits.com/en/inf_tec_en/win32openacs_en/
If you are going to use the windows installer please keep this in mind:
It is going to install you 2 services, please use the one named OpenACS
Before you start the service, start the database server.
On Windows Vista you will need to start and stop the database server and the openacs service
with administrator privileges.
Basic Tcl
What is Tcl?:
Originally from "Tool Command Language", Tcl is a highly flexible and easy to use programming language, it is the language we will be using to work with OpenACS, so if you do not know it, now it is a great time to try and learn a little bit about it.
Why Tcl?:
The OpenACS toolkit is intended to be used with the AOLServer HTTP server, Tcl is AOLServer's built in scripting language so it is natural to write the applications using Tcl.
Example and Resources:
A highly recommended Tcl reference book HYPERLINK "http://philip.greenspun.com/tcl/"http://philip.greenspun.com/tcl/, it is free and easy to follow, you will learn Tcl in just a few minutes with it, keep it close while developing on OpenACS.
My First Page
My First ADP:
ADP stands for AOLServer Dynamic Pages, they are pretty similar to a plain HTML page, but they include a few more tags and extensions to able to handle dynamic information coming from the Tcl page.The process of creating a user viewable dynamic page on OpenACS is actually divided on at least 2 files a Tcl file and one ADP file, so for a page called "foo" you will have foo.tcl and foo.adp
The adp page is just an HTML page with the necessary markup to display dynamic data.
The Tcl page handles permissions, logic, calculations and provides the data to the ADP page.
The naming on these pages is really important, remember that tcl is a case sensitive language.
There is a third kind of page that could be involved, this third kind defines the database queries to be used, we will not be using them on this tutorial.
Examples:
On the most basic level you can set a variable on the Tcl file and retrieve it on the ADP, this variable becomes a datasource for the ADP page. Open up your favorite editor, we recommend Notepad++ (HYPERLINK "http://notepad-plus.sourceforge.net/uk/site.htm"http://notepad-plus.sourceforge.net/uk/site.htm) on Windows and Kate (found under the K Menu on KDE) or GEdit (found on the applications menu on Gnome) on a Linux system, and follow these next examples.
Hello World:
helloworld.tcl:
set hello "Hello World!"
helloworld.adp
Hey, @hello@
These simple two lines will generate your first page on OpenACS, you can create both files under the /usr/share/openacs/wwwdirectory on your test site. And when you go to HYPERLINK "http://localhost:8000/helloworld"http://localhost:8000/helloworld (notice we are not using any file extension) you will see something like this:
View of the page we just created.
SHAPE \* MERGEFORMAT HYPERLINK "http://localhost:8000/helloworld"http://localhost:8000/helloworld
Connection Information:
On this example we will retrieve some basic connection information using the HYPERLINK "http://www.openacs.net/api-doc/proc-view?proc=ad_conn"ad_conn procedure and will display it using a simple unordered list.
connection.tcl
set user_id [ad_conn user_id]set url [ad_conn url]set session_id [ad_conn session_id]set IP [ad_conn peeraddr]
connection.adp
Basic Connection Information:
User Id: @user_id@
This URL: @url@
This session: @session_id@
IP Address: @IP@
Go to HYPERLINK "http://localhost:8000/connection"http://localhost:8000/connection and you will get something like this:
SHAPE \* MERGEFORMAT HYPERLINK "http://localhost:8000/connection"http://localhost:8000/connection
If you notice, right now our last couple of pages do not look quite attractive and there is no title on the pages, they are very simple pages and there is a really easy way to improve their look by adding a couple of lines to the adp page. Lets improve our last example by using the HYPERLINK "http://openacs.org/forums/message-view?message_id=1156517"master tag at the start of the adp page.
Better looking connection.adp:
Basic Connection Information
Basic Connection Information:
User Id: @user_id@
This URL: @url@
This session: @session_id@
IP Address: @IP@
You should see your page with the site template, the tag tells OpenACS to include a header, footer, CSS and few more things to your page, using this you can build sites with a unified look and feel. The property tag can set different page attributes, in this case the title of the page.
SHAPE \* MERGEFORMAT HYPERLINK "http://localhost:8000/connection"http://localhost:8000/connectionOn your test site the page should look something like this:
The look may change from system to system depending on the sites template, but a basic install should look like the image.
Passing Variables between pages:
To ensure the presence of the required information for the Tcl page OpenACS uses a simple and powerful contract system between the Tcl page and the ADP; this is established by the ad_page_contract procedure in the Tcl page. We will build a pretty simple page to illustrate this.The example will present a simple form for the user to fill out on one page and another to display the information. We will ask for a name and an age and display it on the other page, the name, the age and if the person is an adult.
nameage.tcl
nothing here
nameage.adp
display-name-age.tcl
ad_page_contract {This page will display the name and age entered on the nameage page.And this page is role is pretty much just to accept and validate the data before displaying it.} {age:integername}
display-name-age.adp
Page for @name@
Name: @name@
Age: @age@
@name@ is an adult.@name@ is still a minor. SHAPE \* MERGEFORMAT HYPERLINK "http://localhost:8000/nameage"http://localhost:8000/nameage
Day 2
Objectives:
Now that you know how to create pages, we want to learn on this day how to create a new package and how to work it inside the system.
Section 2
On this Section You Will Learn:
How to create your own package
How to configure a package
What is the basic structure of a package
How to mount your package
What application we will create on this tutorial
My First Package
Even when using single pages and folders you can accomplish some neat stuff using OpenACS, the real power of the toolkit lies with its packages system. To illustrate this we are going to build a simple package, a "To Do" List application and we will integrate it as a new OpenACS package.
The To Do list Application:
The requirements for our to do list application are pretty simple, we want to build a basic "To Do" List with the following features:
To let the users keep a list of items they need to accomplish before a given date.
The users must be able to see and modify only their own items.
The information we need to have on each item is:
Title
The description of the task
The due date
The item's current status
We need to give the users an interface to:
View their list of tasks.
Enter a new item to the list.
Edit/Delete an item.
Creating a New Package:
At a very basic level an OpenACS package is just a directory under the "packages"directory, you can probably find it on /usr/share/openacs/packages, with the necessary files (Tcl/adp files) and a file with metadata about the package, but you do not need to write it all yourself, the proper way to create the package is by going in to the "Package Manager" and selecting the option to create a new package.Go to your site administration: HYPERLINK "http://localhost:8000/acs-admin/"http://localhost:8000/acs-admin/
Then follow the link "Developer's Admin" and click on "Package Manager (HYPERLINK "http://localhost:8000/acs-admin/apm"http://localhost:8000/acs-admin/apm ), you should see a page listing all the packages installed on your system:Scroll all the way down and you will find the link to "Create a new package"
After following that link you will be presented with a page to enter the new package information, fill out the form with this information:
Package KeytodoPackage NameTo Do ListPackage PluralTo Do ListsPackage TypeApplicationOpenACS CoreLeave it uncheckedSingletonLeave it uncheckedAuto-Mount URILeave it blankPackage URLLeave the defaultInitial Version0.1dVersion URLLeave the defaultSummaryA little application to keep track of items on a "To do list" DescriptionA little application to keep track of items on a "To do list" Primary OwnerLeave the defaultPrimary Owner URLLeave the defaultSecondary Ownernot necessarySecondary Owner URLnot necessaryVendornot necessaryVendor URLnot necessary
Make sure to leave checked the "Write a package specification file for this package" check box.Now after you click the "Create Package" button, the package will be created and installed on your system.We can check that the package was created by going to the "packages" directory under your OpenACS installation, /usr/share/openacs/packages, and looking for a directory named "todo".It should be: /usr/share/openacs/packages/todoInside of it you will find the file todo.info and the following file structure:
Each file and directory has its own special purpose:
todo.info:
This is the package specification file, inside of this file is the information that makes this directory a package inside of OpenACS, the package name, parameters, dependencies, etc are defined here, usually you do not need to edit this file directly because it is generated by the Package Manager when there is a change on it.
sql:
This directory holds the data model for the package, the initial definition and changes to the data model are defined here. There are two subdirectories here, oracle and postgresql, this is to allow the definition of database specific code, we will be using the postgresql directory only on this tutorial.
tcl:
The Tcl directory holds the library files containing the definition of procedures related to your package.
www:
This are the public pages of your package, here you will define the pages that the user will interact with, a special service of OpenACS called the request processor maps each request done to an instance of your package to this pages, so you can have your package mounted at different URLs all working with the same code.You will find this same basic structure on every OpenACS package.
Mounting our new package:
Now that our package is created we will mount an instance of it on our "Site Map". Mount means that the pages at its www directory can be accessed by the user.Head to the administration page, HYPERLINK "http://localhost:8000/acs-admin/"http://localhost:8000/acs-admin/, under "Subsite Administration" go to your "Main Site", HYPERLINK "http://localhost:8000/admin/"http://localhost:8000/admin/ once there look under the "Advanced Features" section for the "Site Map" option. Usually the URL for this page would be something like: HYPERLINK "http://localhost:8000/admin/site-map/"http://localhost:8000/admin/site-map/
On this page you are able to see the different "site nodes" that exists on your site, packages, subsites, it is all here. Scroll to the bottom and look for a little form that will let you mount your package, you can even give it any name you want at the moment of mounting, but we will leave it blank this time.
After clicking "Mount Package" the new instance of your package will appear on the site map list, you can even browse to it! but, it does not have any content yet.
You can create a simple "index.adp" or "index.html" file under the www directory of your package to test that it is working.
Section 3
On this Section You Will Learn:
How to define a data model in OpenACS
How to make an sql file execute on package installation
What does our To Do data model contains
To Do Data model:
We will need to create at least one new table on the data base to store the information of our To Do list.We need to store:
The title of our task.
A description.
A due date.
The state of our to do list (pending, completed, canceled).
Who is the owner/creator of the to do list.
When we created it.
When we modified/updated it.
To what package instance it belongs to.
Run the next create table statement on your data base to create the "todo_item" table:
create table todo_item ( item_id integer, title varchar(200), description text, status char(1), owner_id integer, due_date date default now(), creation_date date default now(), constraint to_do_list_pk primary key (item_id), constraint to_do_owner_fk foreign key (owner_id) references users );
Then save it to: "/usr/share/openacs/packages/todo/sql/postgresql/todo-create.sql"
By saving it with that name you make sure that if you ever install the "todo" package in any OpenACS system, it will create the todo_item table during the installation process; right now we will not use this file again, but will come in handy if you need to install the package again on another system.
If you need help running the script, you can check the Appendix B at the end of this tutorial. You can also specify a file with instructions to be executed when uninstalling the package, you save this to:"/usr/share/openacs/packages/todo/sql/postgresql/todo-drop.sql" for now a simple drop table statement will work.
drop table todo_item;
Adding some test Entries:
Lets test our table by adding a few items directly on the data base.You will need to know your user id, to find this out go to the Users administration page: http://localhost:8000/acs-admin/users/ and look for your user details page, there you will a find your user's id.Then run this commands on the data base prompt:
insert into todo_item values(acs_object_id_seq.nextval, 'My first item', 'My first item description', 'p', 568);insert into todo_item values(acs_object_id_seq.nextval, 'My second item', 'My second item description', 'p', 568);insert into todo_item values(acs_object_id_seq.nextval, 'Another item', ' item description', 'p', 568);
SHAPE \* MERGEFORMAT On psql run both the create table statement and the test values. See appendix B on how to connect.
Day 3
Objectives:
On your third with OpenACS we want you to be able to finish up the package we started yesterday, have all the user interface set up and be able to use your "To Do" list application.
Section 4
On this Section You Will Learn:
How to create web forms with OpenACS
How to use ad_form for:
Entering new data
Editing an existing entry
Displaying one entry's information
How to create reports with OpenACS
How to use the List Builder for:
Displaying information as a list
Add sorting to a list
Add actions to a list
Creating user accessible pages:
Our next step will be to create the user interface of our package; we need to create the web pages that the user will be interacting with. Please remember to save all of this pages you want the user to be able to access and the www directory of your package, this is very important for the package to work properly.
Add and Edit item page:
We will create our page to add an item, we will do it in a way that we can reuse the same page to edit the item.You can do a simple HTML form and handle the user inputs yourself, but there is no fun in that. We will do it the OpenACS way, by using the built in procedure ad_form that allows you to specify the form fields, the actions to be executed on different states of the form, input validation, etc. You can read all about ad_form here: HYPERLINK "http://www.openacs.org/api-doc/proc-view?proc=ad_form" \n _blankad_form on the OpenACS APILets do the ADP first, you will see the page is really simple:
todo-ae.adp
@page_title@
todo-ae.tcl
Lets begin with the ad_page_contract for this page and declaring a few variables that we will use later.
ad_page_contract {This page allows the users to add new items to their to do list or edit existing items.} {item_id:optional}
set page_title "Add/Edit Todo Item"set user_id [ad_conn user_id]
If you notice we have declared item_id as optional parameter on this page, this allows to easily know if we are on edit mode or adding new information, if item_id is present then we are editing an existing item, if not, we are adding a new one, ad_form is smart enough to know this. We have used ad_conn to get information about the current user.
Form Widgets:
Lets continue by building our forms widgets, take a look at the next code snippet:
ad_form -name todo_item_form -export { user_id } -form { item_id:key {title:text {label "Task Title"} } {description:text(textarea) {label "Description"}}{due_date:date(date) {label "Due Date: "} {format {MONTH DD YYYY} } } {status:text(select) {label "Status"} {options { {"Pending" "p"} {"Complete" "c"} {"Canceled" "x" } } } }}
On the first line we are starting to use ad_form, the "name" parameter gives a name to our form, this way we can reference it on the ADP or later on the same Tcl file. We also "exported" some variables to the ad_form, this takes the variables from our Tcl file and includes them in the form as hidden fields.
ad_form -name todo_item_form -export {user_id } -form {
After the "-form" switch we can start defining our form's widgets, we start with the "key" widget, this is usually a unique identifier for the item we are adding or editing.
item_id:key
Next we have a simple text field.
{title:text {label "Task Title"} }
Our Next line defines a "text area" widget for our task's description.
description:text(textarea) {label "Description"}}
The next one is a date widget, what this actually does is to insert 2 "selects" and one text field so the user can select the month and day and input a year, this saves you the trouble of handling 3 different widgets for just one piece of information. We specify also the format we wish to use with the date.
{due_date:date(date) {label "Due Date: "} {format {MONTH DD YYYY} } }
Our last widget is a "select" widget, this one contains an "options" list with all the possible values and labels this select will present to the user, each option is a list of two elements {