Template for new Gnome-do plugin
Andy
I am wanting to write a simple plugin (to resolve doi [http://
www.doi.org/]) - I have search the list for help and there were some
out of date links which didn't work
Can people recommend a good plugin to copy and/or upto date
documentation
Andy
Christopher James Halse Rogers
I'm not sure that we've ever really had particularly good developer
documentation, let alone up to date documentation :).
That said, the plugin API is actually pretty simple.
A good plugin to look at would be the TinyUrl plugin, which does a very
similar job (take some text, run it through a web service, return a
URL).
There are two things which plugins can provide: either raw Actions (such
as TinyURL or your DOI resolver) or a full ItemSource (such as Files and
Folders).
Both ItemSources and Actions are subclasses of Item; as such, they've
all got Name, Description and Icon properties. These are pretty much
what you'd expect ☺.
The meat of an Action is its .Perform method; this takes a list of Items
to act on (and optionally the corresponding modifiers) and optionally
returns a list of Items. For your DOI resolver, you'll extract the DOI
from the Item(s) passed in, do whatever work you need to do to resolve
them, and then return a list of URLItems corresponding to the resolved
DOI(s).
There are a couple of additional methods and properties you'll want to
provide - the SupportedItemTypes property telling Do what sort of Items
your Action can act upon, and (optionally) the SupportsItem method to
determine whether a specific Item is supported.
The other thing you need is some way to tell Do about the plugin -
metadata such as its name, the icon to show, its version, and what sort
of plugin it provides. For that you need to build in a $FOO.addin.xml
resource - you'll find TinyUrl's in the TinyUrl/Resources directory¹.
Actually, you'll find TinyUrl.addin.xml.in there, because we need to set
a path in ./configure to point to the right place to grab translated
strings from. The build system adds that string in (the
“@expanded_datadir@/locale” bit) and generates TinyUrl.addin.xml from
it.
I hope that's useful for you.
Chris.
(
For those interested in the ItemSource…
The core of an ItemSource is its Items property, which is an
IEnumerable<Item> of all the Items the ItemSource provides (obvious, eh?
☺). Every so often, Do asks each ItemSource to .UpdateItems() to ensure
that that .Items is up to date, then adds each Item in .Items to the
Universe (the set of things that Do searches through). You don't have
to care about this unless you want to add a bunch of Items to the set of
things Do looks through.
)
¹: Technically, I think you can provide this information through
appropriate C# attributes directly in the code. None of the existing Do
plugins do that, though!