package-plugin
==============
This is a very simple browser plugin that is meant to allow a website
to add a box to allow to install or run a particular piece of software
provided in their distribution's repositories.

If the package is not installed but is available in the package repository, the plugin
will show:

 +------------------------------------+
 | _Install GNU Backgammon Now_       |
 | Version: 20061119-14.fc9           |
 +------------------------------------+

Click on the plugin, and it asks the session service to install the package;
the display changes to:

 +------------------------------------+
 | GNU Backgammon                     |
 | Installing...                      |
 +------------------------------------+

once that is done, the plugin will show:

 +------------------------------------+
 | _Run GNU Backgammon_               |
 | Installed version: 20061119-14.fc9 |
 +------------------------------------+

Clicking on it launches the application.

Security Considerations
=======================

The design as a plugin is specifically meant to avoid revealing information about installed
applications to the web page. None of the information in the plugin is revealed in the DOM
tree. It might be possible to guess at results by subtle timing attacks, but it would at
best be a probabilistic thing.

Web pages probably can trick the user into clicking on the plugin
and installing or running applications they dont' want to install or run:

 - The application title is supplied by the web page
 - The web page could put elements over the plugin to make it appear

(The second is why I consider the first to be acceptable.) However, importantly, the
only applications that could be installed in that way are applications from the package
repository already configured for the system. The only applications that can be run in
this way are applications already on the system. And there is no ability to pass command
line arguments or files to the applications. So, the security risk should be minimal.

Accessibility
=============

The design as a plugin (for the above security considerations) causes some problems for
accessibility. In particular, there is no access into the plugin for screenreaders
or other assistive technologies. Making this work would require the existence of a
system for integrating accessibility support between the browser and plugins, which,
to my knowledge does not exist at the moment.

Keyboard navigation is also missing at the moment, but could be added quite easily.
(Basically, the Return keypress just needs to be treated like clicking on the plugin.)

The fonts, font sizes, and colors used in the plugin come from the system theme, so they
should not pose a problem for users with special needs. (But see discussion of
sizing below.)

Cross Browser Support
=====================

The plugin acts as a standard windowless plugin, so it shouldn't be restricted
to working in Firefox or in Gecko-based browsers.

The plugin does assume that the toolkit hosting the browser is GTK+ for a couple
of things:

 - To get the theme colors and fonts
 - To get a timestamp from the X server if one isn't provided in the button press
   event when launching an app)

These could be fixed if necessary. (Use XSETTINGS directly for fonts and colors,
just skip the timestamp and let the newly launched app get placed in the
background if not running GTK+ and no timestamp is provided.)

More deeply, the plugin requires that the GLib main loop be running, so that
libpackagekit can receive asynchronous notifications from the PackageKit daemon.
So, getting it to work in Konqueror is going to be hard unless Qt has been
compiled to use the GLib main loop.

Trying it out
=============

packagekit-plugin builds with the standard:

 ./autogen.sh
 ./configure
 make

Instead of doing 'make install', you can symlink .libs/packagekit-plugin into
~/.mozilla/plugins. Then you can restart your browser and load the HTML page
under tests/.

If you do this, you probably want to delete the symlink when you are
done so that it doesn't interfere with a system install of the plugin.

Using
=====

Add the following code to your web page:

    <object type="application/x-packagekit-plugin" width="300" height="150">
      <!-- Name that will be used in the user interface -->
      <param name="displayname" value="GNU Backgammon"/>
      <!-- Whitespace separated list of package names -->
      <param name="packagenames" value="gnubg"/>
    </object>

Unfortunately browser plugins have no mechanism for size negotiation, so you
have to specify a predetermined size in some fashion. You can do it with the pixel
sizes as above, or you can do it with CSS using 'em' sizes or percentage
lengths. For example, you could have in your CSS:

      .packagekit-plugin {
         width: 30em;
         height: 5em;
      }

And then add class="packagekit-plugin" to the object tag above.

You should make the size generously bigger than what you need on your system
to deal with translations and with varying font sizes and device resolutions.
Using em sizes rather than points is probably a good idea to help with the
font size issue, but it doesn't completely resolve it since the text of the
plugin will be sized based on the system font size, not on the web pages font.

Customization
=============

The default appearance of the plugin is very plain, with a rectangular outline
and a white background. To customize this appearance, you can add the
optional parameters radius and color to your web page. This will make the
plugin draw a rectangle with rounded corners, and use the given color
instead of white.

    <!-- radius for rounded corners -->
    <param name="radius" value="10"/>
    <!-- background color, must be parsable by pango_color_parse() -->
    <param name="color" value="#aeaeff"/>


Owen Taylor <otaylor@redhat.com>
July 24, 2008

Last updated:

Matthias Clasen <mclasen@redhat.com>
August 21, 2009
