Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
dev:client_coding:libreoffice_plugin_wire_protocol [2020/10/13 03:57] – Add import/export commands and improve/clarify other commands. adomasvendev:client_coding:libreoffice_plugin_wire_protocol [2022/07/20 09:44] (current) – adomasven
Line 1: Line 1:
-<html><p id="zotero-5-update-warning" style="color: red; font-weight: bold">We’re +====== LibreOffice Wire Protocol ======
-in the process of updating the documentation for +
-<a href="https://www.zotero.org/blog/zotero-5-0">Zotero 5.0</a>. Some documentation +
-may be outdated in the meantime. Thanks for your understanding.</p></html>+
  
- +The LibreOffice plugin uses a simple wire protocol to communicate with Zotero. (The Word for Mac and Word for Windows plugins both run in process, and use AppleEvents and COM respectively to communicate with the word processor.) The below documentation applies to Zotero 6.0 and newer.
-====== LibreOffice Plugin Wire Protocol ====== +
- +
-The LibreOffice plugin uses a simple wire protocol to communicate with Zotero. (The Word for Mac and Word for Windows plugins both run in process, and use AppleEvents and COM respectively to communicate with the word processor.) The below documentation applies to Zotero LibreOffice Integration 3.5.3 and newer.+
  
 ===== Basics ===== ===== Basics =====
  
-The Firefox or Zotero Standalone process operates a server on port 23116, which the extension residing within LibreOffice connects to. All frames consist of a 32 bits specifying the transaction ID, a big-endian 32-bit integer specifying the length of the payload, and the payload itself, which is either UTF-8 encoded JSON or an unescaped string beginning with "ERR:".+The Zotero client process operates a server on port 23116, which the extension residing within LibreOffice connects to. All frames consist of a 32 bits specifying the transaction ID, a big-endian 32-bit integer specifying the length of the payload, and the payload itself, which is either UTF-8 encoded JSON or an unescaped string beginning with "ERR:".
  
 There are two types of commands: [[#integration_commands|integration command]], sent by the word processor to Zotero initiate an operation (e.g., to add a new citation), and [[#word_processor_commands|word processor commands]], sent from Zotero to the word process to retrieve data from a document or to make changes to the document. Integration commands are sent from the word processor to Zotero, and must never receive a response. Word processor commands are sent from Zotero to the word processor, and must always receive a response. There are two types of commands: [[#integration_commands|integration command]], sent by the word processor to Zotero initiate an operation (e.g., to add a new citation), and [[#word_processor_commands|word processor commands]], sent from Zotero to the word process to retrieve data from a document or to make changes to the document. Integration commands are sent from the word processor to Zotero, and must never receive a response. Word processor commands are sent from Zotero to the word processor, and must always receive a response.
Line 26: Line 20:
                 TRANS ID    LENGTH      PAYLOAD                 TRANS ID    LENGTH      PAYLOAD
 HEXADECIMAL     00 00 00 00 00 00 00 0C 22 61 64 64 43 69 74 61 74 69 6F 6E 22 HEXADECIMAL     00 00 00 00 00 00 00 0C 22 61 64 64 43 69 74 61 74 69 6F 6E 22
-INTERPRETATION  0           11          "addCitation"+INTERPRETATION  0           11          {"command": "setDocPrefs", "templateVersion": 1} 
 </code> </code>
  
Line 46: Line 40:
  
 You can observe frame payloads sent between Zotero and LibreOffice in the Zotero [[/support/debug_output|debug output]]. You can observe frame payloads sent between Zotero and LibreOffice in the Zotero [[/support/debug_output|debug output]].
 +
 ===== Integration Commands ===== ===== Integration Commands =====
  
-These commands are sent from the word processor to Zotero, and do not receive a response. The command payload is always a quoted string.+These commands are sent from the word processor to Zotero, and do not receive a response. The command payload is always a JSON object with a `command` property, which is described below and a `templateVersion` property which is a number. The templateVersion number is used by Zotero to notify the integration user if the plugin installed in LibreOffice is outdated. The current up-to-date version is "1".
  
 ^ Command ^ Description ^ ^ Command ^ Description ^
-| "addCitation" | Add a new citation | +| "addEditCitation" | Add a new or edit an existing citation | 
-| "editCitation" | Edit an existing citation | +| "addEditBibliography" | Add a new or edit an existing bibliography | 
-| "addBibliography" | Add a new bibliography | +| "addNote" | Insert a Zotero note into the document |
-| "editBibliography" | Edit an existing bibliography |+
 | "refresh" | Refresh all fields in the document, verifying that they match expectations | | "refresh" | Refresh all fields in the document, verifying that they match expectations |
 | "removeCodes" | Remove field codes from the document | | "removeCodes" | Remove field codes from the document |
 | "setDocPrefs" | Change the citation style or other document parameters | | "setDocPrefs" | Change the citation style or other document parameters |
 +| "exportDocument" | Export the citations in the document to a format importable in other word processors |
 +
 +An up-to-date command list is always available by looking at the methods of [[https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/integration.js#L619|Zotero.Integration.Interface]].
  
 ===== Word Processor Commands ==== ===== Word Processor Commands ====
Line 76: Line 73:
  
 Zotero will cancel the current operation, log this error, and present it to the user using the [[#Document_displayAlert]] command if possible. If the subsequent Document_displayAlert command fails, Zotero will present the error using its own dialog box. Zotero will cancel the current operation, log this error, and present it to the user using the [[#Document_displayAlert]] command if possible. If the subsequent Document_displayAlert command fails, Zotero will present the error using its own dialog box.
 +
 +A full and up-to-date API of commands is available as part of [[https://github.com/zotero/zotero/blob/master/test/tests/integrationTest.js|Zotero Integration tests]] and [[https://github.com/zotero/zotero-libreoffice-integration/blob/master/components/zoteroOpenOfficeIntegration.js#L358||LibreOffice plugin code]].
  
 ==== Application_getActiveDocument ==== ==== Application_getActiveDocument ====
Line 211: Line 210:
 | 1 | fieldCode | %%Integer|String%% | The code stored within this field. Since no data has been set, this should be empty. | | 1 | fieldCode | %%Integer|String%% | The code stored within this field. Since no data has been set, this should be empty. |
 | 2 | noteIndex | %%Integer%% | The number of the footnote in which this field resides, or 0 if the field is not in a footnote. | | 2 | noteIndex | %%Integer%% | The number of the footnote in which this field resides, or 0 if the field is not in a footnote. |
 +
 +==== Document_insertText ====
 +
 +Inserts rich text (HTML) at cursor position. The rich text may contain citation placeholder hyperlinks (to https://www.zotero.org/?[placeholderID]) which are later converted to citations via [[#Document_convertPlaceholdersToFields]].
 +
 +=== Parameters ===
 +
 +| 0 | documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]|
 +| 1 | text | %%String%% | The text |
 +
 +
 +=== Returns ===
 +
 +null
 +
  
 ==== Document_getFields ==== ==== Document_getFields ====
Line 231: Line 245:
 ==== Document_convert ==== ==== Document_convert ====
  
-TODO+Converts all fields in a document to a different fieldType or noteType. Called upon style change from a an in-text to note type or vice-versa 
 + 
 +=== Parameters === 
 + 
 +| 0 | documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]| 
 +| 1 | fields | %%Array(String)%% | Array of field IDs to be converted | 
 +| 2 | toFieldType | %%Array(String)%% | Array of field types to be converted to. Each entry is either "ReferenceMark" or "Bookmark" | 
 +| 3 | toNoteType | %%Array(Number)%% | Array of note types to be converted to. Each array entry corresponds to a field in the ''fields'' parameter and is one of<code> 
 +NOTE_IN_TEXT = 0 
 +NOTE_FOOTNOTE = 1 
 +NOTE_ENDNOTE = 2 
 +</code> | 
 +| count | %%Number%% | Size of the above arrays | 
 + 
 +=== Returns === 
 + 
 +null 
 + 
 +==== Document_convertPlaceholdersToFields ==== 
 + 
 +Converts placeholders (which are text with links to https://www.zotero.org/?[placeholderID]) to fields and sets their field codes to strings in `codes` in the reverse order of their appearance 
 + 
 +=== Parameters === 
 + 
 +| 0 | documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]| 
 +| 1 | placeholderIDs | %%Array(String)%% | An array of placeholderID strings which are to be converted to citation fields in the document. | 
 +| 2 | noteType | Number | Note type to convert citation placeholders to. Is one of<code> 
 +NOTE_IN_TEXT = 0 
 +NOTE_FOOTNOTE = 1 
 +NOTE_ENDNOTE = 2 
 +</code> | 
 +| 3 | fieldType | Number | Field type to convert to. Either `ReferenceMark` or `Bookmark` 
 +| count | %%Number%% | Size of the above arrays | 
 + 
 +=== Returns === 
 + 
 +Array of fields after conversion 
 + 
 +(Array) 
 + 
 +| 0 | fieldID | %%Array(Integer|String)%% | Unique identifiers for each field | 
 +| 1 | fieldCode | %%Array(Integer|String)%% | The code stored in each field | 
 +| 2 | noteIndex | %%Array(Integer)%% | The number of the footnote in which each field resides, or 0 if the field is not in a footnote |
  
  
dev/client_coding/libreoffice_plugin_wire_protocol.1602575865.txt.gz · Last modified: 2020/10/13 03:57 by adomasven