Add options for remotely controlling/accessing JabRef (Command-Line or x-callbacks)

[nathanlesage]

Hey, as discussed on Twitter, over at Zettlr we're currently thinking about ways to interact between the app and several reference managers. Everytime you write something, it might happen that you want to change something in a specific citation or just want to open the linked PDF-File. In this case, it would be great to have a small interface to tell reference managers "Hey, please jump to that entry!" or "Could you please open the PDF file linked with that citekey?"

Zotero uses x-callback-links for that, that is, custom-protocol URLs such as zotero://open-pdf/library/items/[itemKey]?page=[page] or zotero://select/items/@[citekey]. The benefit would clearly be a better cross-integration between several components of your workflow on your computer.

If something like this would be possible, this would be great! :) I'm not sure of all potential good options for such an API, but I think the most important ones would be "Open linked PDF for entry with citekey @xyz" and "Select entry @CiteKey".

---

Further reference: Zettlr/Zettlr#418

[tobiasdiez]

That should be relatively straightforward to implement: https://stackoverflow.com/questions/26363573/registering-and-using-a-custom-java-net-url-protocol

Do you also have the database name, or just the citation key?

Side remark/question: As you may know some reference manager include knowledge management and note taking to some extend. This is still one of JabRef's weaknesses. Do you think it would be possible to include some of the features of Zettlr in JabRef? A beginning would be for example to view Zettlr notes citing a given entry.

[nathanlesage]

Sounds good! I am not sure what options one might end up needing — therefore I'd design the API to be extendable. I haven't yet made so much experience using JabRef (albeit I will be implementing it in a project I'm working on currently, because having one bibTex file is much better for working in a team than Zotero's internal database!) So concerning database name — I don't know how often one might have more than one open …? I mean Zettlr will read in the BibTex file, so it'll have access to everything stored in there.

Concerning the callback URLs, I'd opt for a REST or CRUD-approach, because it seems to me to be the most flexible approach to that! (In case of security concerns one could limit access to the commands via Preferences or a notification window).

And to the side remark/question: Sounds like a very interesting idea. I personally don't really use the note taking abilities of Zotero, because I tend to view software based on the one-program-one-function paradigm (albeit I'd rather say: one program one domain), this is why I don't want to implement reference manager functionality into Zettlr and opt for simply communicating with a program that offers such functionality. However, there's an issue open on my tracker where someone wanted such an x-callback-approach for Zettlr, and while we're on it, I could also implement that in Zettlr so that reference managers can access the internal API themselves!

[nathanlesage]

Heya, I just wanted to drop by because while discussing the cross-integration, we came upon a question that we might want to discuss before integrating that feature: Most citations are in the form [prefix @CiteKey, page-number]. Zettlr is able to extract the page number, so when we talk about "please open that item", together with @somelinguist we had the idea that maybe we could implement an API that also optionally takes a page-parameter to -- if the linked file is indeed a PDF -- open the PDF on the specified page. Zotero, for instance, also implements that functionality via their callback API. I don't know -- is it possible for JabRef to open PDFs with a page number given? If so, the question would be of how to handle it -- the easiest way from the perspective of Zettlr would be to simply throw both CiteKey, library, and an optional page number at JabRef, and then let JabRef decide whether to use the page number (if the linked file is indeed a PDF) or to simply ignore it (if it's a simple URL).

What do you think?

[tobiasdiez]

At the moment, JabRef does not support opening a PDF at a specific page. In principle, it would be relatively straightforward to add it. Related code:

jabref/src/main/java/org/jabref/gui/desktop/JabRefDesktop.java

Lines 89 to 100 in c3b7ee7

	} else if (StandardField.PS.equals(field)) {
	try {
	NATIVE_DESKTOP.openFile(link, StandardField.PS.getName());
	} catch (IOException e) {
	LOGGER.error("An error occurred on the command: " + link, e);
	}
	} else if (StandardField.PDF.equals(field)) {
	try {
	NATIVE_DESKTOP.openFile(link, StandardField.PDF.getName());
	} catch (IOException e) {
	LOGGER.error("An error occurred on the command: " + link, e);
	}

However, there is no generally accepted API for pdf reader, so one needs to have a look at the most common ones and find the necessary cmd args. This is possible but also a bit of work. So for now I would say you can through the page number at JabRef, but we will ignore it for the moment. If there is enough user feedback to get page numbers working, we can implement it later.

I'm pretty busy the next two weeks, not sure if I find the time to implement the API soon. :(

[nathanlesage]

This sounds great! I know that there's no unified API (I mean why standardise, right? 🙄) I'll just stay tuned on how you'll be implementing that and in the meantime think of a good scalable way of realising this interaction within Zettlr. Additionally, I'll increase priority on the implementation of such a callback-interface in Zettlr, so if you'd like you can think of ways in which an interaction with Zettlr for notes based on the CiteKeys, etc. would be cool for you, so that I can directly implement the API endpoints you'd need right from the beginning! :)

P.S.: I tried to find the responsible class for the integrations you already have for other programs such as TeXLive and vi, but I couldn't find it. It would be really nice if you could point me in the right direction so that I can "copy" the way you handle those apps in order to make it easy to implement the inter-application-communication!

Oh, and we all are busy, so there's absolutely no pressure! I really value that you want to implement this API, but please, there's no deadline — after all, it's open source! Have nice holidays and a good start into 2020 and don't worry too much until then!

[somelinguist]

@tobiasdiez That sounds great!

For reference, Zotero has some logic for figuring out how to pass the command line arguments to several different PDF readers on different OS at https://github.com/zotero/zotero/blob/3c1cdd57d2ad52cc9434b906a469579cb7b850a8/chrome/content/zotero/xpcom/openPDF.js#L26

For Windows, they're supporting Adobe and PDF-XChange, both of which look like you would do:

path/to/program.exe /A page=# path/to/pdf

For Linux, they support Evince and Okular, both of which look like:

path/to/program -p # /path/to/pdf

On macOS they support the native Preview app, Skim, and PDF Expert. They're using custom AppleScripts for each one (see link above).

[tobiasdiez]

@nathanlesage These push operations are implemented here: https://github.com/JabRef/jabref/tree/8777c16a99bd83e4a30ddafc859c0c2208b68733/src/main/java/org/jabref/gui/push
For most applications it's just a glorified command line execution, i.e.

jabref/src/main/java/org/jabref/gui/push/PushToWinEdt.java

Lines 24 to 28 in 8777c16

	@Override
	protected String[] getCommandLine(String keyString) {
	return new String[] {commandPath,
	"\"[InsText('" + getCiteCommand() + "{" + keyString.replace("'", "''") + "}');]\""};
	}

.

[nathanlesage]

Thanks for the hint!

… I suppose it would not be too difficult to use callback URLs instead of CLI calls given the above-mentioned stackoverflow thread, right? If so, it would be great, because I somehow feel that implementing a clean RESTful API via callback URLs is better than implementing command line switches, because these I'd need to hack together ugly, b/c the command line switches are accessed at the purely functional part of the app currently, which would break the object-oriented approach to some extend :D

[github-actions]

This issue has been inactive for half a year. Since JabRef is constantly evolving this issue may not be relevant any longer and it will be closed in two weeks if no further activity occurs.

As part of an effort to ensure that the JabRef team is focusing on important and valid issues, we would like to ask if you could update the issue if it still persists. This could be in the following form:

• If there has been a longer discussion, add a short summary of the most important points as a new comment (if not yet existing).
• Provide further steps or information on how to reproduce this issue.
• Upvote the initial post if you like to see it implemented soon. Votes are not the only metric that we use to determine the requests that are implemented, however, they do factor into our decision-making process.
• If all information is provided and still up-to-date, then just add a short comment that the issue is still relevant.

Thank you for your contribution!