Filtered by category Tutorials, 1 - 6 of 6 Postings (
all,
summary)
Created by OpenACS community, last modified by Antonio Pisano 03 Nov 2023, at 11:55 AM
Tutorials for OpenACS development
Other related tutorials
See also: OpenACS Mentorship Program
Other useful resources
Web Sites
Books
Created by Gustaf Neumann, last modified by Paul Babin 14 Oct 2021, at 04:01 PM
OpenACS provides theming functionality, i.e. the customization of the site layout through so-called theme packages with customized CSS and HTML layout.
Each subsite in OpenACS can have its own theme.
By default, the "Openacs-Default-Theme" is activated when installing OpenACS. The "Openacs-Default-Theme" package contains a "tabbed" navigation theme and a "plain" navigation theme (without tabs in main navigation).
OpenACS comes now with a new theme package, the "Openacs-Bootstrap3-Theme" Package, which is based on the Twitter Bootstrap Library. This new package is used on the openacs.org site and available form the openacs repository. The package (and the description below) requires at least OpenACS 5.9.0. In the following section you find some hints on how to use and customize this theme and how the theming can be customized in newer versions of OpenACS.
Step-by-Step Installation of a Theme Package
Installing theme packages and switching between themes can be easily done in a few steps:
- Obtain the theme package (e.g. from CVS or github) and install it under the package directory. You can as well "install from the respository", which makes step 2 below unnecessary.
- Go to /acs-admin/install and install the package
- Navigate to the subsite whose theme you would like to change and go to the "Configure"-Page. If you only have the default subsite set up, this is located at /admin/configure. Choose the theme you want. Click Ok. You should see the new theme now.
Note that a theme package can contain a number of different themes. For instance, the "Openacs-Default-Theme" Package contains a "tabbed" and a "plain" theme; the "Openacs-Bootstrap3-Theme" Package contains a "tabbed" theme in OpenACS style and a "tabbed" theme in turquoise color.
- DONE!
Understanding the Basic Settings of Theme Packages
Where are the themes of a theme package defined?
Open /packages/openacs-bootstrap3-theme/tcl/apm-callback-procs.tcl in your editor. You see that 2 themes are defined here (subsite::new_subsite_theme), with all relevant parameters including css and js files and definition of template files.
You could add another subsite theme here. In order to get it listed on the "Configure"-Page of your subsite, you need to de-install and re-install the Theme Package.
The Theming Parameters allow you to specify, how elements of your page such as forms or lists should be rendered. If the resource which you have defned in your theme is not found, the default is taken from /packages/acs-templating/resources/ as a fallback.
The Theming Parameters
Have a look at the parameter page of your subsite. If you only have the default subsite set up, this is located at /shared/parameters.
In the "Theming"-Section of the subsite parameter page, you find the parameters which you have defined in the apm-callback-procs.tcl file of your theme package. You can modify the parameters here, however it is recommended that you define them in the apm-callback-procs. Why? If you switch the theme or re-install it, the settings of the parameter page are lost!
DefaultDimensionalStyle
- Defines layout of the filter options in a dimensional list. You can find an example at the Download Page of the OpenACS Website.
DefaultFormStyle
- Defines the layout of form templates
DefaultListStyle
- Defines the layout of list templates
DefaultMaster
- Defines the general page layout. The master usually sets the framing for the page layout and places elements such as header, navigation, content area, footer.
ResourceDir
- The directory, from which the resources of acs-templating are loaded. The resources include the template files for dimensionals, forms, lists, masters, templates, widgets. If not set, or the required resource is not found, the default is taken from /packages/acs-templating/resources/.
If for instance, the ResourceDir is set to /packages/openacs-bootstrap3-theme/resources, and you have a dimensional template defined in "Openacs-Bootstrap3-Theme" Package, you only need to specify the name of the -dimensional_template without giving the entire path.
StreamingHead
- Master used for streaming content
ThemeCSS
- List of CSS files used in the theme
ThemeJS
- List of Javascript files used in the theme
ThemeKey
Additional Tools to Layout in a Theme Package
Widgets
Starting with OpenACS 5.9, so-called widgets can be defined. <widget> is very similar to <include>, but uses widget specific name resolution based on themes. If the theme package contains resources/widgets/$specifiedName it is used from there. Otherwise it behaves exactly like <include> (without the resources/templates/theming).
In the "Openacs-Bootstrap3-Theme" Package, widgets are defined e.g. for the main navigation bar and the login area.
Templates
Sometimes, you might want a specific page or include to have a special design or layout which differs from the standard layout defined in that package. For instance, you might want to give the notification widget a new look&feel. You could go to the notification package and edit the correspondend tcl/adp files there. However, when upgrading the package, you always would have to merge your local changes with the upgraded files.
Starting with OpenACS 5.9, you can customize your local templates in your Theme Package. These files "overrule" the tcl/adp files in the corresponding packages. This makes it easier for you to keep the overview of all your layout changes, and also to upgrade your packages with less effort.
How does it work?
Let's take the example from above: you want to change the lokk&feel of the notification widget. The tcl/adp files are situated in /packages/notifications/lib/notification-widget.tcl and /packages/notifications/lib/notification-widget.adp.
Go to the "Openacs-Bootstrap3-Theme" Package. You see a folder resources/templates. Now construct a folder structure in the templates folder, just like this: resources/templates/notifications/lib and create the 2 files notification-widget.tcl/adp. Change the layout as desired.
DONE!
The "Openacs-Bootstrap3-Theme" Package contains a few such template files by default; feel free to change or complement them.
Understanding the Openacs-Bootstrap3-Theme Package
Different master files
The "Openacs-Bootstrap3-Theme" Package comes with a set of master files, which are shortly explained here.
- The "base master" is the plain-master.tcl/adp. It defines the general page layout.
- The tabbed-master.tcl/adp is the addition for a tabbed navigation, i.e. navigation tabs in the header bar which are defined in the parameter page. Tabs can be defined for admins (AdminNavbarTabsList), for members (MembersViewNavbarTabsList), for users (UserNavbarTabsList). You can check if you want the applications to be shown as tabs in the navigation bar.
- The tabbed-master-turquois.tcl/adp is similar tp the tabbed-master.tcl/adp. The difference is in the logo image defined in the .tcl file. In the OpenACS website, it is currently applied in the subsite for the .LRN project.
- The plain-streaming-head.tcl/adp, tabbed-streaming-head.tcl/adp, and tabbed-streaming-head-turquois.tcl/adp files are the corresponding master files for streaming content.
Color css
"Openacs-Bootstrap3-Theme" Package contains a "tabbed" theme in OpenACS style and a "tabbed" theme in turquoise color. The color stylesheets are defined in the apm-callback-procs.tcl file and located at /packages/openacs-bootstrap3-theme/www/resources/css/color/. This makes it very easy to change the color design of the theme. You could either modify one of the color stylesheets "blue.css" or "turquois.css"; or you could add your own color stylesheet and link it in the apm-callback-procs.tcl-file. In the latter case, you should de-activate and re-activate the theme in the "Configure"-Page (see above) to activate the setting.
Twitter Bootstrap
As the name of the package suggests, the "Openacs-Bootstrap3-Theme" Package makes use of the Twitter Bootstrap Library in version 3. The Twitter Bootstrap Library is a HTML, CSS and JAVASCRIPT library for frontend development which is based on a mobile first, responsive approach to web design.
Much has been written about this library. However, here are a few links which should help you to make yourself familiar with the Library in case you are new to Bootstrap:
Designing your own Theme
The following guideline helps you to create your own theme. The easiest approach to develop your own theme is to build up on an existing one. For instance, you could modify the "Openacs-Bootstrap3-Theme" Package as a starting point.
- Make a local copy of the "Openacs-Bootstrap3-Theme" Package
- Rename the package.
- Take particular care of the .info file. Rename all the places where you find "openacs-bootstrap3-theme", and give a unique package key.
- Take particular care of the tcl/apm-callback-procs.tcl file. The subsites defined here through subsite::new_subsite_theme need to have a unique key, so give all the subsites you create here a unique key. Also, take care of the namespace.
- Before starting to modify the package, it is best to try to install and de-install the package on a test instance to make sure that you have all the naming right.
- Now feel free to modify the design as you like.
Themes in .LRN
When installing .LRN, the theme-zen is installed and activated by default.
.LRN comes now with a new theme package, the "Dotlrn-Bootstrap3-Theme" Package (as of July 2016, it is in proof-of-concept state!).
The "Dotlrn-Bootstrap3-Theme" Package builds on the "Openacs-Bootstrap3-Theme" Package and depends on both the "Openacs-Bootstrap3-Theme" Package and the "Theme-Zen" Package.
The Theming specifics described above also apply to .LRN theming, but additionally you should consider the following points:
Portal Pages Design
The Design of a Portal Page is defined on 3 levels:
- The subsite theme (which can be chosen on the "Configure"- Page, as described above)
- The page layout: It defines whether the page has, for instance, a 1-column, 2-column or 3-column layout. In the "Dotlrn-Bootstrap3-Theme" Package, the layouts are defined at lib/layouts.
- The portlet theme: It defines the look&feel of the single portlet. In the "Dotlrn-Bootstrap3-Theme" Package, the themes are defined at lib/themes.
Since every portal which is created, stores the portlet theme ID in the database, and since every portal page that is created, stores the page layout ID in the database, changing a theme in .LRN requires an upgrade of the affected database tables. This is done by the tcl/theme-procs.tcl/xql in the "Dotlrn-Bootstrap3-Theme" Package.
!!!!!! Attention: If you switch to the .LRN-bootstrap3-theme, all the portal pages are updated to the bootstrap3 layout !!!!!!
Installing and De-Installing the "Dotlrn-Bootstrap3-Theme" Package
If the "Dotlrn-Bootstrap3-Theme" Package is de-installed, the above described portal pages design falls back to the theme-zen design. This should make sure that the portal pages are always provided with a working layout.
Created by Byron Linares, last modified by Gustaf Neumann 26 May 2021, at 12:32 PM
This page is obsolete and kept as a reference.
The how-to for a well maintained Windows installation is here.
OpenACS/dotLRN windows installer how to
Required software:
Download
Installer Sources:
The installer source consists in a main Inno Setup script “installer.iss” and could be found in cvs or obtained with the installer.
Other files:
There are some necessary file numbers in order to build the installer.
- tcl\bintallerw.tcl: the AOLserver configuration script
- Install.xml: this XML file control the packages installed by the OpenAcs installer
- tcl\Windows-procs.tcl: This file includes various hacks to make OpenACS work on Windows.Replaces the TCL exec command on Windows, allowing exec to be called with unix-y arguments.Index.tcl : file used for automatic installation.
- Index-org.tcl: file used for manual installation.
- Installer.tcl: file used in automatic installation.
- Installer-org.tcl: file used in manual installation.
- Stara.bat, stop.bat: batch files for starting and stopping all services.
- Tools/setx.exe, tools/reg.exe ,/tools/uzip.exe, /tools/reg.exe Windows command line tools necessary for the installation process.
- AOLserver_4-0-beta-10_2003-08-04.zip: AOLServer
- cygwin.zip: CygWin Unix environment for Windows. Cygwin.zip also contains the PostgreSQL database
- cygwin.bat: file to launch cygwin unix environment console.
- license_en.txt: license text file.
- important.txt: extra info text file.
- Note.txt : especial notes text file.
Download Resources
Building the installer:
- In order to build this installer we need to place all the resources in a folder.
- Create tools and tcl folders with the files before mentioned.
- Download OpenACS, dotLRN and all desired package and place in a folder and named “oacs-dotlrn”
- Open the file installer.iss and generate the installer.
The installer.iss has to important parts:
[Files] section:
In this section are listed all the sources for the installer, in this part you
Can change or add any source that you want.
[Run] section:
In this section is where all commands are executed, like the cygwin installation, postgreSQL installation and AOLserver.
[Code] section:
Section for define procedures or functions to work around the installation.
These are the main sections in the “installer.iss” script. And the sections that have to be changed form personalize the installer.
developed at the Galileo University (www.galileo.edu) by Byron Haroldo Linares Roman bhlr@galileo.edu as part of the E-LANE project (www.e-lane.org)
Instructions on using the installer are at:
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.
Created by Kenneth Wyrick, last modified by Benjamin Brink 29 Jun 2017, at 11:38 AM
Next-Steps
After following:
Debian Installation Instructions
A. Installing Daemontools
Documentation
nano /usr/share/doc/openacs|dotlrn/README.daemontools on openacs package.
apt-get install daemontools daemontools-run
B. Configuring Daemontools and Using SVC
1) Change the "StartDaemon" value to "no" in /etc/default/:
# OpenACS
nano /etc/default/openacs
... or ...
# .LRN
nano /etc/default/dotlrn
2) Stop the daemon:
# OpenACS
/etc/init.d/openacs stop
... or ...
# .LRN
/etc/init.d/dotlrn stop
3) Link daemontools dotlrn|openacs script:
# OpenACS
ln -s /usr/share/openacs/etc/daemontools /etc/service/openacs
... or ...
# .LRN
ln -s /usr/share/dotlrn/etc/daemontools /etc/service/dotlrn
Now you can control the dotlrn service using the svc command:
* To start the service: svc -u /etc/service//openacs or dotlrn
* To stop the service: svc -d /etc/service//openacs or dotlrn
* To restart the service: svc -t /etc/service/openacs or dotlrn
C. If There's Problems Purge and Reinstall
apt-get remove --purge openacs or dotlrn
apt-get install openacs or dotlrn
D. To configure the instance to listen on a different IP than 127.0.0.1
Edit the config.tcl file:
nano /etc/openacs|dotlrn/config.tcl
Change the following parameters to fit your needs:
set hostname Your hostname
set address to Your public IP
E. Backup and Restore (to be filled in)
and found that I had to figure out how to:
su - $OPENACS_SERVICE_NAME
pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp openacs-dev
ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp
exit
The $OPENACS_SERVICE_NAME
which I thought would be "dotlrn"
turned out to be "www-data"
Next I found there was no /var/lib/aolserver but there are /var/lib/dotlrn and /var/lib/postgresql
The default paths show the locations that were decided upon (in early 2004) so below we will try to document were things are in a standard dotlrn installation, now.
| a work in progress |
|
| |
|
| OpenACS service |
dotlrn |
| OpenACS service account |
www-data |
| OpenACS database name |
dotlrn |
| SERVERROOT |
/usr/share/dotlrn/www |
| Database backup directory |
/var/backups/ |
| Service config files |
/usr/share/dotlrn/etc/config.tcl |
| Service log files |
/usr/share/dotlrn/log/ |
| PostgreSQL directory |
/usr/lib/postgresql/8.3/main |
| AOLserver directory |
/usr/lib/aolserver4 |
| Backup Script |
/usr/share/dotlrn/etc/backup.sh |
F. Installing Packages (to be filled in)
1. From .LRN CVS
a) Create a local repository
b) Download to your local repository
G. View the Log File
nano /var/log/aolserver4/dotlrn/error.log
H. Mail Server (to be filled in)
- Installation
- configuration
Created by OpenACS community, last modified by Gustaf Neumann 07 Jul 2016, at 02:34 PM
Documentation Requirements for Developer Tutorials
By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS developer tutorial documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.
-
list learning prerequisites to customize, fix, and improve OACS modules, and create new ones. You are expected to have read and understand the information [minimum requirements similar to adept at Using OpenACS Administrating Guide] before reading this guide.
-
Refer to development documentation instead of duplicating here
-
List suggestions for installing and setting up a development environment; these can be annotated links to the installation documentation
-
Provide working examples that highlight the various subsystems, tcl environment, OpenACS protocols, aolserver template and ns_* commands, OpenACS templating, sql queries, db triggers, scheduling protocols, how to use the page contract, how to get the accessing user_id etc
-
Show how to construct basic SQL queries using the db API,
-
The life of an http request to a dynamic, templated page
-
General rules to follow for stability, scalability
-
Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package development, by referring to developer resources.
-
Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a PostgreSQL equivalent tutorial about developing a new OpenACS package including discussion of the significance of the package documentation templates
-
Include a summary of important links used by developers
-
Note any deprecated tools and methods by linking to prior versions instead of describing them in current docs
