How to Integrate Your Website with Ubuntu Unity WebApps

When I decided to add Ubuntu WebApp support to FeedsAnywhere I found a surprising lack of available reference material online. The API links that were included on most sites went to either dead links or links that were about building an installable component to manage the app. However, I was looking for something simple that could be done completely using Javascript within the website itself. After much searching I finally found an old reference here. Even though it is for the 12.10 release it works in 13.04 too. I haven't tested with 13.10 yet.

Setup

The first step is creating a function that sets up the Unity object and basics like address and icon. I added some error detection to the process to avoid failures when a non-compatible browser is used and the full code is included below. The Unity.init function below is what adds the icon to Dash and the Launcher and tells the system what homepage to navigate to when clicked.

// ==UserScript==
// @name feedsanywhere-unity-integration
// @include http://*.feedsanywhere.com/*
// @include http://feedsanywhere.com/*
// @require utils.js
// ==/UserScript==

unityActive=1;
try {
  window.Unity = external.getUnityObject(1);
} catch (e) {
  unityActive=0;
}

if (unityActive == 1) {
  Unity.init({name: "FeedsAnywhere",
    domain: "feedsanywhere.com",
    homepage: "http://feedsanywhere.com/",
    iconUrl: "http://feedsanywhere.com/images/home_icon.png",
    onInit: unityWebApp
  });
}

Initialization

Near the end of the setup you'll notice a line with onInit referencing the unityWebApp object. unityWebApp is a function you will define that will run code right away. FeedsAnywhere uses this function to add entries to the Launcher and HUD. Other code, like updating unread counts, can be run at later times within the rest of your code.

Launcher Actions

Since the Unity.init function defined what to do when selecting the icon in the Launcher, an action is adding another target to the right-click menu. The code below is for the Show Interesting action in FeedsAnywhere. Simply change Show Interesting to whatever you want as the text and adjust the location.href to the destined address.

Unity.Launcher.addAction("Show Interesting", function() { document.location.href="/feed/interesting"; });

Launcher Unread Counts

Unread counts can be added to the Launcher icon as well. A good example of this behavior is the system update program showing how many new packages are available. In the example below, num_unread is a variable containing the number you want to display. Please note that using a string will not work. It must be a number. That is why the variable is enclosed with Number() to make sure a string isn't inadvertently passed.

The second line in the code removes the bubble with the count completely. This necessary because setting the count to 0 will display a 0, however with FeedsAnywhere I chose to remove the count when there are no unread items or when there is a 1000+ unread count.

Unity.Launcher.setCount(Number(num_unread));
Unity.Launcher.clearCount();

HUD

HUD actions are very similar to Launcher actions and should also be defined in the function call by onInit.

Unity.addAction("/Show Interesting", function() { document.location.href="/feed/interesting"; });

Indicator

With FeedsAnywhere I chose to avoid using the indicator menus because unread counts in a news reader can get very large and because updates to the count are only happening when you are actively using FeedsAnywhere and not in the background. That said, I did experiment them and for completeness, here is the implementation code.

Unity.MessagingIndicator.showIndicator("Interesting", {
  count: 0,
  callback: function() { document.location.href="/feed/interesting"; }
});

Indicators should be set up in onInit, however count may often need to be updated elsewhere in the code if it is to be kept accurate without requiring a page load.

Navigation

j/k selects the next/previous item in the list
n/p in title view, selects the next item without opening it
space/shift+space moves to the next/previous page
shift+m open/close the main menu
shift+o open/close the options menu
enter select the highlight entry from a menu

Actions

enter,o in title view, expands or collapses the selected item
shift+a marks all items in the current page as read
d go to the item's list of similar stories
i/u designate the item as interesting/not interesting
m marks the item as read or unread
s adds or removes a star from the selected item
shift+s open/close the item's share menu
shift+u marks all items in the current page as unread
v opens the original source for the item in a new tab

Go To a New Page

g then h go to the homepage
g then i go to the Interesting items view
g then a go to the All items view
g then s go to the Saved items view
g then p go to the Popular items view
g then f go to the Select a Feed page

Application

- decrease the font size
= increase the font size
esc close any menu if open, otherwise deselect all items
? open/close a decription of keyboard shortcuts