elementary / contractor

A desktop-wide extension service used by elementary OS

Contractor

Building, Testing, and Installation

You'll need the following dependencies:

• libdbus-1-dev
• libgee-0.8-dev
• libglib2.0-dev
• meson
• valac

Run meson to configure the build environment and then ninja to build

meson build --prefix=/usr
cd build
ninja

To install, use ninja install

sudo ninja install

Writing Contract Files

elementary Files, Photos and other apps support adding options to the context menu by the way of Contract files.

These Contract files can be made system wide available by adding them to: /usr/share/contractor or for specific users by adding them to: ~/.local/share/contractor

Simple .contract file example:

[Contractor Entry]
Name=Mount
MimeType=application/x-cd-image;application/x-raw-disk-image
Exec=gnome-disk-image-mounter %f

• Name: Text displayed in the right click context menu.
• MimeType: Mimetype(s) of files it should be shown for.
• Exec: Command to execute. More info.

Tips:

• Use pkexec to ask for root permissions. Example: Exec=pkexec chmod +x %U

Examples

• Send by Email
• Print
• Send files via Bluetooth
• Compress
• Extract Here
• Write onto removable device
• QR Share
• Wallpaperize
• Show checksum
• GPG Encrypt/Decrypt

contractor's Issues

documentation anywhere??

Is there any documentation anywhere about the api exposed by this service?

the existing entry in the 'human interface guidelines is all I found but It is very unhelpful.

for the curious:

Contractor

Contractor is a service and a protocol for exposing services easily between apps. It lets apps interact with other apps and services without hardcoded support for them. You simply add Contractor support, and then any service registered with Contractor is now available for your app to use. Your app can integrate with Contractor in two different ways:

Register one of its functions as a service that can be used from other apps
Implement the contractor menu or otherwise access contractor to receive a list of services that can handle the data your app manages
Displaying Results from Contractor

Contractor results are typically presented to users in menu form. Keep the following in mind when presenting Contractor results:

If the item acted upon is one of many items visible, such as in an icon view, be sure to display results in a way that is directly related to the item such as in a context menu.
If the item acted upon is the only item currently visible, such as a web page or a contact in Dexter, contractor can be displayed in a toolbar menu.
Never display the target app's name. The menu string is the intended display name for that app. Doing so can lead to redundant messages such as, "Set image as wallpaper (wallpaper)" and it is always irrelevant to a user's needs.

filter functions based on file size

Some contracts may need to place a restriction on file size due to the services they work with, for example there is a maximum upload size for Facebook and you can't send a 3GB movie through gmail.

In this way, an application needs to be able to tell Contractor how large the target item is so that Contractor can either filter out or make insensitive services that can't take large files.

Launchpad Details: #LP782759 Daniel Fore - 2011-05-14 18:37:28 +0000

How to debug?

I'm struggling with writing a image resize contract for Files. One of the biggest issues is that I don't know how to debug my .contract scripts.
Is there anyway to get the result / output of the Exec parameter?

Contractor doesn't allow disabling system-wide contracts

There are mechanisms to add or change, but not disable/remove system-wide contracts per-user. Some people (e.g. me) will never use e.g. Facebook and Twitter contracts and prefer to disable them.

This bug causes ugly workarounds in webcontracts.

Launchpad Details: #LP1026280 Sergey "Shnatsel" Davidoff - 2012-07-18 18:43:06 +0000

meson regression: contract directory no longer installed

The meson equivalent of install (DIRECTORY DESTINATION ${CMAKE_INSTALL_FULL_DATAROOTDIR}/contractor) is missing - so the contracts directory is no longer created upon installation.

Doesn't support actions exposed via D-bus

Contractor doesn't support calling actions via D-bus as opposed to command-line arguments. D-bus is the GNOME and KDE standard, and arguably a much better way to implement such things.

For example, Empathy seems to use D-bus calls for file transfer.

ProblemType: Bug
DistroRelease: Ubuntu 12.04
Package: contractor 0.2-0r26+pkg4precise1 [origin: LP-PPA-elementary-os-daily]
ProcVersionSignature: Ubuntu 3.2.0-30.48-generic 3.2.27
Uname: Linux 3.2.0-30-generic x86_64
ApportVersion: 2.0.1-0ubuntu13
Architecture: amd64
CrashDB: contractor
Date: Sun Sep 23 13:50:28 2012
InstallationMedia: Ubuntu 12.04 LTS "Precise Pangolin" - Alpha amd64 (20120303)
ProcEnviron:
TERM=xterm
PATH=(custom, no user)
LANG=ru_RU.UTF-8
SHELL=/usr/bin/fish
SourcePackage: contractor
UpgradeStatus: No upgrade log present (probably fresh install)

Launchpad Details: #LP1054925 Sergey "Shnatsel" Davidoff - 2012-09-23 10:21:57 +0000

Put all contracts in a single repository

Is it possible to put all contracts from the examples in a single repo? It would help with third party packaging like for Arch Linux.

Send files via Bluetooth option present when no bluetooth

In the context menu, there is a option to "send files via bluetooth" even when no bluetooth adapter is present.

Launchpad Details: #LP1183552 mrphd - 2013-05-23 20:30:33 +0000

Contractor is GIGO

Passing invalid URIs, e.g. file paths that are not URI-encoded and/or not prepended with file://, prints no errors but produces invalid results:

• In single-uri (%u) contracts every second parameter isn't passed to client.
• In file contracts (%f and %F) the parameters are not passed to clients at all.

This is the behavior of http://www.valadoc.org/#!api=gio-2.0/GLib.AppInfo.launch_uris and Contractor does not perform validity checks before passing parameters to it.

Launchpad Details: #LP1165481 Sergey "Shnatsel" Davidoff - 2013-04-06 18:00:34 +0000

Doesn't provide a way to conditionally show contracts or make them sensitive

Contractor doesn’t provide a way to conditionally show contractos or make the actions sensitive. For example, “Send via Bluetooth” should be shown only when a Bluetooth adapter is present, and keeping contracts that require Internet connection sensitive while offline makes no sense.

Launchpad Details: #LP1073371 Sergey "Shnatsel" Davidoff - 2012-10-30 23:33:52 +0000

Migrate to Meson

Support TryExec key like in .desktop files

Contractor should support a TryExec key like in .desktop files, see http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s05.html

This is an extension of bug 912413 required for properly handling contracts that use an wrapper over the actual provider - which will happen very often, as far as I can tell.

Launchpad Details: #LP1171835 Sergey "Shnatsel" Davidoff - 2013-04-23 12:10:34 +0000

Support text buffers like plain text selection or URL

Contractor should support manipulating not only files but also text buffers passed to it. Contractor core is able to handle that. We still need to:
 1) Establish .contract keys for passing a data stream instead of file names
 2) Adjust contracts accordingly

Launchpad Details: #LP1025341 Sergey "Shnatsel" Davidoff - 2012-07-16 16:04:44 +0000

man page is in packaging instead of main source code

I write man pages for all the stuff I package for Debian. Since I do not know how to properly add them to the main source tree (because of CMake) I have included them in the .deb packaging instead.

Restricting man page availability to Debian-derived distros is obviously not a good idea, so they'll have to be moved to the main source tree eventually, complete with the relevant CMake changes.

Launchpad Details: #LP1333887 Sergey "Shnatsel" Davidoff - 2014-06-24 18:47:34 +0000

Is there a proper way to translate contract files?

I'm currently working on the translation of an app and I'm getting trouble translating the contract file. Is there a proper way to do it?

First I used to rename the file rddn.contract.in and use meson to rename it properly like we do for the desktop file. But when I try to generate the translation template using ninja it complains that the .contract file extension has not been recognized and it's content is not being added the template.

Then, I noticed that the file structure was the same than desktop fiiles so I found a parade by naming the file rddn.contract.desktop.in which seems to work becauses xgettext read the file the same way than a classic desktop file. But it's a bit tricky.

What do you think? Any help would be appreciated.

Document how to provide contracts from flatpak apps

Problem

With the move to Flatpak current approaches of providing contracts no longer work.

Proposal

Document how to provide contracts from apps distributed through Flatpak.

Relevant: elementary/hig#33

@Marukesu mentioned:

Well, they can, they only need to add --talk-name=org.elementary.Contractor to finish args.
We can also add a portal to copy the sandboxed contract to the host path so they can be used on others apps.

Discriminate between single file and multi-file actions [$50]

For example we have a contract "Set as Desktop Background" that only makes sense for just 1 file and a contract "Set as Desktop Slideshow" that makes sense only for >1 file.

Launchpad Details: #LP1357990 Daniel Fore - 2014-08-17 18:00:25 +0000

wrong RDNN for dbus service

The dbus service file is still named org.elementary.contractor.service, everything is being moved to io.elementary.* namespace.