Webinar - Part 1 - Basics

OpenACS Basics - Part 1

On 2006-10-15 Tracy Adams gave a webinar for developers on OpenACS basics. Here are notes, that might be of use for people who are starting to learn the toolkit. For example for easy copy-n-paste during learning sessions.

We assume the reader has a working instance of OpenACS at hand. If not, there are other sections of xowiki, that cover the installation and configuration of OACS.

Configuration for the turorial 

The default config puts the files of the toolkit to:

/var/lib/aolserver/service0

In this case, the dir of our interest for now, will be:

/var/lib/aolserver/service0/www

 We will edit all our tutorial files in that directory.

Hello, world! 

 OACS uses combination of Tcl and ADP pages for clear separation of logic and presentation. Tcl pages are just a Tcl scripts and ADP are HTML pages with some extra tags. However the early versions of the toolkit rendered pages within Tcl. We will use some of the earlier features of the toolkit.

Open a file "helo-1.tcl" in the path:

/var/lib/aolserver/service0/www

and put there:

# helo-1.tcl # return standard HTTP headers ReturnHeaders ns_write "hello, world!"

 now, open Your Firefox and go to:

http://yourhost/helo-1

or maybe with the port number: 

http://yourhost:8000/helo-1

instead of "yourhost" put the name or IP of the host of the edited instance of OACS. It also refers to all examples which follow.

Note the lack of .tcl extension at url. OACS has a Request Processor, that figures out the right extension and fetches the file.

ReturnHeaders - returns HTTP headers to the browser ns_write - just writes string to the browser

The docs for the entire system can be found at:

http://yourhost/doc

Note also very useful API browser and search boxes at:

http://yourhost/api-doc 

( maybe the URL will need also the port number, depending on Your config, for example:

http://yourhost:8000/api-doc 

)

Set a value

 To use a variable just put a value in it:

# helo-2.tcl
ReturnHeaders
# first, set the value for a
set a 10

# then use it
ns_write "value of a is $a"

The value of the var can also be a string:

# helo-3.tcl
ReturnHeaders
# first, set the value for a
set name "John"

# then use it
ns_write "My name is $name"

To get the value of the var:

# helo-4.tcl ReturnHeaders set a 10 # let's use the value of a for new var: set b $a ns_write "<br/> value of b is $b" # we can also do this like that: set c [set b] ns_write "<br/> value of c is $c"

The form [set varname] form of getting the value of the var seems at first a bit too long, but it comes in handy when doing some metadata manipulations.

Call a func

To evaluate the function ( or call a procedure ) use [ ] as follows:

# helo-4b.tcl ReturnHeaders set a 10 # let's use the value of a for new var: # expr is a func that returns the result of the math expression given # as the argument. using square braces we call this func set b [ expr $a + 5 ] ns_write "<br/> value of b is $b"

 Lists are simple

To create a list:

# helo-5.tcl
ReturnHeaders
set mylist [ list "red" "green" "blue" ] 
ns_write "<p> mylist is: $mylist"

( TODO: more on the lists - creation, adding, deleting, finding, etc...)

More complex structures: ns_set  

See the docs on ns_set: http://panoptic.com/wiki/aolserver/Ns_set.

 

 

# helo-6.tcl ReturnHeaders

# create a new set with a name "the_name_of_the_set": set vars_by_names [ ns_set create the_name_of_the_set ] # the name of the set is different that the name of the # variable, that contains that set # put some variables into the set: ns_set put $vars_by_names red   $red ns_set put $vars_by_names green $green ns_set put $vars_by_names blue  $blue # how many things do we have in the bag? set size [ ns_set size $vars_by_names ] ns_write "size of the set:  $size " # let's show them: ns_write "<br>red:   [ ns_set get $vars_by_names red   ]" ns_write "<br>green: [ ns_set get $vars_by_names green ]" ns_write "<br>blue:  [ ns_set get $vars_by_names blue  ]" # the same, but better: ns_write "<hr/>" set size [ ns_set size $vars_by_names ]

#     counter     condition      change the counter for { set i 0 } { $i < $size } { incr i } {     set key   [ns_set key   $vars_by_names $i]     set value [ns_set value $vars_by_names $i]     ns_write "<br/> $key: $value " }

Parameters for the page

It is very simple to control the way the parameters from query string go to our page:

#helo-7.tcl
ad_page_contract {
    demonstrates using of ad_page_contract
} {
    id:integer
}

ReturnHeaders
ns_write "id is: $id"

1. try to reach the page http://yourhost/helo-7 without the query string     the page should display the message about input problems

2. try the same with the url: http://yourhost/helo-7?id=123    the page should write the message: "id is 123"

3. try the same with the url: http://yourhost/helo-7?id=asdf    the page should display the message about id not being the integer

The parameter can be optional:

#helo-8.tcl ad_page_contract {     demonstrates using of ad_page_contract } {     id:integer,optional }

set id "<b>not necessary but optional</b>" ReturnHeaders ns_write "id is: $id"

Access control 

Using ad_conn, we can discover many useful info: 

# helo-9.tcl

# check if the user is logged in, redirect if not ad_maybe_redirect_for_registration ReturnHeaders # id of the user set user_id [ad_conn user_id] ns_write "user_id: $user_id" # peer's IP set user_ip [ad_conn peeraddr] ns_write "<p> user's IP: $user_ip"

Logic and Presentation

Now let's get to Tcl + ADP stuff which allows to separate the work of the designer from the work of the developer.

Most of the pages in OACS consist of at least Tcl and ADP components. Here is how:

In most cases Tcl and ADP pages are named the same, except for the extension. It is possible to explicitly call the presentation page from the script. See the docs for ad_return_template.

In the following example we will use helo-10.tcl and helo-10.adp.

in Tcl we do some data manipulation

# helo-10.tcl ad_page_contract {     demonstrates TCL and ADP combination     and multirow } {     id:integer,optional } -properties {     a:onevalue     alist:multirow }

set a 10 # create the multirow multirow create alist no name      color # add rows multirow append alist 1  Adam      red multirow append alist 2  Ben       blue multirow append alist 3  Catherine green multirow append alist 4  Danae     black

then we present it in ADP. Put the script below into helo-10.adp: ( note: remove the space between @ and the name of the variable below; I do not know how to escape the @ )

<master> <p>     the value of a is @ a@ </p> <blockquote>     <multiple name="alist">         <li> @ alist.no@ - @ alist.name@ ( color: @ alist.color@ )

</li>     </multiple> </blockquote>

 now open the page in browser:

http://yourhost:8000/helo-10

That's all.

The webinar took place on Sunday 2006-10-15 at 2:30 P.M. Eastern time.

Many thanks to Tracy Adams, who was presenting the material.  

( corrections welcome, especially of my english )