Introduction

When starting with OpenACS, you'll find a lot of things to think about--you may be learning a new languages, a new editor, a new operating system, a new conceptual framework, or some combination of these. This page is meant as advice to keep things in perspective.

Those before you are your friends

Those before you are your friends: you can ask questions in the OpenACS Q&A forum if you get into trouble, but make sure to search the forums first.

Do not forget that the users of OpenACS are your friends - while it is good to take some time to see if you can find what you need or figure something out, if you are stuck, ask. Sometimes it turns out that there's a better way, which you might never find by yourself and if they tell you something might not be worth doing, pay attention - they may not always be right, but they know the toolkit and the "OpenACS" way of doing things better than you do.

The OpenACS Education Page has more information on resources for getting help.

Emacs is your friend

You are by no means obligated to use emacs as your editor of choice. But it is a good choice for OpenACS.
  • It allows you to have multiple files open at once, so you can cut and paste between them, for example.
  • It allows you to run shells, so you can do things like run SQL*PLUS or psql from within Emacs. And, not only that, but you can use Emacs commands to edit SQL commands while you are running SQL*PLUS or psql. If you are using Oracle, this is especially welcome, since SQL*PLUS' own editing features are decidedly minimal.
  • It allows you to open several windows. This means you can have a shell window above that you've done this command in:
    tail -f logfile
    (where "logfile" should be replaced with the path to your aolserver error log or whatever). So, you can see errors. Also, when you see a SQL error, you can copy the code from the log file window and paste it into a SQL*PLUS or psql buffer and see what is wrong with it more exactly (or you can remove parts of the query and run more basic forms of it, continuing to add pieces until you find what is breaking it).
  • Emacs lets you search and replace nicely (Meta-x replace-string) --you can even use regular expressions
  • Emacs has macros, so, if you feel like taking the time, you could get it to spit out code fragments when you hit certain keys. Might speed you up some, if this fits in with your style.
  • Emacs lets you use a mode that colors different types of text differently so that you can see what you are working on and even see some typo bugs jump right out at you because they literally don't look right. Make sure you have a file in your home directory called .emacs (yes, there's a period as its first character) that has this in it (parentheses and all):
    (global-font-lock-mode 1)

The more you know of Emacs the better and it may stand you in good stead elsewhere. However, you really only need to know some 20 commands or so to use it effectively so rather than focussing on learning it all, learn those commands and get them into your fingers so that you don't have to think how to do stuff.

The Toolkit is Your Friend, Part I

Don't know how to do something? Chances are something like it has been done somewhere else in the toolkit. In fact, this is the meta-lesson of Problem Set 5 - learning to go looking in the toolkit for stuff you can re-use elsewhere.

To search for stuff in the toolkit, you have a few options:

  • Look at the API reference on OpenACS: http://openacs.org/api-doc/ or on your own local site at yoursite.com/api-doc.
  • You can also grep the source code to look at examples of how the API is used within the toolkit: 
    cd /var/lib/aolserver/service0/
grep -r searchterm *

    (replacing "searchterm" with whatever you are searching for, use double quotes for multi-word searches). If the results come by too fast, you can redirect them to a file: 

    grep -r searchterm * > filename

    Also, you can PIPE results into another grep or two if you need to filter things down: 

    grep -r searchterm1 * | grep searchterm2 | grep searchterm3

    The idea is that the first set of results get passed into the second grep and if need be you can keep doing this. You can of course, also use regular expressions in a grep search (you will need double quotes for these--check the "man" pages for grep--do "man grep" from a shell prompt.

    The Toolkit is Your Friend, Part II -- The Utility Procs

    Writing code in Tcl to do anything interesting is a pain, since Tcl is NOT your friend. Thankfully, there are a whole bunch of utility procs (i.e. procedures) that make your life very easy. Almost anything that's hard to do is available in the API. Want to see if there's a proc that lets you, say, get stuff out of the database in a certain way? Looking for procs that will allow you not to have to worry too much about CONNECT BY when doing the Family Tree stuff from Problem Set 5?

    Well, check this page out:

    http://openacs.org/api-doc/

    Click on Browse OpenACS Tcl API if you want to browse the API.

    First of all, you can scroll down to see the names of all the documented utility procs in the toolkit, grouped by file, meaning that they are often grouped by function. Want to see the parameters for the utility proc? Want to examine the source code for a utility proc? Just find it's name and click on the link.

    If you are looking for something in particular, you can either use your browser find capability (ALT-F or CTRL-F) or... you can use the search box provided - want to see a utility proc in use? If it is used in the "tcl" directory in some utility proc or other, you will find it (you can also use this search box to search for Tcl commands or anything in the "tcl" directory)

    Just ask yourself: is it likely that what you are trying to do might have been needed by the folks building the toolkit, like something to handle dates or list boxes or whatever? If the answer is yes, then figure that there is a good chance that there are some utilty procs that might fit the bill and take a look first before you start hacking new Tcl code. If you can't find one - or don't feel like going on a wild goose chase - ask (though if you look through the utility procs you may find useful utility procs that whoever you are asking doesn't know about).

    Remember: the toolkit is your friend - don't write code that has already been written for you.

    The database is your friend

    Both Oracle and Postgres are supported by OpenACS, and they both are very good databases.

    Yes, SQL and Oracle can be challenging to get to know. It can be frustrating to realize that you can do whatever you want to do in 3-10 lines of code, but that it'll take you a while to figure out what those few lines need to be. But once you do, you'll be able to do lots of the stuff you want to do using the database. Given how powerful an RDBMS like Oracle or PostgreSQL is, you can, and should, do as much as you can in the database. Be creative in coming up with queries that can get as much stuff out at once as you can, so you don't need to do multiple queries (use nested queries, joins, etc.) The database is fast and powerful compared to Tcl. Use that to your advantage.

    If you find you are doing something with every element that you get out of a query, ask yourself if you couldn't just rewrite your query so you get it all done in one query (If you get a result set out of the database and then find yourself looping through the results, querying the database for each row from the middle of the Tcl loop, you are almost by definition doing something wrong--it should be possible to do all the processing in one query).

    AOLserver is your friend

    Aside from all it's features and things, AOLserver can help you debug your code.

    First, there's the log. Let's say you want to see how things are going as a Tcl page gets executed. You can do something like this:

    ns_log Notice "Some message. The value for first_names is: $first_names"

    ns_log writes to the log file, the word Notice is necessary to specify just what type of thing is being written to the log file and then a message in double quotes follows and it will be inserted into the log file. Notice that you can put in variables. So you can see what the value of variables are.

    But wait, I hear you say, that means you have to wait for everything to go wrong and then check the log file. What if I just wanted to do "write statement debugging" so that I see the value of variables right in front of me without having to go switch windows to look at a log file?

    Well...you're in luck. You can use ns_return for debugging purposes - you add it into the middle of your code and move it around to find the problem (as opposed to the usual use of putting it at the end of your code to generate the page that you've been building).

    ns_return 200 text/html "The value of first_names is $first_names"

    The program will return a page whose contents will be the statement in double quotes assuming that the Tcl page gets executed to that point and you will see the message with the value there. You can just keep moving the ns_return statement down, (changing the variables if you need to) until you see that the ns_return statement isn't being executed.

    Note that ns_return should pretty much stop you cold once it executes--it returns the page with whatever you have in double-quotes and that is it--end of program.

    You can also use ns_write in a similar manner but have a bunch of them executing as the Tcl page gets run.

    All this strikes you as a primitive form of debugging? Well, so it is -- welcome to the web. As you become more familiar with OpenACS, you'll see that there are some more sophisticated methods of debugging, but it's best to start with the basics.

    Tcl is NOT your friend


    Do NOT try to do fancy stuff in Tcl and if you do, if it doesn't work quickly, you might want to DROP IT. Don't be stubborn with Tcl. It is not worth it, especially if you are just beginning to learn how to work with it. The language is fairly simple, and most of the power of OpenACS comes from the API, not the programming language.

    Look for ACS utility procs and AOLserver Tcl API calls that let you do things so you don't have to reinvent the wheel in Tcl. For example, ACS has a date widget so you don't necessarily have to reinvent your own. More about the utility procs above in the "The Toolkit is Your Friend, Part II -- The Utility Procs".

    Time is NOT your friend

    "If it were done when 'tis done, then 'twere well it were done quickly."
    -- Macbeth, Act I

    Not to put too much pressure on you, but we like to see people able to finish the problem sets in a reasonable amount of time. These problem sets originate from a course at MIT, which was latter offered to web nerds all over the world in the course of three weeks. So plan anywhere between three weeks and an academic semester. After all, on the web it is all about getting stuff running quickly for companies running on internet time. So...you probably won't get special treatment for some fancy idea that somehow didn't come together at the end. The idea is to write code that works and learn it while doing it.

    Not that it should look like junk or leave out checks for bad data or have bugs in it - take a look at the way other OpenACS modules are written (for better or worse).

    Sometimes good enough is good enough.

    Do NOT try to be a perfectionist - obviously after you work with the OpenACS for a while, you will be able to do better, but right now you don't have that experience so don't worry about it.

    Also, you may see other people who have done a better job than you and you may want to mimic some of what they've done. If you are ahead time-wise or if you can do it quickly, OK. But if you can't or if you start to run into trouble, think seriously about backing off. Some people may be more talented than you or simply more experienced than you. That doesn't mean that your stuff is bad, just that their's may be a bit better. But: your job is to make the thing work. If you get snagged on stuff that doesn't work and don't finish, that is much worse than having stuff that isn't as good as the next person.

    History of this Document