Translator minVersion
I am trying to write a simple export translator.
If I change the "minVersion" field from "2.0" to "6.0", the "libraryID" becomes "undefined". Is it a bug or a misunderstanding of how to use that field?
Thank you.
If I change the "minVersion" field from "2.0" to "6.0", the "libraryID" becomes "undefined". Is it a bug or a misunderstanding of how to use that field?
Thank you.
How can I get the current translator version?
I have looked in the following links, but could not see this information:
- https://www.zotero.org/support/translators
- https://www.zotero.org/support/dev/translators
- https://www.zotero.org/support/dev/translators/coding
- https://www.zotero.org/support/dev/how_to_write_a_zotero_translator_2nd_edition
I went through the GitHub page, but I could not find the information about the latest version of the Zotero translator. Could you point me where to find the version of the Zotero translator?
Can you first describe what the problem is you're looking to solve?
I am trying to understand what is the meaning of "Version" in these fields.
From the information below, I understood that the version to put in there is just the version of Zotero from which it is tested to work:
"minVersion & maxVersion
Respectively the minimum and maximum version of Zotero (as specified in Zotero’s Install Manifest) with which the translator is compatible."
https://www.zotero.org/support/dev/translators
(I don't know how to put formatting for a quotation in my reply.)
The latest version of Zotero I am using now is 6.0. So I have simply put 6.0 in my translator, instead of the 2.0 that was in the example I followed. However, when using 6.0, it leads to the "undefined" output for the "libraryID", described in my original post.
From your reply, I understood that the translators are using somehow a different "version" than the version of the Zotero client:
"I think the translator versions track differently than the client version. I have all mine set to 4.0.27"
But I don't understand what is the correct "version" information that should be used to put in the "minVersion" & "maxVersion" fields, and where to find it.
If it is the Zotero client version, then I guess it is a bug. If not I would like to understand where to find the correct information.
I can't fault your for curiosity, but I find the combination of "what is the version I need" and "not a coder, don't know github" peculiar. Not mocking, should that be a concern, but I just don't understand what you're trying to achieve.
So, you still haven't stated the actual problem you want solved. What problem do you have that knowing these versions would help solve? Are you trying to create a new translator? Something else?
https://forums.zotero.org/discussion/98368/custom-copy-paste-to-evernote
The format of the question was probably not clear, or contained too many questions. So I started to split my questions into smaller posts, easier to get replies to.
In short, I just want to extract the information I need from Zotero, in the format I need, in a way that it gives me a fast way to go back quickly to the original information in Zotero. The idea behind is to design a simple interactive workflow with direct connections to the pdf files in Zotero for a literature review.
I have formulated the question with Evernote, but it would be the same questions for the notes in Zotero.
I have just transferred from Mendeley to Zotero, following the nice improvements of Zotero in version 6. So I am still learning what is possible to do through Zotero, through Zotero plugins, or through simple customization. It is difficult to ask a clear question without understanding all the possibilities and limits of Zotero.
I understand that developers do not have time to customize the workflow of all users. So I will probably need to put some effort from my side to see what I can do with the tools available.
All the information I have found seems to give "select" links to the main panels in Zotero: zotero://select/library/items/. I want to get "open-pdf" links (ideally with all the options like links to a specific page number, links to Zotero annotations, open the pdf file in a new Zotero window, ...).
After searching through different discussions, I concluded that:
- The open-pdf links are already working, but not accessible in a way that would be efficient for my workflow.
- The easiest way to obtain the open-pdf links is probably through a custom Quick Copy, after reading the following page:
https://zoteromusings.wordpress.com/2013/04/23/zotero-item-uris-from-client/
This is for the more general reply on what I want to achieve, with the context.
Leading to the reason for this post being that I am writing a simple custom translator for my workflow.
And you are right, the main reason behind this post is mostly curiosity, as leaving 2.0 would probably work for my purpose. The reasons to still ask about it were:
- I thought that the very small size of the translator code would be a good starting point to learn how to produce nice custom tools for my workflow. So understanding what the code is doing is important to understand what is possible to do.
- Other people may have the same question, and could find this post useful. I could not find it in the documentation, so I have documented the places that I have searched.
I will be glad to get some feedback on this process.
Translators can convert Zotero information into plain text. That's it. When exporting to file, only a single file can be generated, so you can't eg export multiple markdown files in a single run. You can set a single such translator to be the quick-copy/drag-drop translator, but again, text; while you can technically produce eg HTML, you can't specify the content-type from the translator, so the recipient likely will treat it as plain text. These translators are easy to build, but you get no user interaction beyond some input checkboxes. Since their scope is so limited, it is fairly easy to learn the infra.
Plugins are substantially more work to build. Zotero offers a Javascript scaffold to get you started, and I offer a more comprehensive but also more complex typescript scaffold + tools to publish updates and use modules from npmjs. If you don't need the complexity, certainly the JS scaffold is a great start, and it has a lot less moving parts to get to know. Switching to the typescript infra is possible later but more work, essentially a port.
Plugins can do almost anything you want if you are careful. They can also easily break Zotero, but unless you muck with the data, an uninstall will undo the breakage. For building plugins, you will have to get comfortable reading the Zotero source to figure out where and how you can hook into the internals; the basics are just Firefox XUL/XPCOM plugins, which is a technology that Mozilla no longer wants to talk about, and the docs on it have fallen in disrepair. If this is your first foray into programming, building XPCOM plugins is a dive into the deep end.
My own plugin started as a fairly simple mod of one of the Zotero translators, and now has a pretty chunky companion plugin, and a few tools like the publishing infra and a separate bibtex parser split off to npm modules. It got well out of hand, but it started as a translator.
I don't understand all the vocabulary in your reply yet, but I will come back to your post as I learn more about Zotero and the development tools.
I have now started to use the Zotero Scaffold:
https://www.zotero.org/support/dev/translators/scaffold
I will start with a simple export translator for my workflow and see where it takes me.
Is there any recommended place to share translators beyond the ones officially accepted in Zotero? I would be curious to see what other people have done to integrate in their personal workflow, and I would find it useful to get feedback on my translator as well.
Submitting a pull request to the Zotero Translators GitHub repo is probably not relevant for a workflow specific translator.
https://www.zotero.org/support/dev/translators
I have spent more time reading the "Step 3: Post to the Zotero Forums" and links in there to improve the content of my posts: https://www.zotero.org/support/getting_help
I clearly should have done this earlier. But I would find it very useful to emphasize further these useful recommendations within the forum page, maybe as a link at the bottom of the links on the left, or as a reminder below any "New Discussion"?
libraryID
field? This is the code that converts items to the pre-4.0.27 format. I don't believe it touches any library IDs.https://zoteromusings.wordpress.com/2013/04/23/zotero-item-uris-from-client/
This export translator is nice, as I can use it to link back to Zotero when making notes in Evernote. The format in it is:
function doExport() {
var item;
while(item = Zotero.nextItem()) {
Zotero.write("zotero://select/items/");
var library_id = item.libraryID ? item.libraryID : 0;
Zotero.write(library_id+"_"+item.key);
}
}
I have seen that it is also possible to link directly to the pdf file, with a link like:
zotero://open-pdf/items/...
instead of the select link given in the "Zotero Select Item.js" export translator.
These links seem to be more powerful, with direct links to the annotations in the pdf file, with a format like:
([Ravazzoli et al., 2020, p. 1](zotero://select/library/items/DY4CVXND)) ([pdf](zotero://open-pdf/library/items/XVYXIM5F?page=1&annotation=JLYLFW4S))
I would like to customize the export translator above to use in combination with the Zutilo plugin to customize some links that I can use in Evernote to open the pdf file in Zotero from Evernote. For example, something like:
[citeKey](zotero://open-pdf/library/items/XVYXIM5F)
So, I have used the export translator above as a starting point to achieve this goal. I did not find the information about "minVersion" or "libraryID" in the tutorial links I could find listed at the top of this discussion. I also could not find the relevant documentation on how to get the "DY4CVXND", "XVYXIM5F" and "JLYLFW4S" IDs.
My strategy to implement the custom translator I need was to go through the lines of the "Zotero Select Item.js" export translator one by one, to understand it. Leading to the question in this post.
Changing the "minVersion":"2.0" in that translator to "minVersion":"4.0.27" also returns an undefined libraryID. Suggesting that this language is not valid anymore in the new translators infrastructure.
From this understanding, my next question is therefore: what is the correct way to obtain the different IDs for the items, pdf files and annotations?
So I understand that the libraryID is not used anymore, and irrelevant to produce the links to Zotero?
Thank you very much for the Dump.js translator. From there, I can get some information to understand the origin of the different IDs in:
([Ravazzoli et al., 2020, p. 1](zotero://select/library/items/DY4CVXND)) ([pdf](zotero://open-pdf/library/items/XVYXIM5F?page=1&annotation=JLYLFW4S))
- "DY4CVXND" appears in the "parentItem" of the "attachments", and "itemKey" of the item at the bottom.
- "XVYXIM5F" appears in the "itemKey" of the "attachments".
- "JLYLFW4S" does not appear anywhere.
I will go through the documentation again with these new keywords.
In the dumped JSON file, I also get 2 URIs, one for the parent item and one for the PDF file. They open my Zotero online library. But they only select the item and pdf file in the side panel, not in the central library panel. Is it a bug?
Other remarks:
- The Quick Copy shortcut works when selecting the parent item in the library.
- It also works from anywhere when the PDF file is open in the Zotero PDF viewer, either when selecting an annotation, the pdf file or even from a note in the right side panel. However, it only gives the information of the parent item.
- The same shortcut "Ctrl + Shift + C" is used to copy a note when selected from the central panel in the library.
From all this, I guess that the Quick Copy only works on the main bibliographic items in the library. They can provide information on the PDF files attachments, but cannot provide the link to a specific PDF file if there are multiple PDF attachments.
I also guess that the annotations information is not accessible from the translators infrastructure?
I was expecting the Quick Copy tools to be available on all items, either parent or child.
Would it make sense in the future to extend the capabilities of the Quick Copy to be available also when selecting a child item, like a PDF file or a note, and also on the annotations?
Otherwise, the Quick Copy is not the right tool to obtain a link like:
([Ravazzoli et al., 2020, p. 1](zotero://select/library/items/DY4CVXND)) ([pdf](zotero://open-pdf/library/items/XVYXIM5F?page=1&annotation=JLYLFW4S))
Is there any simple way to achieve this, or it requires developing a Zotero plugin?
A drag and drop from an annotation into Evernote copies the content of the annotation, but does not give any link back to Evernote.
But then the conclusion above contradicts the following statement in the Zotero 6 announcement: https://www.zotero.org/blog/zotero-6/
With the example in the image clearly showing a link to an annotation in a PDF file with the open-pdf Zotero link... So I am probably missing something?
The ability to get the complete link above seems to be only possible from internal commands, with the formatting described in another part of Zotero, not in the Quick Copy part:
https://www.zotero.org/support/note_templates
Thank you for your help to clarify these points.
No I think they're still used in links
from the looks of it it is the key of an annotation
That I can't tell you.
That will be the entry point for these attachments, yes.
I think they can? If there are multiple attachments, there will be an array of attachment objects on the item
If it isn't dumped by Dump.js, the answer is indeed "no".
Looks like they're only available on top-level, non-attachment items.
That's for the Zotero devs to decide. I'm not part of the Zotero crew.
I don't see anything that would not be possible to produce with some work. But if you mean faithful reproduction of citations as produced by Zotero, this is technically possible but non-trivial.
A Zotero plugin can just use the Zotero infra for generating these. But plugins are harder to build
No I think it's possible to transform one into the other
- The Quick Copy tool can only access information from the top level of an item, the parent item.
- From that entry point, it can access the metadata of the item, its attachments and its child notes.
- The annotations information can be accessed with the Quick Copy tool only if it has been converted to a child note beforehand, or if it has been copied manually to a child note.
- All the annotations in the PDF viewer which have not been exported to a child note cannot be accessed from the Quick Copy tool.
- Therefore, a Quick Copy tool can provide the global information on a parent item, including the annotations which have been exported to a child note, but cannot be used as a "targeted" Quick Copy tool on any child item. I understand that the information of the child items is included in the available information, but this is not what I want to do. I would like to reproduce the behaviour of the internal copy paste commands of Zotero on a specific content (annotation or child item) to an external editor in a customized format.
If the conclusions above are correct, I had misunderstood the statement in the Zotero 6 announcement. Strictly speaking, the Quick Copy tool only works on the parent item in the main library, through which it can access all the child information. However, the Quick Copy tool is not capable of working directly, in a targeted way, on any of the child information if there is more than one. This would be the meaning of having a plural on "notes" and "annotations", meaning only all together. The "from the PDF reader" implies that the annotations have been exported to child notes beforehand.
The example provided in the image in the announcement is possible to achieve with the Quick Copy only for a hardcoded information in the translator on which child information to choose. There is no way to specify in a general way which child information within the parent item should be targeted by the Quick Copy.
I would like to ask the developers if it is planned to extend the Quick Copy capabilities to be usable also on the annotations in the PDF viewer and the child items?
Another possible interpretation of the announcement is that the text from the second sentence starting with "You can copy or drag [...]" does note actually refer to the Quick Copy tool, but rather to another general copy tool, available from Ctrl+C shortcut or drag and drop. In that case, the results I obtain from simple testing do not contain the links back to Zotero. Is there another place where this can be added, different from the translators in the Quick Copy settings? If I understand correctly your statement, even a plugin will not be able to achieve the targeted Quick Copy I am looking for.
This would explain why all the plugins for external editors are importing all the information all together, before allowing manipulation in their editor, rather than giving the ability to target specific data in Zotero directly. I see this heavy duplication of data highly unnecessary, considering that the targeted tools could be available in Zotero directly.
Then I guess that there are two main barriers to expand the capabilities of the Quick Copy tool to become a targeted Quick Copy tool:
1) Include the information about which item is currently selected in the data available.
2) Include the information about all the annotations in the PDF viewer which have not been exported to a note.
All the information is already there, because it is possible to achieve this kind of targeted copy with internal commands. But it would require an upgrade of the translators infrastructure to provide a targeted Quick Copy. This would really be a game changing upgrade, as external editors would not need to duplicate the data structure already maintained by Zotero.
Let's consider a publication in my library with two attached PDF files (e.g. the main publication PDF1 and its supplementary material PDF2). I open PDF1 in the Zotero PDF viewer. From there, I do the Quick Copy as Dump with your translator Dump.js. Then I open PDF2 in the Zotero PDF viewer and again do the Quick Copy as Dump from that second PDF file. From testing, the result of these two two Quick Copy is strictly identical. Can you confirm this behaviour?
This demonstrates that the Quick Copy as Dump did not copy the information about which PDF file was currently open in the Zotero PDF viewer.
This leaves 2 possible conclusions:
1) This is a limitation of the Dump.js translator. There are other commands available for translators to do this.
2) This is a limitation of the translators infrastructure. The only way to overcome the limitation will be to modify the translators infrastructure.
Do you know if the correct conclusion is 1 or 2, or if the reasoning is flawed?
But this is not an example of While I don't know what you mean by "targetting specific data in Zotero directly", I can pretty much guarantee you that a plugin can in fact do this. It may take a large effort for some desired results, and it may be fragile in the face of Zotero updates, so whether you want to take this route is up to you. My main plugin does a fair amount of this, so I only support the latest version of Zotero; it may or may not work with older versions that the latest, but if you find out it doesn't, you will have to upgrade. Compatibility for translators that stay in their sandbox is much more stable -- all the way back to 4.0.27.
Coming to the plugins: is it possible for a plugin to obtain "targeted" information from Zotero? In other words, is it possible for a plugin to know what is currently selected in Zotero?
To illustrate with the example above: Can I produce a plugin which can make a new "targeted Quick Copy" in the Zotero menus, with a different output depending on which PDF file is currently open?
If it is possible, it means that the plugins have access to more information than the translators, as they can obtain the information on what is currently selected in Zotero at a finer level.
In fact I could have Zotero play an MP3 attached to an item when that parent item is selected. That wouldn't even be hard. I could do that sticking to the regular extension points Zotero offers.
Zotero plugins are almost uniquely, ridiculously capable, because I am not even limited to these extension points that the devs could foresee, which is what most plugin systems would be limited to. I can, and do, change the internals of Zotero as it runs (a practice called monkey-patching) and I can do that in almost all parts of Zotero. Very few things are off-limits, and if I am happy to rebuild important chunks of Zotero on my own, nothing is actually off-limits. Because of all of this, plugins can also very easily disrupt Zotero.
So the translators just give the ability to format the metadata from the items in the library, including the metadata of the parent item and its child items. But they cannot access the annotations in the Zotero PDF viewer that have not been exported to a child note beforehand.
The translators can be used from the Zotero UI (e.g. the Quick Copy tool) or from plugins (like yours). This is why designing a targeted Quick Copy can be done from plugins (and Zotero developers), but cannot be done by writing a simple export translator fed to the existing Quick Copy.
This gives a good idea of what would be needed to generate a targeted Quick Copy.
Zotero.Utilities.Internal.itemToExportFormat
(but not for top-level attachments, which are not passed to translators I think).itemToExportFormat
, but we want translators like Zotero RDF to be able to export attachments with their annotations and then re-import them without any loss, so it gets a little more complicated.)