Write your own Sugar web activity

Choose your development environment

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

sugar-build is a Sugar desktop build environment. With sugar-build you've got a full Sugar desktop environment. It's a good choice if you've enough knowledge to build your environment on GNU Linux.

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 sugar-build, after you have built the development environment, enter the shell

Create an activity based on the default template

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.

activity.info

And also in the title tag of index.html.

index.html

On sugar-build, install the activity for development

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.

Sugarizer settings

Now you should have a basic activity running!

Activity template

File structure

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

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

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:

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:

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:

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

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 using a mix of them, so 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:

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

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:

Import mustache in your js/activity.js:

Use it:

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.

Activity inspector

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 (on sugar-build only) with running the following command inside the activity directory:

Using other JavaScript libraries

AMD-ready

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

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

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:

After that, on sugar-build you can make an XO bundle and upload it to the Sugar Activity Library http://activities.sugarlabs.org/ (ASLO).

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.