Document Contractor [$40]

[danirabbit]

Turns out we have like no docs for this. Should at least include using contractor in your app (to populate a menu for example), but ideally also includes writing contracts for your app.

https://www.bountysource.com/issues/28862098-document-contractor

[ghost]

I'm not sure where to put this right now, but what about this: contractor.txt This is in Markdown format, but the file upload doesn't support the .md extension so i had to rename it to .txt

[lewisgoddard]

Using Contractor

What is Contractor?

Contractor is a service that allows you to use other program's functionalities in your app or expose parts of your app to others. For example, File Manager uses this to do various things to selected files (e.g. Compressing them to an archive, attaching them to an email or setting an image as the desktop background)

Please note: Contracts are not made for simply opening a file in an editor. You should do that in a regular .desktop file. Instead, they provide a shortcut for the user so that he doesn't have to go through loads of screens to achieve what he'd like to do.

Imagine this scenario: The user found a photo he'd like to send to a friend in his files. Traditionally, he would now have to open up his email client, click the "Compose" and "Add attachment" button and finally find the file he just stumbled upon again in a file chooser dialog. Instead, he can just right-click the file in File Manager and choose "send file".

Using other apps' contracts

In our example, let's say we wrote a program that processes images. After it's done with processing, we'd like to let the user choose what to do with the result. He might want to share it with other people via email, set it as a wallpaper, etc. Doing so is as simple as:

var file = GLib.File.new_for_path ("path_to_result.png");

// find all the contracts applicable for this type of file
var contracts = Granite.Services.ContractorProxy.get_contracts_for_file (file);

This creates a list of Granite.Services.Contract 's that come into question for your type of file. Now you can go ahead and look up what each Contract does:

foreach (Granite.Services.Contract contract in contracts) {
// do something to show the contract to the user. In this case, just print its description.
    stdout.printf(contract.get_description() + "\n");
}

Once the user chose one, all you need to do is:

// This is the contract the user chose.
the_contract.execute_with_file (file);

Dead simple, isn't it?

Creating your own contracts

In order to create your own contract, all you need to do is create a contract file. Here's an example:

[Contractor Entry]
Name=my_exec
Icon=my_icon
Description=What your executable does
MimeType=the/mimetype;the/other-mimetype
Exec=my_exec %F

Here's what each variable does in detail:

• Name: The name of your contract
• Icon: The icon name. This should be a name that can be resolved using the current icon theme. Tip: have a look into /usr/share/icons on your machine.
• Description: A description of what this contract does. Might be shown to the user, so use simple language and non-technical terms.
• MimeType: This is a semicolon-separated list of MimeTypes that this contract accepts.
• Exec: This is the commandline that is going to be executed when the contract is launched. %F is then going to be replaced with the filepath your app is supposed to process. You might want to add some kind of flag like --attach-file, or --set-as-default, or whatever your app should be doing with this file.

In the case of our image processing program, this might look something like this:

[Contractor Entry]
Name=Improve Image
Icon=image
Description=Apply filters.
MimeType=image/gif;image/jpeg;image/png
Exec=awesome_image_program --quick-filter %F

Once you're finished, put your file in one of these locations:

• /usr/share/contractor (for programs installed with a package manager)
• /usr/local/share/contractor (for manually installed programs, e.g. using "sudo make install")
• ~/.local/share/contractor (for testing)

And voilà, you're done!

---

# Using Contractor

## What is Contractor?
Contractor is a service that allows you to use other program's functionalities in your app or expose parts of your app to others. For example, File Manager uses this to do various things to selected files (e.g. Compressing them to an archive, attaching them to an email or setting an image as the desktop background)

**Please note:** Contracts are not made for simply opening a file in an editor. You should do that in a regular .desktop file. Instead, they provide a shortcut for the user so that he doesn't have to go through loads of screens to achieve what he'd like to do.

Imagine this scenario: The user found a photo he'd like to send to a friend in his files. Traditionally, he would now have to open up his email client, click the "Compose" and "Add attachment" button and finally find the file he just stumbled upon again in a file chooser dialog. Instead, he can just right-click the file in File Manager and choose "send file".

## Using other apps' contracts

In our example, let's say we wrote a program that processes images. After it's done with processing, we'd like to let the user choose what to do with the result. He might want to share it with other people via email, set it as a wallpaper, etc. Doing so is as simple as:

    var file = GLib.File.new_for_path ("path_to_result.png");

    // find all the contracts applicable for this type of file
    var contracts = Granite.Services.ContractorProxy.get_contracts_for_file (file);

This creates a list of `Granite.Services.Contract` 's that come into question for your type of file. Now you can go ahead and look up what each Contract does:

    foreach (Granite.Services.Contract contract in contracts) {
    // do something to show the contract to the user. In this case, just print its description.
        stdout.printf(contract.get_description() + "\n");
    }

Once the user chose one, all you need to do is:

    // This is the contract the user chose.
    the_contract.execute_with_file (file);

Dead simple, isn't it?

## Creating your own contracts

In order to create your own contract, all you need to do is create a contract file. Here's an example:

    [Contractor Entry]
    Name=my_exec
    Icon=my_icon
    Description=What your executable does
    MimeType=the/mimetype;the/other-mimetype
    Exec=my_exec %F

Here's what each variable does in detail:

* **Name:** The name of your contract
* **Icon:** The icon name. This should be a name that can be resolved using the current icon theme. Tip: have a look into /usr/share/icons on your machine.
* **Description:** A description of what this contract does. Might be shown to the user, so use simple language and non-technical terms.
* **MimeType:** This is a semicolon-separated list of MimeTypes that this contract accepts.
* **Exec:** This is the commandline that is going to be executed when the contract is launched. `%F` is then going to be replaced with the filepath your app is supposed to process. You might want to add some kind of flag like `--attach-file`, or `--set-as-default`, or whatever your app should be doing with this file.

In the case of our image processing program, this might look something like this:

    [Contractor Entry]
    Name=Improve Image
    Icon=image
    Description=Apply filters.
    MimeType=image/gif;image/jpeg;image/png
    Exec=awesome_image_program --quick-filter %F

Once you're finished, put your file in one of these locations:

* `/usr/share/contractor` (for programs installed with a package manager)
* `/usr/local/share/contractor` (for manually installed programs, e.g. using "sudo make install")
* `~/.local/share/contractor` (for testing)

And voilà, you're done!

[danirabbit]

Alright, so this is an interesting start but I don't think it really solves the issue. We don't just want a reference, that's what valadoc is for. We want to provide a full project tutorial with a narrative and ends with a project that fully compiles. It should include instructions for cmake, for example and should include configurating translations and any packaging changes that might need to be made.

[peteruithoven]

Elementary Contractor's readme now also contains some basic documentation on contract files: https://github.com/elementary/contractor I wish I knew about lewisgoddard's comment