Adding support for Tropy URL Scheme

Feature request
1

I’d like to have a tropy:// URL scheme so I can easily integrate this with other apps in my system. As an initial option, the URL would be really useful to open a specific photo. An example URL scheme could look like tropy://open?id=<uniqueid>

As an example, in Zotero it would be possible to use the attachment menu. From their docs:

image

You can also “Attach Link to URI…” to add a link to a web page ( http:// or https:// ) or to another program on your computer (e.g., OneNote onenote:// or Evernote evernote:// ).

I talked a little about how I would use links from other apps in Tropy here:

Having a Tropy URL Scheme would allow links to flow both ways!

Examples of other apps with URL Schemes:

Related posts:

2

Thanks for this! We’ve actually been laying the foundation for this already; none of this is documented yet, partly because we’re still exploring the possibilities and limitations of an API – and we also lack usage scenarios, so the more details you tell us about workflows you’d like to see supported the better.

Currently you should already be able to use to the tropy:// URL to open Tropy, but not much beyond that. You can also enable a full HTTP API which is more powerful (let’s you query the current project, download images or import new images etc). Our main issue with designing a good API is that in Tropy you can have multiple projects (I think this is different than in all the examples above), so I think we have these choices:

  • Make the full path to your project file an integral part of the URL. This is terrible, because it will produce long URLs and the URLs won’t be stable as they always depend on the current location of the project file – if you move the file, old URLs become stale.
  • Make the project id part of the URL. This is slightly better, because URLs would be shorter than when using full paths, however the biggest issue is that there is no guarantee that Tropy can find the project for a given id: Tropy could remember projects it has already seen, but even then you could move the files and there would be no sensible way for Tropy to find the files.
  • Always use the currently active (or most recent in case Tropy is woken up by the API call) project. This is what we do at the moment until we’ve settled on a better solution.
  • Allow you to register projects for API use explicitly. This solves some of the issues of the first two approaches, but not completely.

In any case, how would you like to use the Tropy URL scheme in other apps: open Tropy to a specific item or photo; import a given file; add a tag to an existing item – anything else?

By the way, reading you post just now it occurred to me that you should already be able to add arbitrary links to notes – so that’s something you could do as a workaround, if you want to link a photo in Tropy to other files or apps.

1 Like
3

Thanks! Sorry in advance for the long reply! Hope the minor headers make sense.

Re: Troubleshooting tropy:// in Linux

Just a heads up, there might be some additional trickiness to get it to work in Linux (this might be related). At the moment, it doesn’t work for me in Ubuntu 18.04 with v1.8.0.

Some additional things Linux users might need to do:

xdg-mime default tropy.desktop x-scheme-handler/tropy
sudo update-desktop-database

To verify that the tropy:// URL works, the following commands should output tropy.desktop:

xdg-mime query default x-scheme-handler/tropy
xdg-settings get default-url-scheme-handler tropy

In addition, tropy should appear under Default applications in ~/.config/mimeapps.list :

[Default Applications]
...
x-scheme-handler/tropy=tropy.desktop

Given that I followed all the steps above, I’m not sure what else could be missing.

Re: tropy:// API

I believe you could look into Todoist’s projects for that. I’m pretty new to Tropy, but I believe you could do something similar:

todoist://project?id=128501470

Obsidian has a similar scheme with vaults, which just refer to two different folders in your laptop (but from what I understand would be equivalent to the projects here).

For Tropy, it really depends on how you want to perform the search to the specific item you want to open, but I could see something like

tropy://open?project=<id> # Opens a specific project
tropy://open?project=<id>&item=<itemid> # Opens a specific item in a project
tropy://open?project=<id>&list=<listid> # Opens Tropy on the specified list
tropy://open?project=<id>&list=<listid>&tag=<tag> # Opens a specific list filtered by the given tag(s)

In my opinion, using the project ID with this precondition is a reasonable assumption. If a link containing an id that has not been seen or remembered by Tropy is clicked, you could just default back to opening en empty Tropy instance.

Another alternative would be to support two variations of the URI… one with actions like open where the IDs are used, and a simpler “project” URL that could open the destination path as a Tropy library, but without the option to perform actions, e.g. tropy://tropy-project/path/to/my/photos. This would let the users have an “absolute” link to the vault (so tropy can remember it), and some action-based links once Tropy is aware of the project.

Re: Use cases

For me the main use case right now would be “linking” between applications, so opening to a specific item and/or photo would already serve 90% of what I’d like to do. My main goal is not so much to automate stuff through the URL scheme, but to easily switch between contexts. Adding tags or links (e.g. an obsidian link) to an item from other apps would be a second great step for me!

Keep in mind that I’m only starting with Tropy, and that I’m mostly using it for my genealogy hobby. Other academic users might have other more complex use cases that I haven’t thought about.

4

Last but not least, could you point me to where I could do this?

And thanks again for the thorough responses and the help!

5

URL scheme support and a “copy link” option in menus would be a very useful feature for two-way linking.

For linking to and from external note programs, like Evernote, and reference managers like Zotero.

It would also enable easy use of images in markdown.

2 Likes
6

I agree with what @tokeriis has suggested - a simple way to copy a link to an image would be fantastic. I take a lot of notes on the fly on visual material. It would be great to be able to insert a link to a specific image in Tropy, so that when I return to the note later I can easily jump to the thing I was looking at.

1 Like
7

Have there been any updates on tropy:// url scheme? From what I can tell playing with the HTTP API, it only allows us to pull information, but not control the UI.

My main usage scenario is as others have describe: to be able to copy an item ID to a tropy:// url that I can paste into Zotero, emacs/org-mode, or some other app, then click it to open Tropy and jump right to the item. This might be for external note taking, organizing, or to do lists.

I asked about on github a few years ago (External Tropy image/photo URI, OR open image/photo from command line · Issue #387 · tropy/tropy · GitHub) and it looks like a similar issue was created earlier this year (Enable tropy URL-scheme · Issue #595 · tropy/tropy · GitHub).

If there’s some code somewhere to test, or a few pointers to where it ought to be, then I can jump in and play a bit.

8

We’ll look to add this to the upcoming beta release. If you tell me your operating system, I’ll prioritize that one.

9

That’s great. It would be enormously helpful to my workflow.

I use Linux, personally, and I’m happy to test a beta release.

10

OK we finally added this to the dev build; I’m hoping to release the beta in the coming days. This is still exploratory while we figure out use cases for this. As a start we’ve implemented the following URL handlers:

  • tropy://about or tropy://version opens the ‘About Tropy’ window
  • tropy://preferences or tropy://prefs opens the preferences window
  • tropy://project or tropy://project/current opens/focuses the current or most recent project window
  • tropy://project/current/items/:itemID/:photoID will open the respective item and photo in the current project

You can copy a link to a specific item/photo via the context menu. Do you think this will work for your use case? There’s currently no other way to easily see an item’s or photo’s id in the UI though of course you could query the project db directly. Please let me know if you have other ideas!

Next, we’re planning to add a way to manage project file aliases: this will allow you to use names other than ‘current’ to link to a given project file. Tropy will then focus/open the respective project if such an URL is handled.

11

I’ll give it a shot as soon as the beta is out. The use case looks perfect.

It would be handy if there is a keyboard shortcut to copy the current item/photo tropy:// link.

Another idea would be to expand the API so that it’s possible to get the current item/photo ID. Then I could create a script to pull the current item as a tropy:// link directly into the document I’m working on and save cutting/pasting.

I can’t comment on project aliases.

12

A keyboard shortcut should be easy to do.

As for getting the key via API, do you mean to get the key via the HTTP API? I don’t think there is a way to respond to a request via the protocol, though we could add a URL that causes Tropy to copy the current item’s link to the clipboard, is that what you had in mind?

13

A shortcut would be great.

I was just hoping for a way to extract the currently selected item/photo ID using a script, without having to go through a clipboard. A URL that copied the link to the clipboard would be halfway there, and I could live with it. There’s plenty of ways to pull from the clipboard.