Write your own Sugar web activity

Choose your development environment

You've got three choices to develop your own web activity for Sugar:

• install packaged Sugar on Fedora, Debian, or Ubuntu; or,
• use Sugarizer.

See Setup a development environment for more detail.

Sugarizer simulates the Sugar environment in a browser. So you need
only a browser to start developing. It's the better choice if you've
no time or knowledge to learn how to install or build Sugar desktop
on a GNU Linux distribution but you're not in a Sugar desktop
environment, so your activity may only work in Sugarizer.

Create the activity from the template

On packaged sugar, after you have built the development
environment, clone the Sugarizer repository.
Install volo through npm.

npm install -g volo

Create an activity based on the default template

cd sugarizer/activities
volo create MyActivity.activity ./ActivityTemplate
cd MyActivity.activity

On Sugarizer, after you've cloned - or copied - the Sugarizer
repository, copy all content of
activities/ActivityTemplate directory in a new directory
activities/MyActivity.activity.

Customize

Choose a name for your activity. Write it in the activity name and
bundle-id in activity/activity.info of the new directory.

And also in the title tag of index.html.

On packaged sugar, install the activity for development

python setup.py dev

On Sugarizer, update the file activities.json of the Sugarizer directory: add a new line for your activity. Update id, name and directory values on this new line.

Now you should have a basic activity running!

File structure

In your new activity, you will find the following file structure:

MyActivity.activity/
|-- activity/
| |-- activity.info
| -- activity-icon.svg |-- index.html |-- css/ | -- activity.css
|-- js/
| |-- activity.js
| -- loader.js |-- lib/ |-- package.json -- setup.py

• activity/ contains information about your activity, including the
  name, ID, and the icon.

• index.html is where the elements that compose your activity are
  defined. The template comes with a toolbar and a canvas where you
  can place your content.

• js/activity.js is where the logic of your activity lives.

• css/activity.css is where you add the styling of your activity.

Those are the files you'll modify in most cases. The others are:

• js/loader.js configures the libraries paths and loads your
  js/activity.js . You can add non-AMD libraries here.

• lib/ contains the libraries

• package.json contains information about the libraries the activity
  depends

• setup.py lets you install your activity or make an installable
  bundle with it

Now you are ready to go ahead and develop your activity in the html,
js and css directories.

Revision control your code

For development you can initialize the repository as a git
repository. This will help you to track your changes. First use git
init
to initialize the repository:

git init

With git
status
you can show the available files in the folder they are still
untracked. Now add all the files in the directory besides the lib
folder and commit those changes, you can use git status again to see
the current state:

git add .
git commit -a -m 'Initial import'
git status

First steps

Adding a button to the toolbar

This simple example will show you how web activities are structured as
bits of HTML, CSS and JavaScript.

You will need a SVG graphic for the button. Or you can use one from
the Sugar icon set at lib/sugar-web/graphics/icons/. For this
example, let's say you have one custom icon called my-button.svg.
Create a directory icons/ inside your activity and place the SVG
file inside. Then do the following steps.

In index.html, add a new <button> element inside the toolbar:

In css/activity.css, define the button style:

#main-toolbar #my-button {
background-image: url(../icons/my-button.svg);
}

In js/activity.js, add a callback for the button:

var myButton = document.getElementById("my-button");
myButton.onclick = function () {
console.log("You clicked me!");
}

Adding HTML content dynamically

Soon you will find that adding content to the HTML as we did with the
toolbar button in the previous section, is very limited. You'll want
to add HTML elements on the fly, as the user interacts with the
activity, or as the data structures of your activity logic change.
There are several options to archive this. Most of the time you'll
end up using a mix of them, so it is important to know them all.

First, it is possible to create HTML elements and append them to other
HTML elements using JavaScript. This is called "manipulating the
DOM".

For example, to create a new div with class 'my-div', and append it to
the canvas div, you can do:

myElem = document.createElement('div');
myElem.className = "my-div";
var canvas = document.getElementById("canvas");
canvas.appendChild(myElem);

But it is a pain to do that for large HTML structures. Writing HTML
directly is much better:

var canvas = document.getElementById("canvas");
canvas.innerHTML +=
'

' +
'
• Tom
' +
'
• Chris
' +
'
• Donald
' +
'

Nice, that saves us many JavaScript lines. But what if the HTML
depends on your data? Let's say you have an array of names and you
want one <li> per name, as in the previous example. You have
two options: 1. go back to use the JavaScript methods for DOM
manipulation, or 2. use a template system.

There are many template systems out there, and you can use whatever
you like. Let's try mustache here.

Add mustache to your activity:

volo add mustache

Import mustache in your js/activity.js:

var mustache = require("mustache");

Use it:

var template =
'

' +
'{{#names}}' +
'
• {{ name }}
' +
'{{/names}}' +
'

var data = {names: [{name: "Laura"}, {name: "Joao"},
{name: "Willy"}, {name: "Sandra"}]};

var containerElem = document.getElementById("container");
containerElem.innerHTML = mustache.render(template, data);

Debugging

If you want to inspect the code, you can press ctrl+shift+I while your
Activity is running.

The inspector is a very useful tool for many things. For example, you
can edit the activity CSS or HTML, and interactively see how it is
affected. Or you can execute JavaScript commands in the console.

It has also more advanced tools for JavaScript debugging. They are
nicely documented here:
https://developers.google.com/chrome-developer-tools/docs/javascript-debugging.

Keeping Sugar libraries up to date

The activity depends on the
sugar-web library
that provides the Sugar API and the Sugar look & feel.

This means that if there are changes to the library you have to update
your local copy. You can do this with running
the following command inside the activity directory:

volo add -f

Using other JavaScript libraries

AMD-ready

You can easily add AMD-ready libraries with volo. For example, to add
RaphaelJS:

$ volo add DmitryBaranovskiy/raphael
Downloading: https://codeload.github.com/DmitryBaranovskiy/raphael/legacy.zip/v2.1.2
Installed github:DmitryBaranovskiy/raphael/v2.1.2 at lib/raphael.js
AMD dependency name: raphael

Then in js/activity.js you can use it:

var raphael = require("raphael");

non-AMD libs

Please, refer to
RequiresJS shim section,
then you can add your shim section in js/loader.js

Ready to release

Before your first release, you should:

• make your activity unique in the Sugar interface by changing your
  activity icon activity/activity-icon.svg . Or if you don't have
  graphics skills, you can ask in the community if someone can do it.

After that, if the activity works with Sugar 0.112 or earlier, on
packaged-sugar you may make a bundle and upload it to the Sugar
Activity Library http://activities.sugarlabs.org/.

python setup.py dist_xo

With Sugarizer, you can directly publish the XO bundle. So, just zip the content of your activities/MyActivity.activity directory and rename the .zip file to a .xo file.

For further releases, you should update the activity_version in
activity/activity.info.