Creating a Simple App / Widget

Apps or widgets are features that the user may add to the toolbar at any time. An app may be a button, a menu, or actually any combination of features.

Their most distinctive trait is that they can be dragged from a page on the Web and dropped into the toolbar, which will install the app or widget code and resource files. They will become part of the toolbar until the user decides to remove the app.

This tutorial will take you through the process of creating a very simple app: the Hello World App. But before getting into the actual app, it will help to understand how apps are installed and how they load.

App or widget installation happens in several phases.

First, the user visits a page that contains an app reference, most likely an app icon on the page. This icon is actually an HTML image. The image tag should be surrounded by an anchor tag that points to the URL for the app's manifest. The App Manifest is an XML file that describes the app.

The user may decide to install the app. The user will do it by dragging the app's icon into the toolbar. When the icon is dropped, the toolbar retrieves the App Manifest file and looks at the properties specified there.

One of the properties in the manifest tells the toolbar the URL from where it should get the actual app code. This URL must be in one of the hosts the toolbar trusts for apps. If the host is trusted, the toolbar downloads the app and locates the App Constructor file within the contents of the app code.

The App Constructor file is a text file containing a series of JavaScript statements that will create an instance of the app. Upon installation, the toolbar will load the contents of the file and evaluate the JavaScript statements. Those statements may be creating the different objects that comprise the app. After that, every time the toolbar loads, the app constructor will be called again.

Inside the DTX framework, the contents of the app constructor file are used as the body of an anonymous constructor function. This constructor is used to instantiate one single object, which is anonymous too.

A DTX App requires at least three files:

The Widget Manifest;
The Widget Constructor; and
The Widget Icon.

The first step for the Hello World app would be to write it's Manifest XML. Open your favorite XML editor and paste the following:

<?xml version="1.0" encoding="utf-8" ?>
<widget
id="com.mydomain.mywidgets.hello"
name="Hello World"
codebase="http://widgets.mydomains.com/hello/hello.js"
icon="http://widgets.mydomains.com/hello/widgets_hello.gif"
type="text/javascript">
<version number="1" update="1440" />
</widget>

Save the file as “manifest.xml”. The following paragraphs provide a quick explanation of what each attribute will do.

The “ID” attribute is a unique identifier for the widget. It is a good idea to name it after the domain name of the widget maker. This is an easy way to make sure the ID will be unique. Widgets are stored in the user data folder inside a folder named “widgets\<WIDGET_ID>”, so this ID will be used for the folder name as well. In this case, the relative path would be “widgets\com.mydomain.mywidgets.hello\”.

The “name” attribute contains the name for the widget. The widget will appear under this title in the Manage Widgets menu. Look at the <widgetmenupopup> tag for more information.

The “codebase” attribute contains the URL for the actual code of the widget. This URL must be in one of the hosts the toolbar trusts for widgets. The list of allowed hosts is specified by the toolbar maker. It may be defined in the “widgetallow” attribute for the toolbar, for instance:

This toolbar will allow widgets from three different hosts:

widgets.vmn.net;
widgets.mydomain.com; and
widgets.yourdomain.com.

The “icon” attribute in the manifest points to the location of the icon for the widget. The icon may be a PNG or GIF image, preferably 46x46 pixels.
The “type” attribute refers to the MIME type of the resource to which the “codebase” URL points. Only two values are currently supported:

“text/javascript” - In this case the “codebase” URL points to the Widget Constructor file.
“application/zip” - A ZIP file that contains the widget files. The ZIP may contain sub-folders. The toolbar will look for a file named “widget.js” and will use it for the Widget Constructor.

The <version> node contains information the toolbar will use to perform silent updates for the widget. It's “version” attribute states the current version for the widget. This is an integer value. Another attribute, “update”, specifies the frequency in minutes the toolbar will look for updates for this widget.

The next step would be to create the Widget Constructor file. Create an empty JavaScript file and input the following lines:

var button = framework.createElement("toolbarbutton");
button.setAttribute("label", "Hello!");
button.setAttribute("image", "http://widgets.mydomain.com/hello/happy.png");
button.addEventListener("command",
function() {
framework.alert("Hello World!");
});

framework.mainContainer.appendChild(button);

Save the file as “hello.js”. This code is all you need to have a button added to the toolbar that shows a “Hello World!” Message Box when pressed. Let's look at each line in more detail.

var button = framework.createElement("toolbarbutton");

The above line will create a new toolbar button. Note that the “framework” variable is visible to the widget constructor code and points to the actual DTX Framework interface for the toolbar. Through this interface the widget can extend the toolbar just like any other native feature.

The “button” variable will remain hidden within the widget's instance, so it will not be accessible to objects other than the widget instance.

button.setAttribute("label", "Hello!");
button.setAttribute("image", "http://widgets.mydomain.com/hello/happy.png");

The two lines above set, repectively, the label and image attributes for the button. Note that the image points to a live icon in an HTTP server. For widgets expected to have a wide distribution, it would be better to point to an image in the toolbar's chrome space as shown below:

button.setAttribute("image",
framework.makeWidgetChromeUrl("com.mydomain.mywidgets.hello/happy.png"));

The “content/widgets” part in the URL section is mandatory since this is the space where all widgets are placed within the chrome. The widget's ID must be appended to that as well. This approach would also require to use the “application/zip” type for the widget and package it into a ZIP file that would include the widget constructor named as “widget.js” and the “hello.png” icon. For a test widget, a live HTTP URL will do fine for the button's image.

button.addEventListener("command",
function() {
framework.alert("Hello World!");
});

The above lines register an event handler for the button. When the button is pressed, the provided function will be called. In this case the function only displays an alert box.

And then add the following line:

framework.mainContainer.appendChild(button);

This appends the new button to the toolbar, which is the “mainContainer” element for the current framework.

The next step in the widget creation would be to upload these files into an HTTP server, including the widget icon. The URLs specified in the widget's manifest and constructor should be valid.

The last step would be to create a reference to the widget in a web page, so the user can drag and drop the widget into a toolbar. The way to do this is to use an <img> tag in the page. Around this <img> tag you should place an anchor tag <a> having it's “href” attribute point to the widget manifest. A special marker needs to be included in this URL so the toolbar knows it is for an widget manifest. These HTML tags would be something like the following:

<a
href="http://dtx_widget$widgets.mydomain.com/hello/manifest.xml$"
onclick="alert('Please use Drag&Drop to install widget'); return false;">

<img src="http://widgets.mydomain.com/hello/happy.png" border="0" />
</a>

Note that the actual URL for the manifest is contained within the “$” markers in the “href” attribute. In this case the widget manifest would be retrieved from "widgets.mydomain.com/hello/manifest.xml".

Now you are ready to test the new app. Just make sure the host in your “widgetallow” toolbar attribute includes the host for the “codebase” URL you specified in the manifest. Once your toolbar is set to accept apps, it helps to add a <widgetmenupopup> somewhere in the interface since it is the only way a user can remove an app.

Dynamic Toolbar

Creating a Simple App / Widget

Newsletter Sign Up