SELF Platform Documentation

This is a documentation in progress. When you do not see this opening paragraph, we consider that this is usable. Currently this serves the purpose of the SELF Platform developers and documentation writers and is not rated suitable for other users. If you are still curious, of course, you can help your self. if any questions please contact us on the self-platform-dev@nongnu.org mailing list.

Table of Contents

1 What is SELF Platform?

SELF Platform is a web based, collaborative and distributed authoring system for learning materials following open standards. SELF Platform is free software application. More details from SELF Platform.

A pictorial representation of the SELF Platform is as follows:

Pictorial Description of SELF Platform

2 How to install SELF Platform?

The installation procedure is still not automated. Currently the following procedure helps technically savvy to install and inspect the software. RPM and Deb based packaging will be done shortly.

As and when the procedure advances this documentation will be updated.

2.1 Download selfApp

You can check out the most upto date versions from cvs.

"cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/self-platform co selfApp"

2.2 Whatelse do we need?

The following are the dependencies of selfApp

2.2.1 postgresql for storage

version 8.1 or above.

If you are using debian based GNU/Linux, 'apt-get install postgresql' will do.

After installing postgresql, you will need to switch to the postgres user to create new users.

sudo su postgres -

Then use `createuser` to add a new database user. For creating the database use the `createdb` command.

You can list the database using the `psql -l` command while being the postgres user itself.

2.2.2 Zope and Plone

Zope2.9 or above (not tested or ported to Zope3.0 or above).

Plone2.5 or above should work.

If you are using Debian based GNU/Linux, 'apt-get install plone-site' will do. This will also install Zope2.9 and other dependencies.

2.2.3 python-psycopg2 and zope-psycopgda2

These two wrapper libraries required for interfacing Python with Postgresql.

If you are using Debian based GNU/Linux, 'apt-get install python-psycopg2 zope-psycopgda2'

We often find that the zope-psycopgda2 is installed in 'usr/share/zope/Products/ZPsycopgDA:2'. This some how does not work in our systems. So, we have a workaround: make a link as follows: ln -s /usr/share/zope/Products/ZPsycopgDA\:2 /var/lib/zope2.9/instance/plone-site/Products/ZPsycopgDA'

In case, have compiled and installed Plone, please compile and install ZPsycopgDA as provided in the plone website.

http://plone.org/documentation/how-to/how-to-setup-sqlpasplugin-to-authenticate-against-a-postgresql-database

Please do an appropriate installatiion on your system depending on your system. When you restart Zope, you should be able to see the product 'ZPsycopgDA' in the ZMI:/ControlPanel/Products/'.

2.2.4 LocalFS

Download LocalFS product from: http://www.easyleading.org/Downloads/LocalFS-1.7rc1-andreas.tar.gz

LocalFS should be unpacked and put in the `Products` folder. One needs to restart Zope for it to work.We use LocalFS to access filesystem at the CLIENT_HOME, where pickled views of each node of GNOWSYS is stored in separate folders for each node. We also use this for uploading files such as images, and other files that are used as resources in the platform.

2.2.5 Build the storage schema for the knowledge base

The storage of SELF Platform is managed by GNOWSYS. All components of GNOWSYS are distributed as a part of the selfApp.

check out the latest version of gnowsys-pg by giving the following command

cvs -d:pserver:anonymous@cvs.savannah.gnu.org:/sources/gnowsys co gnowsys-pg

and then change directory to gnowsys-pg/ and give the following command

python genSchema.py -g <databasename> <hostname or ip> <username> <password>

for example

python genSchema.py -g gb localhost username password

This command will work only if you have a postgresql server running and you have provided the account details properly in the above command.

This will result in creating about 147 tables, 10 views, and authentication schema etc. This is the generic GNOWSYS schema.

The next step is to install selfApp in Plone, and create a database connection from the Plone instance and create the schema required for the selfApp.

2.2.6 Zsycopg

Inside the plone instance click on the 'Add' button and select 'Z Psycopg 2 Database Connection' then give the id as 'auth_db' and put in the connection string as 'dbname=<databasename> user=<username> password=<password> host=<localhost> port=<port no>' keep the rest as defaults and press 'Add'

2.2.7 SQLPASPlugin

This plugin stores all the user details in the postgresql, and is an extension to the Plone/Zope authentication.

You can obtain this from http://plone.org/products/sqlpasplugin

SQLPASPlugin is a Plone Archetype product. Therefore, its installation can be done by first copying the folder 'SQLPASPlugin' in the Products folder. Then change the ownership of the SQLPASPlugin folder to plone:users. Restart Zope, and view the Plone site; goto Preferences; select "Add/Remove Products"; select 'SQLPASPlugin' and click 'install' button.

Next step is to perform some configuration of the Plugin.

fullname/fullname email/email

2.2.8 ZtinyMCE

2.2.9 GNOWSYS

This is supplied with selfApp.

2.3 Installing selfApp in Plone

  1. copy the entire selfApp directory with all the files in it into the 'Products' path of the Plone installation. Ensure that the permissions of the directory is as per the Plone settings.
  2. Edit the file DB_connectionString.txt put the appropriate values

    dbname=<databasename>:user=<username in database>gnowsys:<password=<password of database>:host=localhost:port=5432

  3. restart zope if it was already running, else start zope server. usually "/etc/init.and/zope2.9 start/restart" should work.
  4. go to the Zope management Interface using a browser, say firefox depending on which port the Zope is currently running. Usually it is http://localhost:8080/manage
  5. install a "Plone Site" from the add product menu. The name of the Plone site can be your choice, say 'self-platform'
  6. if the name of the Plone Site is given as 'self-platform', then view the self-platform from http://localhost:8080/self-platform
  7. click on the link "Preferences" You will see this if you are already logged in. You have to be logged in as a user with 'manager' previleges.
  8. from the left hand side panel you will find a link by name "Add/Remove Products".
  9. select "selfApp" from the quick installer, and add.

    These steps will extend the Plone site and mutate it to behave like a self-platform. After this step, you can use the self-platform from the http://localhost:8080/self-platform.

3 gnowQL

Gnowledge Query Library (gnowQL) is used to add, retrieve and edit the content. All the ZPT (Zope Page Templates) of the self-platform use mostly the gnowQL.

You may see an object by name gnowQL in the self-platform instance. This is the main connection service agent to the knowledge base providing agent oriented (distributed) access to the data. You can access this object using xmlrpc protocol using any of the language libraries. We mostly use Python.

3.1 How to connect to the appropriate database.

Please configure the zope-psycopgDA object to point to the correct GNOWSYS database with all the details. To configure this, you need to know the user name, password, port number where Postgresql is running, and the database name where the GNOWSYS schema was built as described in the above section titled "Build the storage schema for the knowledge base"

4 API of SELF Platform

4.0.1 adding nodes as courses, lessons and collections

The methods start by the name 'manageAdd<NodeType>(dictionary)' If the nodetype is an object, the method will be 'manageAddObject(dictionary)'

The method takes only one parameter as a Python dictionary object.

The structure of the dictionary object can be as follows:

{'nid'='gnu emacs','title'=['GNU Emacs','Emacs'],'description':'An extendable macro editor', 'uid':35}

Where 'nid' is nodeid, and 'uid' is user id. The order of the items in the dictionary do not matter. If any of the mandatory keys in the dictionary are not supplied the system will raise an appropriate error.

Currently the knowledge base has the following nodetypes:

A complete list of the fields will be documented here. Meanwhile you may refer to the Autogenerated HTML schema of GNOWSYS storage schema. Each node will have a prefix 'gb' in the schema, and suffixed by 's'. e.g., Object node will be described as 'gbobjects'.

4.0.2 retrieving node information

4.0.3 updating node information

4.1 Examples of Templates in ZPT

4.1.1 a form to add a node

4.1.2 retrieving node information

4.1.3 a form for updating node information

4.2 Examples of managing from a Python Interpreter using xmlrpclib.

4.2.1 retrieving information

5 SCORM

SELF Platform is built to conform to SCORM (Shareable Content Object Reference Model)

5.0.1 LOM: Learning Object Metadata

The link below is a representation of the various attributes a learning object will have. These are mostly adopted from Dublin Core Metadata.

LOM: learning object metadata

5.0.2 Course Metadata

Metadata of a course is captured by the 'manifest' specification in SCORM. The link below is a representation of the manifest metadata. This metadata is attached to a course object.

SCORM Manifest, Course Metadata

5.0.3 Sequencing and Navigation Metadata

SCORM 2004 specifies more than the above set of metadata for finer control of course delivery to learners. This set of metadata is useful for a run time enviornment like Moodle to deliver to learners.

Sequencing and Adaptive Navigation

5.0.4 Documentation Authors Instruction

Please check out the files from cvs using the command "cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/web/self-platform consists of self-platform"

Use the 'self-doc.org' file to modify. Generate the html file by exporting from the orgmode in GNU Emacs.

6 Internationalization of selfApp

For internationalization of selfApp this web page was referred. The pot file was generated using the following command

i18ndude rebuild-pot --pot selfApp.pot --create selfApp --exclude="global_searchbox.pt" .

All the files related to internationalization are located inside selfApp/i18n/ .It basically consists of selfApp.pot and the po files of the languages whose translation are supported inside the platform.

To modify the translations of various languages it is recommended that an application called poedit is used it is available in the software repositories and can be obtained by

sudo apt-get install poedit

The directory contains a template po file called default.po which can be used to add support for languages which are already not supported in selfApp. To edit the po file open it with poedit and add the translated strings to the same, once the translation is over go to Catalog-> Settings and add the Language and Country values save the file as selfApp-xx.po where xx is the language code.

7 Troubleshooting

7.0.1 While installing selfApp if you get an error

'cant set encoding to' then do the following go to the following directory

/var/lib/zope2.9/instance/plone-site/Products/ZPsycopgDA

and edit the file DA.py, in line number 82 put encoding='UTF-8'

7.0.2 If any errors related to LocalFS are encountered please check if it

has been correctly installed. If not please make the following changes in line number 52 of LocalFS.py

#from OFS.content_types import find_binary #It was replaced with the following line from zope.app.content_types import find_binary

7.0.3 Errors related to selfApp tarball

Author: Nagarjuna G <nagarjun AT gnowledge DOT org>

Date: 2008/12/10 09:25:47 IST