Be Careful This page is for prototype development only. If you want to do general Sakai3 development, you should read the Sakai 3 UX Development Guidelines and Information page.

Getting started

Before you get started you'll need to have Sakai3 up and running together with the fsresource bundle.

Software

Software you need

• Git - Version control system which you need to get the current 3akai-ux code + push your own changes to it. More information on K2 git tips for developers
• Java - You need this to run K2, which is the back-end project
• Maven - To build K2

Software that is useful

• Aptana Studio - An IDE which most of the front-end developers use to develop HTML/CSS/JavaScript (Setting up Aptana Studio for Sakai3 UX development)
• SVN - Version control system that will allow you to check out the current documents we have for prototypes

First run

Install K2

Add the following line to your .mavenrc file. (Make sure it doesn't have an extension .mavenrc.txt)
It should be in your home directory ~/ if it is not, just create it.

MAVEN_OPTS="-Xmx900m -Xms168m -XX:PermSize=256m -XX:NewSize=64m"

Go to the folder you want to install Sakai and make a directory called sakai.

cd /opt/
mkdir sakai
cd sakai

Clone the files from Ian (ieb) into that folder. This will create a folder called open-experiments

git clone git://github.com/ieb/open-experiments.git

Build the K2 project. The reason we add the -Dmaven.test.skip=true is to make the build faster. This means that you skip the back-end tests which isn't a best practice if you want to develop back-end code as well.

cd open-experiments/slingtests/osgikernel
mvn clean install -Dmaven.test.skip=true

If an error occurs during this build I suggest you send a post to the sakai-dev mailing list.

Run K2

Execute the jar file.

java -Xms32m -Xmx256m -jar app/target/org.sakaiproject.kernel.app-0.2-SNAPSHOT.jar -f -

Fork the UX code

In order to be able to push changes online, you'll have to fork the code from oszkarnagy.

Make sure you are logged in and then press the fork button on the main 3akai-ux page.

When you have forked the code, you should have a page like http://github.com/__USERNAME__/3akai-ux.

Then copy your private URL which looks like git@github.com:_USERNAME_/3akai-ux.git

Get the UX code

Clone the 3akai-ux code from your own git repository

cd /opt/sakai
git clone git@github.com:__USERNAME__/3akai-ux.git

Go into the newly created folder called 3akai-ux and add the christianv remote repository

cd 3akai-ux
git remote add christianv git://github.com/christianv/3akai-ux.git

Create a new branch called prototype and merge the remote branch into it

git fetch christianv
git checkout -b prototype master
git merge christianv/prototype

Use the fsresource bundle

When you build K2 it also gets the latest UX code from git. But if you are doing front-end development I would suggest you keep the K2 (back-end) and 3akai-ux (front-end) as separate as possible. The fsresource bundle will give you the ability to map the dev and devwidgets folder to the location you want (e.g. /opt/sakai/3akai-ux/dev)

Download the fsresource jar file and put it under /opt/sakai/

http://people.caret.cam.ac.uk/~cv268/sakai3/fsresource/org.apache.sling.fsresource-0.9.3-SNAPSHOT.jar

Map the /dev and /devwidgets folder (Keep in mind that K2 needs to be running for this)

cd /opt/sakai/open-experiments/slingtests/osgikernel/tools
./startux.sh -j /opt/sakai/org.apache.sling.fsresource-0.9.3-SNAPSHOT.jar -d /opt/sakai/3akai-ux/dev -w /opt/sakai/3akai-ux/devwidgets

Now you should be able to check if everything is running fine. Go to http://localhost:8080/dev/index.html and log

Update

Update K2

Useful Information When you update K2, you'll also have to redo the fsresource step

Go into your open-experiments folder and add ieb to your tracked repositories (you only need to do this once - not for every update cycle)

cd /opt/sakai/open-experiments
git remote add ieb git://github.com/ieb/open-experiments.git

Fetch his latest code and merge it with your local code

git fetch ieb
git merge ieb/master

Remove the sling folder

cd /opt/sakai/open-experiments/slingtests/osgikernel
rm -rf sling

And build K2 again

mvn clean install -Dmaven.test.skip=true

Developing your first prototype

When you want to develop your first prototype you should first have a look at the Sakai 3 UX Development Guidelines and Information page. That page contains information and guidelines for front-end development.

Work-flow

Make sure you are working on the prototype branch:

cd /opt/sakai/3akai-ux/
git status

You should see something like this:

# On branch prototype

Update the ux code:

git fetch christianv
git merge christianv/prototype

Then make all the changes you want and push them to your remote repository.

git status
git add .
git commit -m"prototype - __MESSAGE__"
git push origin prototype

Send a pull request to christianv.

Things to keep in mind

• Prototypes can be expected to only work with the admin account (admin - admin)
• Since prototypes aren't finished designs, it is allowed to only make them work in one browser. At the moment everybody should use Firefox to test and develop them.

Requesting a prototype to be implemented

If you would like a prototype to be implemented you should open a Jira ticket on Sakai Jira.

1. Log in on Sakai Jira
2. Click on Create Issue
3. Select "Sakai 3 - Core" as project and "Task" as issue type
4. Click next
5. Fill in the details for the issue

When you are filling in the details for the issue, there are some rules you should follow:

• Summary: start it with "Prototype - " and make it as descriptive as possible
• Components: select "UX Design"
• Affects Version/s & Fix Version/s: "unknown"
• Description: try to be as concrete as possible. E.g. the button with text "Submission" needs a tooltip with "Download your submission"