How To Write A Widget

Step 1

Download the latest version of WidgetWeb from Download.

Make sure you can run WidgetWeb first. Play around, add a few pages, widgets to pages, etc. Then proceed to the following steps.

Step 2

A widget has three parts - a model, a view, and a descriptor. WidgetWeb currently supports using Groovy to create the model. Other languages may be supported in the future. FreeMarker is the template engine used for the views. Other template engines (including Groovy) will be supported in the future. Descriptors currently are defined using Groovy.

In this example, we'll create a Widget that displays a list of Del.icio.us bookmarks for a user.

In the implementations directory (/WEB-INF/implementations/), create a new folder with your name space and the widget name, e.g. your namespace.mydeliciousbookmarks. This will be our work directory.

Since we don't need any attributes for our view (we're hardcoding that into the view), we don't need to define a model.

Step 3

Next, we'll create the view. In the work directory, create a new file with a ".view.ftl" extension, e.g. MyDeliciousBookmarks.view.ftl. In this example, we'll use the script provided at Delicious Feeds.

Edit this new file and paste in the following:

Feel free to use your own username in the URL above.

Step 4

Next, we'll create the descriptor. This describes the widget including providing categorization on the "Add Widget" page, determining whether or not this widget displays on that page, a description, and a label when viewing the widget.

In the work directory, create a new file with a ".descriptor.groovy" extension, e.g. MyDeliciousBookmarks.descriptor.groovy.

Edit the file and paste in the following:

package your namespace.mydeliciousbookmarks;
 
 import net.firelord.phoenix.component.BaseDescriptor;
 
 /**
  *  Describes the My DeliciousBookmarks widget.
  */
 public class MyDeliciousBookmarksDescriptor extends BaseDescriptor {
 
     // Implements Component.getCategory().
     public String getCategory() {
         return "General";
     }
 
     // Implements Component.getDescription().
     public String getDescription() {
         return "Display bookmarks for a user from del.icio.us.";
     }
 
     // Implements Component.getLabel().
     public String getLabel() {
         return "My Delicious Bookmarks";
     }
 
     // Implements Component.isVisible().
     public boolean isVisible() {
         return true;
     }
 }

Make sure to change the package to your own namespace, e.g. net.firelord -> com.yoururl.

Step 5

Finally, we'll register our new widget with the system. In our work directory, create a file with a ".reg.groovy" extension. This registers the model, the view, the descriptor, and finally an element using these three with the system. An element is a specific type of component which is the "technical" term for Widget. ;-)

Next, edit this file and paste in the following:

package ;

import net.firelord.phoenix.registry.Registrar;
import net.firelord.phoenix.registry.Registry;
import net.firelord.phoenix.registry.RegistryKey;
import net.firelord.phoenix.registry.RegistryUtil;
import net.firelord.phoenix.security.PermissionTypes;

/**
 *  Registers the system components.
 *
 *  Created by nyven on Aug 18, 2005 12:58:01 PM
 */
public class DeliciousBookmarksRegistrar implements Registrar {

// Implements Registrar.register().
public void register(Registry registry, RegistryUtil registryUtil) {

    registryUtil.registerComponentModel("your namespace.MyDeliciousBookmarksModel", "net.firelord.phoenix.component.model.EmptyModel.class")
    registryUtil.registerComponentTemplateView("your namespace.MyDeliciousBookmarksView", "your namespace.mydeliciousbookmarks/MyDeliciousBookmarks.view.ftl")
    registryUtil.registerComponentDescriptor("your namespace.MyDeliciousBookmarksDescriptor", "your namespace.mydeliciousbookmarks/MyDeliciousBookmarks.descriptor.groovy")
    registryUtil.registerElement(
        "your namespace.MyDeliciousBookmarks",
        "your namespace.MyDeliciousBookmarksModel",
        "your namespace.MyDeliciousBookmarksView",
        "your namespace.MyDeliciousBookmarksDescriptor"
    )
}

}

Step 6

Now we're ready to view our widget. Start (restart) WidgetWeb. During launch it searches for ".reg" files and performs the work within the script. If running locally, open a browser window to http://localhost:8004.

Next, double-click the page title, choose "New Widget" from the tabs at the bottom. You should see your newly registered widget under the General category named Delicious Bookmarks. Select it, and save your work.

When the page refreshes, you'll see your bookmarks.