Widget Development Guide
NTW widgets are nothing more than Chrome extensions that communicate with the main NTW extension. If you already know how to write Chrome extensions, this will be very easy to pick up. If you do not, please head over to the Google Chrome Extensions page for the documentation.
To see how simple it is to create widgets for NTW, check out the source of a couple of existing ones:
Widgets are little more than a page loaded into an iframe. The Custom Site 1 widget allows users to load any website into the widget frame. A modification of this widget, the Toodledo Widget, is a simplified version that loads a predefined webpage.
At a minimum, a widget requires the following files: (Using the Toodledo Widget as an example)
- manifest.json - The manifest file is required by Chrome. Please refer to the Google Chrome Extensions page for more details. You must have a background page, by default
background.html. (keep reading) - NTW.js - This file allows widgets to communicate with NTW.
- background.html - Runs in the background. This file contains information about the extension (similar to
manifest.json) and communicates with NTW. You may have any other code you want running in the background in this file as well. - widget.html - The page that will be loaded into the widget frame on the new tab page. This is what the user will see.
Below is a line-by-line explanation of the important files.
NTW.js
var NTWID = 'kglfkhnhcnemodbfakimgonfkbpmlpfd';
The first line defines the ID of the NTW extension. Widgets use this ID to communicate with the main extension. This should not be changed.
function registerWidget(info) {
chrome.extension.onRequestExternal.addListener(function(request, sender, sendResponse) {
var parts = request.split('-');
if(parts[0] == 'NewTabWidgets') {
info['head'] = request + "back";
chrome.extension.sendRequest(sender.id, info);
}
});
}
Widgets communicate with NTW by listening for an external request and sending one back with some data. The first block of code in NTW.js handles this communication. The info array will be discussed in the section for background.html.
function setTitle(title) {
var data = {
head: 'NewTabWidgets-setTitle',
content: title
}
chrome.extension.sendRequest(NTWID, data);
}
Widgets can change the title of the widget frame on the new tab during run-time by calling this method. It accepts a string and does not return anything.
function setHeight(height) {
var data = {
head: 'NewTabWidgets-setHeight',
content: height
}
chrome.extension.sendRequest(NTWID, data);
}
The setHeight method allows widgets to change the widget frame's height during run-time. The method accepts an integer greater than 0. The actual height is calculated from this number so that widgets can line up nicely on the new tab page.
Widget Height Actual Height (px)
------------- ------------------
1 100
2 237
3 374
The height can be extended above 3, but this is not advised.
background.html
Download background.html (The page will be blank, do a Save As)
The background.html page allows your widget to register with NTW. Below is a detailed description of the source code.
<script type="text/javascript" src="NTW.js"></script>
<script>
var info = {
type: 'widget',
name: 'Notes',
description: 'Notes widget',
icon: '128.png',
height: '2',
options: 'options.html'
};
registerWidget(info);
</script>
type - Currently only two types of widgets are supported: widget and wallpack.
name - The name of the widget that will be displayed in the options page and the widget frame on the new tab page.
description - The description of the widget will be displayed on the options page.
icon - An icon for the widget on the options page. This can be different from the extension icon for Chrome's manifest.
height - The height of the widget frame. See setHeight above for details.
options - An optional options page for the widget.
Back to New Tab Widgets.