Labs/Jetpack/JEP/21

JEP 21 - jetpack.toolbar

• Champion: David Dahl <ddahl at mozilla dot com>
• Status: Planning
• Type: API Track
• Created: 27 July 2009
• Reference Implementation: jetpack.toolbar
• JEP Index

Introduction and Rationale

The 'toolbar' namespace will provide Jetpack developers the ability to modify toolbars in chrome space in the browser.

Proposal

Create an easy way to get a handle on the navigation toolbar, the bookmarks toolbar. Provide an elegant API to add, modify and remove items for each bar, as well as hiding and showing the toolbars.

// get an abstracted "jetpacky" nav bar object / bookmarks bar object
var navBar = jetpack.toolbar.navigation();

// return the array of 'toolbarbutton' objects
navBar.children();

// remove the 3rd child:
navBar.children()[2].remove();

// get a button labeled 'my button'
var btn = navBar.find({label:"my button"});

// replace the function bound to the button
btn.click = function ClickerFunk(){ alert("I clicked my button");};

// number of toolbar buttons: acts like an array
navBar.length;

// make a button
var button = {
    // 'self' would refer to the button
    // 'self.toolbar' would refer to the parentNode
    id: 73, // or "foobutton"
    label: "my button", 
    imageDefault: "http://mybutton.com/image.png",
    imageAlternate: "http://mybutton.com/imageAlt.png",
    click: function(){self.image(self.imageAlternate);},
    mouseover: function(){jetpack.audio.play(self.customAttribute);},
    customAttribute: "http://mybutton.com/yelling.ogg"
};

// change the image displayed
button.image("http://foobar.com/foopy.png");

// move the button
button.moveRight(); // move to the right 1 slot

button.moveLeft(3); // move to the left 3 slots

// .append() and .prepend():

//append button to the end of the toolbar
navBar.append(button);

// prepend button to the beginning of the toolbar
navBar.prepend(button);

// find a button by label or other string or number attribute
var anotherButton = navBar.find({label:'their button'});

// append button to toolbar after 'anotherButton'
navbar.append(button, anotherButton);

// find and append after the button labeled "their button"
navbar.append(button, 'their button');

// get the bookmarks toolbar
var bookmarksBar = jetpack.toolbar.bookmarks();

//make a bookmark button
var bookmarkButton = {label: "GrouchoMarx.com", 
		      url:"http://grouchomarx.com/",
		      image: "http://groucho.com/image.png",
                      type: 'bookmark' // the default
}

// bookmark and feed buttons use the same methods to attach, move, find vis a vis the toolbar 

var feedButton = { label: "my RSS feed",
		   image: "http://myfeed.com/feed.png",
		   url: "http://www.rssfeed.com/rss.xml",
		   type: "feed"
};

// make an entirely new toolbar
var newToolbar = { id: 'myGreatAppToolbar'};

// append it to the toolbar box
jetpack.toolbar.append(newToolbar);

jetpack.toolbar.prepend(newToolbar);

Initial Implementation API

For the initial implementation, the api will be restricted to:

jetpack.future.import("toolbar");

// Create button options. This can be done in a separate object like this,
// or passed inline to append.
var myButton = {
  id: "fooButton",
  label: "FOO!",
  tooltip: "Click on my to do something.",
  image: "http://www.mozilla.org/favicon.ico",
  click: function(event) { console.log("FOO! has been clicked") }
}

// Append the button to the toolbar
jetpack.toolbar.navigation.append(myButton);

// Remove the button from the toolbar
jetpack.toolbar.navigation.remove("fooButton");


// Create button options for the bookmarks toolbar.
var myOtherButton = {
  id: "barButton",
  label: "BAR!",
  tooltip: "Go to http://www.mozilla.org",
  image: "http://www.mozilla.org/favicon.ico",
  url: "http://www.mozilla.org"
}

// Append the button to the toolbar
jetpack.toolbar.bookmarks.append(myOtherButton);

// Remove the button from the toolbar
jetpack.toolbar.bookmarks.remove("barButton");