Connexions Importer : Author's Web Client and Toolkit

The content uploader is a web application that authors can use to convert their educational materials to the Connexions repository format (CNXML), preview how they will look in the repository, and then use the OER Publishing API to upload and publish their modules. Version 2 of the tool will also support editing content previously uploaded or published. Version 3 will have a Wysiwyg editor incorporated.

The content uploader uses the OERPub API to talk to an OERPub Service in Connexions.

The tool accepts

• Word and Open Office documents
• Google Docs
• Google Docs Conversion Documentation
• HTML (blogs work well)
• Advanced mode
• CNXML : https://trac.rhaptos.org/trac/rhaptos/wiki/XMLFormats
• LaTeX

Author Documentation

The current beginnings of documentation for authors are in the source directory under user-docs. The documentation includes

• Specialized instructions for using Word and a set of macros to create CNXML features.
• LaTeX importer readme that points to the Connexions docs

User Interface Design for new version

• Designs and team discussion notes are linked inside this Google doc.

Code and Development Process

Setting up the environment

To get your own local instance of the client you will need to set up your development environment and get the source code for the uploader from github.

• 1. Have Ubuntu 10.04 or higher
• 2. Install git with `sudo apt-get install git-core`
• 3. Register a new account on github.com and follow github's instructions
• 4. Create your development instance of the uploader, oerpub.rhaptoslabs.swordpushweb-buildout, by following the steps in this README from Johan

With these steps you should now have your own local server which you can use for development. The readme describes how to update the code from github.

All source files are inside the src/ folder. You can modify and analyse them. In the following section we describe the usage of git and github to show how to contribute to code.

Develop code, git

If you are not familiar with git, get used to it!

Some good links to read:

• git-for-beginners-the-definitive-practical-guide
• Read and understand the beginners section on github's help pages
• Advice on branching: http://nvie.com/posts/a-successful-git-branching-model/
• Forking is explained here: http://help.github.com/fork-a-repo/

Develop code, change existing code

To contribute to code you need to understand the structure of the source code.

The oerpub.rhaptoslabs.swordpushweb-buildout is the main repository. It builds and downloads all other git/mercurial repositories. I will call them modules because each repository (oerpub.rhaptoslabs.xxx) has its own purpose.

To get an overview of all used modules look at the [sources] section inside buildout.cfg (readonly-access) or dev.cfg

If you want to change code, create a branch and then modify the buildout.cfg and dev.cfg to point on your own branch of the module. You can also find all modules in the src/ folder.

Debugging code inside the pyramid web-framework (swordpushweb)

Add this two lines to your point of interest to get a python debug console:

import pdb;pdb.set_trace()
form.data

Add a new module to buildout

For adding a new module to buildout you have to add an egg to the [pyramid] section and add the repository url to the [sources] section.

Place the readonly repository into buildout.cfg and the read-/write one into dev.cfg .

How to eggify source code

For creating eggs, the best way is to create an egg skeleton using paster, and then just place your code in the lowest-level directory.

Here's a chunk from my history file, where I installed zopeskel in a separate virtualenv to create the oerpub eggs:

cd instances/
mkdir test-zopeskel
cd test-zopeskel/
virtualenv --no-site-packages .
./bin/easy_install -U ZopeSkel
./bin/paster create --list-templates
./bin/paster create -t nested_namespace

I used nested-namespace for the oerpub.rhaptos.xxx stuff, to get the 2 dots in the namespace.

Remove CONTRIBUTORS.txt and rename README.txt to README.rst. Do this also in setup.py. Set author, email and url in setup.py .

Very important: Do not forget to include the right license (GPL 3) and Licensing text for Shuttleworth Foundation (TODO: needed link to text)

Upcoming Development Work

Figuring out how to hook up the additional parts of the OERPUB API into the uploader so that we can get the new design implemented for the Connexions conference in February 2012

References:

• The documentation for OERPub - This is the basic spec, but without the details of the cnx implementation.

• The Connexions implementation of OERPub - This should have everything you will need. Under each API that we need the section in this document is given.
• Connexions Developer documentation on trac and client reference: This may not have complete explanations of all the implemented API, but it is oriented toward common Connexions actions and therefore may be the clearest documentation.

The pieces of the API that we need to hook into the new uploader are as follows:

1. Getting a listing of existing documents from a work area
• Section 6.2

2. Getting the content of a module that has already been uploaded. This involves getting the content and also parsing the metadata that comes back in the atom entry and filling the metadata page in with those.

• Section 6.4

3. PUTing the resulting CNXML and atom entry back to an existing module in the same work area it came from. To change both metadata and content you PUT to the Edit-IRI and I think we can just always do that.

• Section 6.5.3

4. Checking out a new version of a module, and then GETing the content to edit (2) and then saving the resulting changes (3).

• Section 6.3.4

5. Creating a derivative of a module, and then GETing the content to edit (2) and then saving the resulting changes (3).

• Section 6.3.5