Introduction to OpenACS
Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 22 Mar 2019, at 11:04 PM
Start Playing With Openacs.
Before you know it, you will Become an Expert in the basics!
This is a quick guide of the things that you have to know in order to become productive in OpenACS. You have to master certain things before you can advance. A developer has to become an expert in handling and knowing the tools that he uses.
MAYBE, the very first thing to become aware of, is that your installed OpenACS server is self-documenting. Take a look at http://your.server/doc/ and spend some time here; I'd suggest an hour or so just to view the structure and get familiar with what is said where, and how it is said. WHENEVER you ask a question and get an answer, try to seek out the solution you get in the docs and piece it together. This WILL help you to gradually become an expert.
You have to become expert in:
- Emacs
- Tcl
- Linux (for OpenACS installation)
- Searching on OpenACS
- Functions that provides NaviServer
- Use of OpenACS
- Basic API OpenACS
Emacs:
You have to become expert in the text editor that you use for development since is a fundamental piece in your development environment. Not knowing the text editor in used makes it very limited and your work will be very unproductive.
Emacs is an extendable editor (but you can use any editor you want). Check out the oacs emacs module, pretty cool! en:ide-emacs
Minimal knowledge of Emacs:
- window management
- copy/paste
- DB access from emacs
- It's actually very simple, you run a shell in emacs and then run the text db client in the shell in emacs. Once inside emacs, <code>M-x shell (enter)</code> will put you in a shell. From there, you can do anything the shell can do, and then if you want you can save everything. So, oracle users can use sqlplus, postgres users can use psql. (watch out... by default emacs will NOT offer to save the buffer before you exit!)
- file management
- searching
Required time to know emacs ( 4 hours aprox).
PLEASE DON'T LET THAT SCARE YOU... you don't actually need to know EVERYTHING about emacs or be an expert in emacs itself. Me, I just know how to move the cursor, type, define a macro (no, really, this is easy too) and get into shell mode. Oh, and I can run (doctor) in the *scratch* buffer.
Tcl
Try searching google for "Tcl for Web Nerds" and/or look for some good, basic tutorials. I think you can learn at your own pace, and still have fun with OpenACS.
Minimal knowledge of Tcl:
- lists and manipulation functions
- strings
- proc/namespaces
- switch
- regular expressions (regexp)
- Everything that is basic to Tcl
(jiml) I'll suggest you find out how to run tclsh (or, say, psql) from inside emacs (see comment about emacs shell mode, above on this same page).
Required time to know and become used to Tcl (6-12 hours approx).
TCL for web nerds: https://openacs.org/test-doc/tcl-wn
Linux (for OpenACS Installation)
Minimal Knowledge
- user management
- group management
- permission
- compilation
- searching
- environment variables
Searching in OpenACS
Do your searching in OpenACS in different areas:
- forums (use google, example: site:opeancs.org postgres 8.1)
- code (use grep and find): find /path/name -name "*-oracle.xql" -exec grep whatever {} \; -print
- API doc (use to search procs)
Required Time (4 hours approx)
Debugging in OpenACS
This will help us to identify exactly what is producing an error. For that you have to learn::
- To read the log
- To use the Developer Support
To log everything in your log file, go to config.tcl and set "debug true.
Required Time (4 hours)
Functions of NaviServer
Check all of them ( ns_*)
HOWEVER NOTE that it is MUCH more important to see how these calls are used in OpenACS! (aside from which, it will take you less time to understand a single OpenACS interaction if you just look at one... the notes tutorial has a few; I would suggest that you do that tutorial and actually type everything in rather than cut and paste... then you touch every word)
NaviServer Documentation:
https://naviserver.sourceforge.io/n/toc.html
Required Time (4 hours aprox)
Use of OpenACS
Become expert in using OpenACS as a tool, from the user interface point of view.
Important items:
- Developer administration (Site-Wide-Admin) (4 hours)
- Applications: (4 hours or more)
- User administration:
- Understand the roles that exist.
- Will help a lot if you understand more about .LRN
- Basic API of OpenACS
- The -most- basic part of openacs is its object system.
Start to get familiar with the object system by reading
the definition which starts "create table acs_objects"
and find out everything you can about how to define your
own object types, how inheritance works, how to drop your types.
REMEMBER to drop things in -reverse- order from how you create.
Learn how acs_object inheritance works.
- Object and User and permission management
- DB (a detailed document describing the database access api is on your installed server at http://your.server/doc/db-api.html | a search for all tcl db procs: db_*)
- ad_conn (provides basic information regarding the browser the request is coming from as well as the user (if any logged in) who is doing the browsing; search at http://your.server/api-doc)
- Permissions: a permission is a statement of the following form:
PARTY (from table parties) whose party_id is X has
PRIVILEGE (from table acs_privileges) whose textual name is Y on
OBJECT (from table acs_objects) whose object_id is Z
You can:
- make such a statement (ex. group-of-my-students has "read" on my-student-forums)
- ask (in various ways) whether such a statement has been made
I would suggest for further study, that you:
- MOST IMPORTANT: try things out!!
- search google for "permissions tediously explained"
- also see the "notes" tutorial
- acs_rel is good tool for connecting objects. One application: groups of users (so one acs_rel "connects" one user to a common object, representing the group, ex: if andy, betty, carl, dirk and ed are in groups alpha-beta, there will be five acs_rels, all of them tied to alpha-beta on one side of the rel, and for rel, that rel will have one of the users on the other side of the rel)
- Site-map (instances and site nodes)
- another VERY important part of OpenACS that was not listed here before, is the templating system. If you have OpenACS installed, you can view the docs at http://your.server/doc/acs-templating/ and you can see dozens of demonstrations at http://your.server/doc/acs-templating/demo AAANNND if that's not enough, every demo has sample code and you can plug it right in to your page! As you can see, you can show values of Tcl variables, make lists and forms, include other templates and show database results and do all of this and more, looking any way you want.
