Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
dev:client_coding:libreoffice_plugin_wire_protocol [2012/06/26 18:53] – [Word Processor Commands] simondev:client_coding:libreoffice_plugin_wire_protocol [2022/07/20 09:44] (current) – adomasven
Line 1: Line 1:
-====== LibreOffice Plugin Wire Protocol ======+====== LibreOffice 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.+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.
  
 ===== 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, 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 20: 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 35: Line 35:
 <code> <code>
                 TRANS ID    LENGTH      PAYLOAD                 TRANS ID    LENGTH      PAYLOAD
-HEXADECIMAL     00 00 00 01 00 00 00 24 5B 22 41 70 70 6C 69 63 61 74 69 6F (...)+HEXADECIMAL     00 00 00 01 00 00 00 24 5B 33 2C 20 31 5D
 INTERPRETATION  1           6           [3, 1] INTERPRETATION  1           6           [3, 1]
 </code> </code>
  
 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 61: Line 64:
 </code> </code>
  
-If the request is successful, the client must send a response with a JSON-encoded payload. This response is often code>null</code> if the command returns no output, but may also be an array, an integer, a string, or a boolean value depending on the command.+If the request is successful, the client must send a response with a JSON-encoded payload. This response is often null if the command returns no output, but may also be an array, an integer, a string, or a boolean value depending on the command.
  
 If the request is unsuccessful, the client must send a response with the payload: If the request is unsuccessful, the client must send a response with the payload:
Line 70: 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 157: Line 162:
 ==== Document_getDocumentData ==== ==== Document_getDocumentData ====
  
-Retrieves data string set by [#setDocumentData].+Retrieves data string set by [[#setDocumentData]]. NOTE: If the document has been converted to the transfer format and the first line of the document reads "ZOTERO_TRANSFER_DOCUMENT", then this method should return "ZOTERO_TRANSFER_DOCUMENT".
  
 === Parameters === === Parameters ===
Line 165: Line 170:
 === Returns === === Returns ===
  
-(String) The document data string.+(String) The document data string or "ZOTERO_TRANSFER_DOCUMENT"
  
 ==== Document_cursorInField ==== ==== Document_cursorInField ====
Line 205: 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 ====
  
-Get all fields present in the document.+Get all fields present in the document, in document order.
  
 === Parameters === === Parameters ===
Line 225: 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 | 
 + 
 + 
 +==== Document_importDocument ==== 
 + 
 +Called to convert Zotero document transfer format links to fields after Document_getDocumentData returns "ZOTERO_TRANSFER_DOCUMENT". Should reverse the export procedure. Note that citation links may contain trailing parameters, e.g. "https://www.zotero.org/google-docs/?q15df3" 
 + 
 +=== Parameters === 
 + 
 +| 0 | documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]| 
 +| 1 | fieldType | %%String%% | Specifies to what field type the import links should be converted. Should always be "ReferenceMark" for the LibreOffice wire protocol. | 
 + 
 +=== Returns === 
 + 
 +`true` if field links and document data were found and imported, `false` otherwise 
 + 
 + 
 +==== Document_exportDocument ==== 
 + 
 +Converts the document to the Zotero transfer document format. The format is: 
 +1. Insert 4 paragraphs at the beginning of the document, where first one reads "ZOTERO_TRANSFER_DOCUMENT" and third one has the `transferDocumentInstructions` supplied via a parameter. 
 +2. Convert all citations to links that point to "https://www.zotero.org/" and the link text is set to the citation code. 
 +3. At the end of the document insert a link that points to "https://www.zotero.org/" with the text set to documentData. 
 + 
 +=== Parameters === 
 + 
 +| 0 | documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]| 
 +| 1 | fieldType | %%String%% | The field type that the document stores Zotero citations in. Either "ReferenceMark" or "Bookmark". | 
 +| 2 | transferDocumentInstructions | %%String%% | A text string to be inserted at the start of the document explaining the document format | 
 + 
 +=== Returns === 
 + 
 +null
  
 ==== Document_setBibliographyStyle ==== ==== Document_setBibliographyStyle ====
  
-TODO+Provides parameters for the dedicated bibliography formatting style (usually called "Bibliography"). 
 + 
 +=== Parameters === 
 + 
 +| 0 | documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]| 
 +| 1 | firstLineIndent | %%Integer%% | First line indent in twips | 
 +| 2 | bodyIndent | %%Integer%% | Bibliography body indent in twips. Applies to first line too. First line indent is calculated by <code>firstLineIndent+bodyIndent</code> | 
 +| 3 | lineSpacing | %%Integer%% | Line spacing in twips | 
 +| 4 | entrySpacing | %%Integer%% | Bibliography entry spacing in twips | 
 +| 5 | tabStops | %%Array(Integer)%% | Tabulator indents | 
 +| 6 | numTabStops | %%Integer%% | Length of tabStops array | 
 + 
 +== Example Parameters == 
 + 
 +<code> 
 +[1, -720, 720, 240, 0, [], 0] 
 +[1, -720, 720, 240, 0, [1], 720] 
 +</code> 
 + 
 + 
 +=== Returns === 
 + 
 +null
  
 ==== Document_complete ==== ==== Document_complete ====
Line 291: Line 407:
 | fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document_cursorInField]], [[#Document_insertField]], or [[#Document_getFields]]| | fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document_cursorInField]], [[#Document_insertField]], or [[#Document_getFields]]|
 | text | %%String%% | The text | | text | %%String%% | The text |
 +| isRich | %%Boolean%% | Whether the text should be interpreted as RTF ||
  
 === Returns === === Returns ===
Line 298: Line 415:
 ==== Field_getText ==== ==== Field_getText ====
  
-Gets the text of a field.+Gets the (visible) text of a field. Note that any RTF information from setText is not returned, just the visible plaintext.
  
 === Parameters === === Parameters ===
Line 307: Line 424:
 === Returns === === Returns ===
  
-(String) The text+(String) The (visible) text
  
 ==== Field_setCode ==== ==== Field_setCode ====
Line 318: Line 435:
 | fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document_cursorInField]], [[#Document_insertField]], or [[#Document_getFields]]| | fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document_cursorInField]], [[#Document_insertField]], or [[#Document_getFields]]|
 | code | %%String%% | The field code| | code | %%String%% | The field code|
 +
 +=== Returns ===
 +
 +null
 +
 +==== Field_convert ====
 +
 +Converts a field from one type to another.
 +
 +=== Parameters ===
 +
 +| documentID | %%Integer|String%% | The documentID, as originally returned by [[#Application_getActiveDocument]]|
 +| fieldID | %%Integer|String%% | The fieldID, as originally returned by [[#Document_cursorInField]], [[#Document_insertField]], or [[#Document_getFields]]|
 +| fieldType | %%String%% | The type of field used by the document, either ReferenceMark or Bookmark |
 +| noteType | %%Integer%% | The type of note specified by the style:<code>
 +NOTE_IN_TEXT = 0
 +NOTE_FOOTNOTE = 1
 +NOTE_ENDNOTE = 2
 +</code> |
  
 === Returns === === Returns ===
  
 null null
dev/client_coding/libreoffice_plugin_wire_protocol.1340751239.txt.gz · Last modified: 2012/06/26 18:53 by simon