Projects/Silk/Selkie

Selkie - Standalone Web Application

What is Selkie?

Selkie is a standalone web application shell. With Selkie, you can use Web Applications as first-class citizens on your desktop. Selkie WebApps appear as full applications in your desktop. Entries of these web applications are added to the start menu, then can be found in KRunner on the KDE desktop, they appear as their own entry in the taskbar and window-switching machinery.

Selkie allows you to create customized web application. You can add actions to Selkie applications that can be triggered from the toolbar, or on loading webpages. With these actions, you can "inject" Javascript and run them in the context of the website. This allows you to manipulate the contents and behavior of your web application at runtime. Selkie plugins do not contain any "compiled" or native code. The plugins are simple .desktop files that contain the information about a specific webapp. Likewise, actions are .desktop Files as well. They either contain a JavaScript one-liner or point to a Javascript file which is then executed "inside" your web application. From these scripts, you can also access functions Silk offers you, such as triggering notifications on the desktop, or logging to the console.

Selkie is built using WebKit and makes use of KDE's plugin system and Toolbar / Action system. Selkie can load and execute greasemonkey scripts as well, so there are literally hundreds of actions available.

How does Selkie work?

Selkie has four main components. Selkie itself is the application that can run a number of web applications ("WebApps"). Those WebApps are plugins that can be loaded into Silk. The WebApp plugins contain meta information about the web application (icon, name, comment, plugin name). The plugins also contain information about the WebApp itself, such as at which page to start, or which URLs should be opened in the WebApp itself. This allows for sand-boxing the web application and opening external URLs in the default web browser.

Where is the code?

Selkie is developed inside the Project Silk git repository on Gitorious.org. You need a recent Qt (>=4.5) and KDE development tools and headers installed (4.3.x should do).

• [Silk on Gitorious]

Is it stable?

Not at all. It eats kittens and babies. Selkie is not feature-complete, nor widely tested either, it is in a proof-of-concept stage. The code is currently in a "proof-of-concept" stage, but not feature-complete. You can already create WebApps and actions for them, filtering based on URLs and wildcards has been implemented.

Creating Web Applications

Creating WebApps by adapting the .desktop files by hand is possible, an editor for WebApps is in its very early beginnings.

Setting up the Selkie Web Application

WebApps consist of configuration settings and Actions. The settings for a webapp are read from a .desktop file.

Usually, a webapp will create on, two or more desktop files:

• A .desktop file to launch the webapplication, for example from the Menu and from Krunner:
  • Needs to be of type Application
  • Should have the webapps Name, GenericName and Comment
  • An Icon for the webapp

A file could look like this:

[Desktop Entry]
Name=ReviewBoard
GenericName=KDE's ReviewBoard
Comment=KDE's ReviewBoard Instance
Exec=selkie reviewboard
Icon=kstars
Type=Application

• A .desktop file describing the plugin, holding site-specific settings:
  • Has to be of Type=Service
  • startUrl, AllowedBases
  • KPluginInfo metadata, most importantly: X-KDE-PluginInfo-Name, which is used as parameter to selkie
  • config options, starting with: X-Silk- (These config options are defined in services/silk-webapp.desktop, which is the ServiceType for Silk/Webapp

The plugin .desktop file typically looks like:

[Desktop Entry]
Name=Review Board
Comment=KDE's ReviewBoard Instance
Icon=kstars
Type=Service

X-KDE-ServiceTypes=Silk/WebApp

X-KDE-PluginInfo-Author=Sebastian Kügler
[email protected]
X-KDE-PluginInfo-Name=reviewboard
X-KDE-PluginInfo-Version=0.01
X-KDE-PluginInfo-Website=http://kde.org/
X-KDE-PluginInfo-Category=Development
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true

X-Silk-StartUrl=http://reviewboard.kde.org/r/
X-Silk-AllowedBases=http://reviewboard.kde.org/

The StartUrl is the initial URL to show when the application starts. All activated links (through clicks, or redirects) that have their basePath in X-Silk-AllowedBases. This option can contain a list of URLs, separated by "," (a comma). For some sites, adding the address as https:// makes sense as well, possibly also other subdomains.

Defining Actions

Actions apply to a specific site, and within this site to a URL. Actions can be shown for some URLs and hidden for others. An action can be triggered by the user, and will execute a piece of JavaScript in the website's context. This way, you can "inject" JavaScript into the running website, for example to hide certain elements or trigger functions. to invoke an action in the website's own JavaScript API.

The webapplication, after starting the service-specific plugin, scans for plugins of the type Silk/WebApp/Action, and creates Actions from the .desktop files. An action plugin can provide a JavaScript one-liner to run (window.location = 'http://that.domain/some_page' to jump to a location). It's also possible to provide a JavaScript file for more complex things. An example for this is the togglesidebar.js script in the silk service directory.

[Desktop Entry]
Comment=Toggle the Chrome in Gitorious Interface
Icon=view-sidetree
Name=Toggle Chrome
Type=Service

X-KDE-PluginInfo-Name=silk-commitlog
X-KDE-ServiceTypes=Silk/WebApp/Action

X-Silk-ScriptFile=togglesidebar.js
X-Silk-ShowOnUrl=http://gitorious.org/
X-Silk-TriggerOnUrl=http://gitorious.org/
X-Silk-WebApp=silk

The KPluginInfo entries are needed to identify the plugin from there on (X-KDE-PluginInfo-Name), and to retrieve this action (X-KDE-ServiceTypes). Not setting the ServiceType of your plugin correctly means that the plugin won't be found.

Actions in a nutshell:

• • You need one silk-webapp-myplugin-myaction.desktop file per action, containing name, icon and options for triggering and enabling the action
  • Possibly a script if you're using the X-Silk-ScriptFile option
  • or a one-line in the form of

    X-Silk-Script=window.location = 'http://mail.google.com/mail/?view=cm&fs=1&tf=1'

    (if both options are given, the one-liner will be preferred, the file will be ignored). Note: this should be changed to run the one-liner after the script has been included.
  • every files needs to be installed via CMakeLists.txt

Installation of WebApps and Actions

In CMakeLists.txt, you need to add the .desktop files.

install( FILES selkie-test.desktop DESTINATION ${XDG_APPS_INSTALL_DIR} )
install( FILES silk-webapp-test.desktop DESTINATION ${SERVICES_INSTALL_DIR})

install( FILES silk-webapp-test-toolbar.desktop DESTINATION ${SERVICES_INSTALL_DIR})
install(FILES toolbaraction.js DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/)

install( FILES silk-webapp-test-trigger.desktop DESTINATION ${SERVICES_INSTALL_DIR})
install(FILES triggeraction.js DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/)

install( FILES silk-webapp-test-wildcard.desktop DESTINATION ${SERVICES_INSTALL_DIR})

An action will have 1 entry for the desktop file, and one optionally for a .js file, if you're using the ScriptFile option. Make sure you install the .desktop files into their respective locations: the apps directory for the launcher, the service directory for your site plugin, and your additional files into the data install dir. Every plugin should install into a subdirectory called /silk-webapp/myplugin -- if you don't install it there, it won't be found by the application. Also, after changing an installed .desktop file, you'll usually want to run 'kbuildsycoca4' to refresh the cached services, often your changes won't have effect immediately if you don't refresh the database.

Creating Local WebApps

You can also create local applications with Silk, by just providing a bunch of HTML files, image data and a start location. For pure client side apps, this can be enough to create simply local standalone webapps. Install these files like this:

# Install the test sites files
install(FILES testsite/mountain.html DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/testsite/)
install(FILES testsite/selkie.html DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/testsite/)
install(FILES testsite/beach.html DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/testsite/)
install(FILES testsite/default.css DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/testsite/)
install(FILES testsite/randa-view.jpg DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/testsite/)
install(FILES testsite/recife.jpg DESTINATION ${DATA_INSTALL_DIR}/silk-webapp/test/testsite/)

The start, and action urls can be speficifed by relative paths, i.e. in the below case silk-webapp-testsite.desktop

X-Silk-StartUrl=testsite/selkie.html
X-Silk-AllowedBases=testsite/

In the Selkie service directory, you can find more examples how to build custom web applications. Have a look at "selkie test" for a demo.

Status / TODO

• loading plugins as actions works for simple cases
• loading javascript files from plugins works
• showing and hiding action button (parenturls + wildcards matching, works)
• triggering (parenturls and wildcards work)
• actions should have a "persistant" flag to execute them on every new page load, within a context
• some way of automating the creation of those things (apps + actions) (webappeditor, in progress)