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.
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
Choose a name for your activity. Write it in the activity name and
activity/activity.info of the new directory.
And also in the title tag of
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.
Now you should have a basic activity running!
In your new activity, you will find the following file structure:
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
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.
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:
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
Create a directory
icons/ inside your activity and place the SVG
file inside. Then do the following steps.
index.html, add a new <button> element inside the toolbar:
css/activity.css, define the button style:
js/activity.js, add a callback for the button:
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.
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:
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
If you want to inspect the code, you can press ctrl+shift+I while your Activity is running.
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:
You can easily add AMD-ready libraries with volo. For example, to add RaphaelJS:
js/activity.js you can use it:
Please, refer to
RequiresJS shim section,
then you can add your shim section in
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
For further releases, you should update the activity_version in