URLDispatcher

Differences between revisions 2 and 9 (spanning 7 versions)
⇤ ← Revision 2 as of 2013-09-18 16:58:15 →
Size: 2146
Editor: cpe-76-182-235-222
Comment: Adding links
← Revision 9 as of 2014-03-28 20:26:01 → ⇥
Size: 3406
Editor: cpe-76-187-229-139
Comment:
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
For Qt/QML applications access to the URL Dispatcher is provided through the Qt desktop plugin so the [[http://qt-project.org/doc/qt-5.0/qtgui/qdesktopservices.html#openUrl|openURL()]] function is valid to use and the backend is transparent. For other applications they can use the Platform API or liburl-dispatcher directly depending on their needs. For Qt/QML applications access to the URL Dispatcher is provided through the Qt desktop plugin. C++ applications can use [[http://qt-project.org/doc/qt-5.0/qtgui/qdesktopservices.html#openUrl|QDesktopServices.openURL()]] method. QML applications can use [[http://qt-project.org/doc/qt-5.0/qtqml/qml-qt.html#openUrlExternally-method|Qt.openUrlExternally(string)]] method. Both are valid and the backend is transparent. For other applications they can use the Platform API or liburl-dispatcher directly depending on their needs.

The URL dispatcher project is hosted in [[https://launchpad.net/url-dispatcher|Launchpad]].
Line 15: Line 17:
|| appid://$(pkg)/$(app)/$(version) || Allows for launching an application using an application ID. Also provides for wild cards. The $(app) can be {{{first-listed}}}, {{{last-listed-app}}} or {{{only-listed-app}}} to select the appropriate applicaiton using the click manifest. Also the $(version) can be {{{current-user-version}}} to select the version in the manifest ||
Line 18: Line 21:
Applications will be able to request URLs in the future, but that isn't supported yet. Applications can register to be opened when a URL is activated by adding a URL definition to their Click manifest. For this a small JSON file needs to be added along side the desktop file in the "hooks" section of the file. A simple manifest could look like this:

{{{
{
 "name": "My App",
 "version": "1.2.3",
 "hooks": {
  "foo": {
   "desktop": "foo.desktop",
   "urls": "foo.url-dispatcher"
  }
 }
}
}}}

Which would then point to another JSON file in your click package that defines which URLs you are expecting to recieve. A simple version of that file could look like:

{{{
[
 {
  "protocol": "foo",
  "domain-suffix": "bar.com"
 }
]
}}}

This would mean that the application in "foo.desktop" would be launched anyone someone requested a URL with the pattern "foo://*.bar.com". The {{{domain-suffix}}} field can be left out if you'd like to recieve all requests for a given protocol. The URL dispatcher definition is an array, so as many protocol/suffixes that you wish to recieve for that application may be added.
Line 22: Line 51:
Because the above feature isn't there, we've hardcoded in some URLs that will be useful in the short term. For legacy reasons we've hardcoded some URLs into the dispatcher:
Line 25: Line 54:
|| tel://$(number) || dialer-app || Requests a phone number to be brought up in the dialer. ||
|| music://* file:///home/*/Music/* || music-app || Opens music in the Music player ||
|| http://* https://* || webbrowser-app ||Opens a URL in the webbrowser ||
|| video:// file:///home/*/Videos/* || mediaplayer-app || Opens video content in the media player ||
|| settings://system/$(plugin) || ubuntu-system-settings || Open a specific settings panel in the settings app. ||		 || file:///home/*/Music/* || music-app || Opens music in the Music player ||
|| file:///home/*/Videos/* || mediaplayer-app || Opens video content in the media player ||

Introduction

The URL Dispatcher is a small service that can allow applications that are confined to launch other applications that are identified with a particular URL. Perhaps the most common case would be sending an http:// URL to the web browser, but other applications like music or just starting an application that is in a different sandbox is also supported. For most applications this is a useful way to get out of their application to another piece of content or user request.

For Qt/QML applications access to the URL Dispatcher is provided through the Qt desktop plugin. C++ applications can use QDesktopServices.openURL() method. QML applications can use Qt.openUrlExternally(string) method. Both are valid and the backend is transparent. For other applications they can use the Platform API or liburl-dispatcher directly depending on their needs.

The URL dispatcher project is hosted in Launchpad.

Supported URLs

Base URLS

There are a few URLs that are supported internally in the URL dispatcher.

URL

Description

application:///$(app_id).desktop

The application URL can be used to start an application with a known Application ID. For applications that install their desktop file in /usr/share/applications the application ID should just be the name of the desktop file.

appid://$(pkg)/$(app)/$(version)

Allows for launching an application using an application ID. Also provides for wild cards. The $(app) can be first-listed, last-listed-app or only-listed-app to select the appropriate applicaiton using the click manifest. Also the $(version) can be current-user-version to select the version in the manifest

Application URLs

Applications can register to be opened when a URL is activated by adding a URL definition to their Click manifest. For this a small JSON file needs to be added along side the desktop file in the "hooks" section of the file. A simple manifest could look like this: 

{
        "name": "My App",
        "version": "1.2.3",
        "hooks": {
                "foo": {
                        "desktop": "foo.desktop",
                        "urls": "foo.url-dispatcher"
                }
        }
}

Which would then point to another JSON file in your click package that defines which URLs you are expecting to recieve. A simple version of that file could look like: 

[
        {
                "protocol": "foo",
                "domain-suffix": "bar.com"
        }
]

This would mean that the application in "foo.desktop" would be launched anyone someone requested a URL with the pattern "foo://*.bar.com". The domain-suffix field can be left out if you'd like to recieve all requests for a given protocol. The URL dispatcher definition is an array, so as many protocol/suffixes that you wish to recieve for that application may be added.

Temporarily Hardcoded URLs

For legacy reasons we've hardcoded some URLs into the dispatcher:

URL

App ID

Description

file:///home/*/Music/*

music-app

Opens music in the Music player

file:///home/*/Videos/*

mediaplayer-app

Opens video content in the media player

URLDispatcher (last edited 2015-08-04 15:15:51 by mpt)