Forum OpenACS Q&A: New OpenACS Tutorial

Request notifications

Collapse
Posted by César Clavería on
Hello all,

Rocael Hernandez and I have been working on a new tutorial for OpenACS, it is aimed at absolute beginners, it covers some simple installation process, the creation of an application and some introduction to the use of ACS Objects, it leaves out some parts of working with OpenACS, but this is really aimed at just the first few days of a new developer.

We have been working on this for quite some time and are very proud to present the first version we feel is ready for public viewing:

Here is the link:

http://openacs.org/storage/view/tutorial%5C/OpenACS_Tutorial.pdf

Collapse
Posted by Cesareo Garci­a Rodicio on
Hello!

Thanks so much! It is a great work.

I think that the level is not "absolute-beginners", I mean, it's not so easy to learn this in four days (in my experience). As I could review the tutorial is about:

Day 1. Connect to an openacs installation and do an "openacs helloworld" page
Day 2. Create a new package (presentation, programming and data)
Day 3. Web Forms a Reports with OpenACS (this is very useful)
Day 4. ACS Objects and Content Repository

So, the most important staff in OpenACS

Really Usefull!! do we have an on-line version?

Cesáreo

Collapse
Posted by César Clavería on
Hi Cesareo,

thanks for the feedback and the breakdown of the contents.

And yes the content is probably intended for someone with the time to read it and some kind of technical background, in the end it covers the creation of a pretty basic application but trying to use as most of the OpenACS functionalities as possible without making it too complex.

About the online version, I'm working on it and will let you know when it is ready.

Collapse
4: Re: New OpenACS Tutorial (response to 1)
Posted by Emmanuelle Raffenne on
Hi César,

Great tutorial! Thanks for sharing it.

Do you plan to update the OpenACS documentation (acs-core-docs) with the content of this tutorial?

Thanks again.

Collapse
5: Re: New OpenACS Tutorial (response to 4)
Posted by César Clavería on
Hi Emma,

I'm glad you liked it :) and, yes, the content of this tutorial will become part of the documentation in the near future, I have taken the job of updating the documentation for the next release ( job #1 described here: http://docs.google.com/Doc?id=ddjwq8c5_9g7jgtbcm ) I'm starting to plan how I will be approaching this job and will post my work plan to get some feedback before starting, but definitely the content of the tutorial will find its way there.

Collapse
6: Re: New OpenACS Tutorial (response to 5)
Posted by Emmanuelle Raffenne on
Hi César,

That's very good news.

I can help reviewing a few markup and accessibility issues I've noticed in the examples of the tutorial.

Collapse
7: Re: New OpenACS Tutorial (response to 1)
Posted by Caroline Meeks on
Nice!

You might want to consider putting it up on flossmanuals.net and/or having it available for purchase on Lulu.

Collapse
8: Re: New OpenACS Tutorial (response to 6)
Posted by César Clavería on
Hi Emma,

That is great, thank you!

Collapse
9: Re: New OpenACS Tutorial (response to 7)
Posted by César Clavería on
Hi Caroline,

Very good idea, thank you :)

Collapse
10: Re: New OpenACS Tutorial (response to 1)
Posted by Dave Bauer on
This looks really great, I see you put quite a bit of effort into it. I did some some funky formatting in the PDF on OS X. I'll try to test on some other PDF viewers to compare.

I think it might be a gentler introduction to use the subsite "Applications" page to setup the TODO notes package intead of the site map and introduce site-map later if necessary for more advanced features.

I see when you add the todo items you use acs_object_id_seq.nextval instead of nextval('t_acs_object_id_seq'); This would be confusing to those not accoustomed to the sequence view hack used to make it similar to Oracle syntax. It would be good to explain why you do that.

In defining the Tcl API, the procedures do not have a documentation block. I think it is best practice to use the documentation block along with @param @return tags.

These are all things that could be addressed when the source of the tutorial becomes available. I'll try to review the tutorial some more. We want to make sure
1) The tutorial matches our engineering standards and
2) The documentation for our engineering standards are up to date.

Thanks again for doing this work, I hope we can make improvements to this tutorial and keep it up to date with the current best development practices.

Collapse
Posted by Rocael Hernández Rizzardini on
I agree, will be simpler to use subsite applications, although the tutorial also goes directly to what you have to do and doesn't stop on the other things you might be able to do at site-map.

Yes, we need to correct the proc declaration to use auto-documentation, and do a very brief note about documentation features.
Also a note on the sequence hack can be made, I really do not expect newbies to focus much on that, maybe we can add a footnote.

Not sure whether we'll keep the sources in Word as they are now or not. So far they are good for producing the pdf, we still need to figure out that. Formatting is important for the tutorial.

Collapse
12: Re: New OpenACS Tutorial (response to 1)
Posted by Gonzalo López on
Wonderful tutorial. It has been the best help I have found since I started in this great world.

Thanks

Collapse
Posted by Hector Amado on
Hi César!, thanks for this great tutorial, i have some suggestions,

I tried the tutorial using:
sudo apt-get install postgresql-8.3
and works fine.

In page 7, after you start the OpenACS service you can explain the user to browse http://localhost:8000 and fill the form an start the installation scripts for OpenACS and restart the service because if you don't do this you can't try http://localhost:8000/helloworld (it shows a blank page)

In page 8, normal user doesn't have permissions to write on /usr/share/openacs/www maybe you can explain how to change permissions like:

sudo usermod -a -G www-data ubuntuuser
sudo chmod -R 775 /usr/share/openacs/www

logout and login

In page 15, you have the information to create a package, but if you follow all steps you get:

The package key should contain only letters, numbers, and hyphens (dashes) and it must be lowercase.

You should write todo instead of Todo for the Package Key value.

Best regards,
Hector

Collapse
14: Re: New OpenACS Tutorial (response to 1)
Posted by César Clavería on
Hello All,

I have uploaded now an online version of the tutorial,as a really long web page here: http://openacs.org/storage/view/tutorial%5C/OpenACS_Tutorial.htm

I have incorporated some of the feedback you gave on you previous posts, thanks Hector and Dave.

The PDF has been updated to reflect the changes and you can get the word files here:

doc format: http://openacs.org/storage/view/tutorial%5C/OpenACS_Tutorial.doc

docx format: http://openacs.org/storage/view/tutorial%5C/OpenACS_Tutorial.docx

I'm going to be the one maintaining this tutorial, so feel free to contact me with any comments or corrections, thanks!

Collapse
15: Re: New OpenACS Tutorial (response to 1)
Posted by ttkk 1024 on
hi,César Clavería ,I am a chinese ,I want translate the tutorial in chinese, can you give me a permission?
Collapse
16: Re: New OpenACS Tutorial (response to 15)
Posted by César Clavería on
Hello,

Yes ttkk, a Chinese version would be great, go ahead!
The Word format documents work for you? If there is anyway I can help you do not hesitate to ask.

Collapse
17: Re: New OpenACS Tutorial (response to 16)
Posted by ttkk 1024 on
thank you very much ,please sent me your word format document,my email:ttkk1024@gmail.com
Collapse
18: Re: New OpenACS Tutorial (response to 1)
Posted by Gonzalo López on
With your permission i'm going to start translating your tutorial into spanish.

I know that is not as useful as the translation in chinesse but I hope it will help someone.

Collapse
19: Re: New OpenACS Tutorial (response to 18)
Posted by César Clavería on
Thank you very much Gonzalo, of course you have my permission and everyone's gratitude.

y hey, una version en español claro que es importante y util, ya hubiese querido yo algo asi cuando empece hace algunos años.

And being able to offer this on English, Spanish and Chinese pretty much covers a great % of the world population.

Collapse
20: Re: New OpenACS Tutorial (response to 1)
Posted by Robert Taylor on
César, great work.

I'm going to look at converting this to wiki documentation.

Nice.

Collapse
21: Re: New OpenACS Tutorial (response to 14)
Posted by ttkk 1024 on
I have a question ,when I go to http://localhost:8000/acs-admin/,I need admin permission,how can I get admin permission?
Collapse
22: Re: New OpenACS Tutorial (response to 1)
Posted by Gonzalo López on
With the user you used to make the installation you have administration permission
Collapse
23: Re: New OpenACS Tutorial (response to 22)
Posted by Don Baccus on
Something to add explictly to the tutorial, perhaps ...
Collapse
24: Re: New OpenACS Tutorial (response to 1)
Posted by Alberto Pesquera Martín on
Hello Cesar,

Great job. It's a good tutorial.

Thank you.

Collapse
25: Re: New OpenACS Tutorial (response to 22)
Posted by ttkk 1024 on
I use openacs on the windows,when I go to http://localhost:8000/acs-admin/,It always need email and password,but I don't know how can get administrator's email and password ,altough I am administrator
Collapse
26: Re: New OpenACS Tutorial (response to 22)
Posted by ttkk 1024 on
while I register a user and log In ,the system give me a message "You don't have permission to read Site-Wide Administration."
Collapse
27: Re: New OpenACS Tutorial (response to 26)
Posted by Dave Bauer on
When you first install OpenACS you fill out a form including an email address and password. This is the email and password you use to log in as the administrator.
Collapse
28: Re: New OpenACS Tutorial (response to 25)
Posted by César Clavería on
I think you need to use the Windows's installer admin user, it is on the linked site.

"In both OpenACS and .LRN there’s a predefined admin user (email: admin@acme.com, password: abc123)."

So try login in with admin@acme.com and password: abc123

Collapse
29: Re: New OpenACS Tutorial (response to 28)
Posted by César Clavería on
The Windows instructions page moved to here:

http://www.spazioit.com/pages_en/sol_inf_en/win32-openacs_en/

(I guess I'll need to update the tutorial)

Collapse
30: Re: New OpenACS Tutorial (response to 29)
Posted by Ryan Gallimore on
The tutorial is a great step in attracting and holding on to new developers. Is there any way we can add a BIG button/link to the openacs.org homepage?
Collapse
31: Re: New OpenACS Tutorial (response to 29)
Posted by ttkk 1024 on
this url is bad ,I can't link it
Collapse
32: Re: New OpenACS Tutorial (response to 1)
Posted by ttkk 1024 on
hello César Clavería ,I have completed translation in Chinese,how can I give you?
Collapse
33: Re: New OpenACS Tutorial (response to 31)
Posted by ttkk 1024 on
I am sorry , because our government don't allow us access the site
Collapse
34: Re: New OpenACS Tutorial (response to 33)
Posted by César Clavería on
Hello,

You can send it to me at cesar@viaro.net
I will make sure to upload it to the correct place and give you the recognition you deserve.

Thank you very much! This is great! :D

Collapse
35: Re: New OpenACS Tutorial (response to 1)
Posted by César Clavería on
Hello all,

I'm very pleased to announce the OpenACS tutorial first translation, we have now a Chinese version of our tutorial that I'm sure will be helpful to many people.

Thanks to our member ttkk 1024 for this translation.

OpenACS Tutorial (Chinese): http://openacs.org/storage/view/tutorial%5C/OpenAcs_tutorial_zh.pdf

Collapse
36: Re: New OpenACS Tutorial (response to 35)
Posted by Iuri Sampaio on
Hi guys,

Nice tutorial!
I really needed to read Day 4 - ACS object types

Is there space available for Portuguese translation?

I already translated Day 1. Plus i have some stuff to add from my experience.

cheers,

Collapse
37: Re: New OpenACS Tutorial (response to 36)
Posted by César Clavería on
Hi Iuiri,

Of course! a Portuguese translation would be very welcomed!

And any improvements to the tutorial will also be helpful, there are MS Word versions linked on this thread so you can use them to base yours.

thank you,

Cesar

Collapse
38: Re: New OpenACS Tutorial (response to 37)
Posted by Iuri Sampaio on
Cesar,

I finished the translation to portuguese.
is there a chance to upload on openacs.org?

I will be glad to load it there. I have no place else

:(
cheers

Collapse
39: Re: New OpenACS Tutorial (response to 38)
Posted by Iuri Sampaio on
I have uploaded it to the official Brazilian Openacs commuminity website

http://www.softwarepublico.gov.br/dotlrn/clubs/openacs/file-storage/download/Tutorial+OpenACS?file%5fid=18012882

Although, i am still interested to upload it on openacs file-storage

Collapse
40: Re: New OpenACS Tutorial (response to 39)
Posted by César Clavería on
Hi Iuri,

Thank you for the translation, sorry for the delay on responses. I will upload it to the OpenACS file storage as soon as I'm able to download it from softwarepublico.gov.br (I'm registering right now)

Collapse
41: Re: New OpenACS Tutorial (response to 39)
Posted by César Clavería on
Looks like even after registering I do not have permissions to download it. Could you check that? or send it to me by email? Thanks
Collapse
42: Re: New OpenACS Tutorial (response to 41)
Posted by Iuri Sampaio on
I just sent to you.

please, let me know when it will be available

Collapse
43: Re: New OpenACS Tutorial (response to 1)
Posted by Irma Gamez on
Hi. I'm following the tutorial, but my instalation is /usr/share/aolserver4/dotlrn, because I want to build a package for dotlrn. I'm saving the examples under dotlrn/www. The hello example works well, but with the connection example I'm having a server error "due to a system error on this server" running http://localhost:8000/connection

Maybe you can give some help. Thank you.

Collapse
44: Re: New OpenACS Tutorial (response to 43)
Posted by César Clavería on
Hello Irma,

Could you check your error.log file? It is probably going to be located in /usr/share/aolserver4/dotlrn/log/error.log that may give us some insight into what is wrong.

Also, if you are putting the examples under the www directory of the dotlrn package I believe you should try something like:
http://localhost:8000/dotlrn/connection

And do not worry those initial examples are OK if you put them under the general www directory (actually it is ok to put them anywhere as long as you know the path to get to them.)

Collapse
45: Re: New OpenACS Tutorial (response to 44)
Posted by Irma Gamez on
Thank you, Cesar, for your fast reply :)

The error.log says "Error: return: failed to redirect 'GET /global/file-not-found.html': exceeded recursion limit of 3"

Have a good day.

Collapse
46: Re: New OpenACS Tutorial (response to 45)
Posted by Jim Lynch on
Hi Irma...

That just means there was an error rendering the error page, which invoked the error page, which invoked the error page, whi STOP!

Oh, sorry...

But that's how it happened, including the STOP.

Collapse
47: Re: New OpenACS Tutorial (response to 46)
Posted by Irma Gamez on
Hi Jim.
I already fix the problem: I delete everything and start a new installation. All is running! Thank God.
Have a good day.
Collapse
48: Re: New OpenACS Tutorial (response to 47)
Posted by christopher laurence on
I'm attempting to run through the tutorial and I'm stuck with the following command. What am I missing? I'm using the latest software of openacs, postgresql, and naviserver.

sudo psql -d openacs -U wwww-data
psql: FATAL: Peer authentication failed for user "wwww-data"

Collapse
49: Re: New OpenACS Tutorial (response to 48)
Posted by Gustaf Neumann on
Dear Christopher,

this error message comes from PostgreSQL and tells you that the database does not know about a user "wwww-data". When you installed OpenACS with the default values of the install-ns and install-oacs scripts, then the created postgres user is named "nsadmin", the database is "oacs-5-8".

In this setup, sudo psql -d oacs-5-8 -U nsadmin should work.

Collapse
50: Re: New OpenACS Tutorial (response to 49)
Posted by christopher laurence on
Hello Gustaf,

I was able to get the command to work if I used "psql -d oacs-5-8 -U postgres" When I use sudo is asks for a password and it isn't the root password. After using the command I tried using insert into but got an error message. I have created a file in my package/todo/sql/postgres/ based on the tutorial.

oacs-5-8=# insert into todo_item values(acs_object_id_seq.nextval, 'My first item', 'My first item description', 'p', 568);
ERROR: relation "todo_item" does not exist
LINE 1: insert into todo_item values(acs_object_id_seq.nextval, 'My ...
^

Collapse
51: Re: New OpenACS Tutorial (response to 50)
Posted by Benjamin Brink on
Christopher, see page 48 (and just prior) of the tutorial. The error translates to: table "todo_item" doesn't exist.
cheers
Collapse
52: Re: New OpenACS Tutorial (response to 50)
Posted by Gustaf Neumann on
Christopher,

when the install-oacs script runs successfully, it creates the user 'nsadmin'; otherwise, other things might be broken as well. To check, which users are defined in your postgres installations, use

   %psql -U postgres 
   psql (9.3.5)
   Type "help" for help.

   postgres=# \du
in order to see, what databases are defined, use
   postgres=# \l

Collapse
53: Re: New OpenACS Tutorial (response to 52)
Posted by christopher laurence on
Hello Gustaf,

This is what I got when I enter the commands:

postgres=# \du
List of roles
Role name | Attributes | Member of
-----------+------------------------------------------------+-----------
nsadmin | Superuser, Create role, Create DB | {}
postgres | Superuser, Create role, Create DB, Replication | {}

postgres=# \l
List of databases
Name | Owner | Encoding | Collate | Ctype | Access privileges
-----------+----------+----------+-------------+-------------+-----------------------
oacs-5-8 | postgres | UTF8 | en_US.UTF-8 | en_US.UTF-8 |
postgres | postgres | UTF8 | en_US.UTF-8 | en_US.UTF-8 |
template0 | postgres | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/postgres + postgres=CTc/postgres
template1 | postgres | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/postgres + postgres=CTc/postgres
(4 rows)

Collapse
54: Re: New OpenACS Tutorial (response to 53)
Posted by Gustaf Neumann on
Christopher,

This looks correct. Therefore, the cmd as i wrote will work. maybe you were struggling with sudo. For setup of sudo, see e.g. [1]. One can setup sudo such it asks you once in a session for your password, or to ask for certain users never for a password, etc.

[1] https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux_OpenStack_Platform/2/html/Getting_Started_Guide/ch02s03.html

Collapse
55: Re: New OpenACS Tutorial (response to 54)
Posted by christopher laurence on
Hello Gustaf,

I'm using ubuntu 14.04 LT now. Is there any location where I can find the final version of the tutorial code? I have copied all the code but continue to get error messages.

Collapse
56: Re: New OpenACS Tutorial (response to 55)
Posted by Gustaf Neumann on
Dear Christopher,

i've never read the tutorial, this was contributed from the people in Guatemala. What kind of errors do you get?

-g

Collapse
57: Re: New OpenACS Tutorial (response to 56)
Posted by christopher laurence on
Hello Gustaf,

I'm getting errors that the database item doesn't exist. I'm trying to run through the tutorial to see how everything works before giving the system to a developer. I can at least complete the hello World! example.

Database operation "select" failed (exception ERROR, "ERROR: relation "todo_item" does not exist
LINE 8: from todo_item
^
")

ERROR: relation "todo_item" does not exist