Search · Index

Popular tags

ad_form (1), ADP (1), ajax (1), aolserver (1), asynchronous (2), bgdelivery (3), bugtracker (1), COMET (1), cvs (4), debian (6), emacs (2), FreeBSD (1), includelets (2), install (2), installation (1), installers (1), javascript (2), libthread (3), linux (3), monitoring (1), nginx (1), oracle (1), osx (2), patches (1), performance (2), postgres (4), pound (1), redhat (1), selenium (1), ssl (1)

1 registered user in community xowiki
in last 30 minutes

Contributors

OpenACS.org

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 " value of b is $b"

# we can also do this like that:
set c [set b]
ns_write " 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 " value of b is $b"

Lists are simple

To create a list:

# helo-5.tcl
ReturnHeaders
set mylist [ list "red" "green" "blue" ]
ns_write " 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 " red: [ ns_set get $vars_by_names red ]"
ns_write " green: [ ns_set get $vars_by_names green ]"
ns_write " 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 " $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 "not necessary but optional"

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 " 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 componetns. Here is how:

In most cases TCL and ADP pages are named the same, exept 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>


 the value of a is @ a@


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

References to this Page: en:docs-dev-tutorial Categories: Tutorials for Programmers (OpenACS.org)