Differences

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

Link to this comparison view

Next revision		Previous revision
dev:client_coding:http_integration_protocol [2019/02/08 06:13] – created adomasvendev:client_coding:http_integration_protocol [2022/07/20 09:39] (current) – Update for Zotero 6.0 adomasven
Line 1: Line 1:
 ====== HTTP Citing Protocol ====== ====== HTTP Citing Protocol ======
  
-The Google Docs plugin uses a simple HTTP protocol to communicate with Zotero. The below documentation applies to Zotero 5.0.46 or newer.+The Google Docs plugin uses a simple HTTP protocol to communicate with Zotero. The below documentation applies to Zotero 6.0 and newer.
  
 ===== Basics ===== ===== Basics =====
Line 53: Line 53:
  
 ^ 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 | 
-| "addEditCitation" | Add a new citation or edit the selected one | +| "addNote" | Insert a Zotero note into the document |
-| "addBibliography" | Add a new bibliography | +
-| "editBibliography" | Edit an existing bibliography | +
-| "addEditBibliography" | Add a new bibliography or edit the already inserted one |+
 | "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" | Open the dialog to 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]]. 
 + 
 +If Zotero responds with a 503 HTTP response, it means that another integration transaction is already in progress. If your integration client initiates an integration transaction and fails to complete it by either returning an error or responding to requests until ''#Document.complete'' is issued the Zotero integration layer will continuously respond with 503 until it is restarted. 
  
 ===== Word Processor Commands ==== ===== Word Processor Commands ====
Line 87: Line 89:
  
 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 216: Line 220:
 | 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 ===
 +
 +| text | %%String%% | The text |
 +
 +
 +=== Returns ===
 +
 +null
  
 ==== Document.getFields ==== ==== Document.getFields ====
Line 245: Line 262:
 NOTE_FOOTNOTE = 1 NOTE_FOOTNOTE = 1
 NOTE_ENDNOTE = 2 NOTE_ENDNOTE = 2
-</code>+</code> |
 | count | %%Number%% | Size of the above arrays | | count | %%Number%% | Size of the above arrays |
  
Line 251: Line 268:
  
 null 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 | placeholderIDs | %%Array(String)%% | An array of placeholderID strings which are to be converted to citation fields in the document. |
 +| 1 | noteType | Number | Note type to convert citation placeholders to. Is one of<code>
 +NOTE_IN_TEXT = 0
 +NOTE_FOOTNOTE = 1
 +NOTE_ENDNOTE = 2
 +</code> |
 +| 2 | fieldType | Number | To be ignored |
 +
 +=== 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.setBibliographyStyle ==== ==== Document.setBibliographyStyle ====
dev/client_coding/http_integration_protocol.1549624430.txt.gz · Last modified: 2019/02/08 06:13 by adomasven