Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Purpose: help developers who would like to create a new widget for the mapbuilder library.

Discuss plans with developers

It is best to discuss your planned extensions with Mapbuilder developers before beginning your work. Your ideas may have been discussed or implimented before or someone may have a better idea for implimentation. And you are more likely to get your improvements incorporated into the codebase if they have been discussed beforehand.

Raise issue in JIRA

Create a "New Feature" issue in the JIRA issue tracker. We use JIRA to track what features and bugs have been addressed between releases.

The main index.html file

When creating a new widget it is usually best to start with a working example and extend it. For example, extend the files in mapbuilder/demo/simple/.

In the index.html, you will need to create a HTML tag to insert the new widget into. Eg:

Code Block
<div id="newWidget"/>

config.xml

In config.xml, the widget is associated with it's model and attributes are assigned to the widget. In the example below, NewWidget is attached to the Context model.

Code Block
<models>
  <Context id="mainMap">
    <widgets>
      <MapPane id="mainMapWidget">
      </MapPane>
      <NewWidget id="newWidget">
      </NewWidget>
    </widgets>

NewWidget.xls

Mapbuilder's strength is its ability to build HTML widget snippets from XML documents using XSL, and that is how most widgets work. (See next section if you want to build a pure JS widget).

Your NewWidget.xsl is responsible for converting the model XML to a HTML snippet. The XSL is called by WidgetBase.paint() whenever the model is updated. Do not forget to add new widget texts for your new widget to the widgetText files.

NewWidget.js

For widgets which render using XSL, all that is usually required for NewWidget.js is:

Code Block
function NewWidget(widgetNode, model) {
  var base = new WidgetBase(this, widgetNode, model);
}

However, you can also overwrite prepaint(), postpaint() or register for "refresh", or other events from models to trigger a redraw of the widget.

Also note that for widgets inheriting from WidgetBaseXSL, a prePaint event is fired before calling prepaint(), and a postPaint event after calling postpaint().

Add Translations

Do not forget to add new messages for your new JavaScript object to the widgetText files.

Test

Once you have the code working, test to make sure it works.

  • Test against the trunk version, or nightly release of Mapbuilder. See http://communitymapbuilder.org/display/MAP/Downloads for details on getting the code.
  • Internet Explorer 6
  • Firefox. (At least test with a recent version of Firefox, but it would be better if you could test with 1.0 version as well if you have it handy.)

Update the schema

After you have created a widget, make sure you update mapbuilder/lib/schema/config.xsd with your new widget. The schema is used to build Mapbuilder's Component Register documentation.

Commit Changes

If you have Subversion commit access, then commit the code to subversion.
If not, then attach your updated code to the JIRA issue and an email to the mapbuilder-devel list asking someone to incorporate your changes.