Extending Toaster

In order to promote customizability of Toaster, we have here a set of guidelines on how to add functionality and customize the Toaster web interface.

Django extensibility model

Django, per se, does not offer any extensibility / customization model. Being a framework for hosted application, it is assumed that the host will have complete access for modification. Because Django is not envisioned to be distributed / portable / reusable, there is no need to support insertion of 3rd party content after deployment, or to alter the user flows by 3rd party contributors. However, we can use Django modularization support to add custom extensibility capabilities to our distributable project.

A Django project supports a number of "applications", intended to allow developers to separate different scopes of a web site in different applications. For example, the custom admin interface for a web site should live in a different application than the normal user-facing site.

Toaster consists of a basic set of applications - we have:

• bldviewer - the "simple" web interface, for development purposes only
• toastergui - the Toaster frontend for build inspection
• orm - a separate application just to hold the persistent object models
• bldcontrol - application containing the code to start and control bitbake in managed mode

Features for extensibility

Toaster extensibility model is based on Django. To implement new functionality in Toaster, you have to add a new application containing the code implementing the functionality.

Keeping the code separated in a different application will make for painless code rebases, as your application may live as a separate set of patches based on top of upstream Toaster.

As a web application, the code is driven by HTTP requests. In order to use your handlers, Toaster will automatically redirect requests starting "{modulename}/" to the patterns listed in the "{modulename}/urls.py" file, where "{modulename}" is the name of the application you're creating.

If your {modulename} application contains either views.py or models.py files, it will automatically be added to INSTALLED_APPS list, as to allow database synchronization applications, such as South, to work with your application. This means that you can use fixtures and migration in your application, just like any of the default Toaster applications

In your application you can call any code and use any models from other default Toaster applications.

If your application needs another contributed application, you have to manage any dependencies manually.

How to create a Toaster extension

This is a summary of what you have to do to add new functionality for Toaster:

• create a new application holding that functionality: python manage.py startapp {modulename}
• add in the application directory a urls.py file: {modulename}/urls.py
• start toaster, and verify your pages are accessible with the "/{modulename}/" prefix
• limit all patches touching your application only to your application; this will ease the rebase (see below)
• when updating Toaster, use rebase (as opposed to merge) to move your applications' patches on top of a new Toaster version
• database management functions will be automatically enabled for your applications