Differences

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

--- dev:client_coding:connector_http_server [2011/04/20 07:05] – adding info on existing connectors and details on writing new ones ajlyon
+++ dev:client_coding:connector_http_server [2019/06/19 19:49] (current) – bwiernik
@@ Line 1: / Line 1: @@
-Zotero has a built-in HTTP server designed to communicate with the Safari and Chrome extensions, called Connector. This HTTP server is enabled by default in Zotero Standalone and it can be enabled for Zotero in Firefox by setting ''extensions.zotero.connector.enabled'' to ''true'' in about:config. See the [[kb/connector enabled|knowledge base article]].
+====== Zotero Connector HTTP Server ======
-The connector server defines four endpoints by default:
+Zotero has a built-in HTTP server to communicate with the [[/support/standalone#zotero_connectors|Zotero Connector]] browser extensions.
-  * ''/translate/list''
-  * ''/translate/detect''
-  * ''/translate/save''
-  * ''/translate/select''
-These endpoints and the server in general are defined in the Zotero code at https://www.zotero.org/trac/browser/extension/trunk/chrome/content/zotero/xpcom/connector.js#L764
+The connector server defines several endpoints by default, including:
+  * ''/connector/savePage''
+  * ''/connector/saveItems''
+  * ''/connector/saveSnapshot''
+  * ''/connector/selectItems''
+  * ''/connector/getTranslatorCode''
+  * ''/connector/ping''
+These endpoints are implemented in [[https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/connector/server_connector.js|server_connector.js]]. The server is implemented in [[https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/server.js|server.js]].
 ====== Extending the Connector Server ======
-The following code registers an additional endpoint with the built-in connector HTTP server.
+The following code registers an additional endpoint with the connector server.
-This script must be run with chrome privileges. The best way to do this is to create an extension that [[https://developer.mozilla.org/en/XPCOM/Receiving_startup_notifications|registers an XPCOM service to run at Firefox startup]]. Firefox 4 users also have the option of creating a [[https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions|bootstrapped extension]]. Alternatively, you could register the endpoint from a overlay or from a chrome URI that you load manually.
+This script must be run with chrome privileges. The best way to do this is to create an extension that [[https://web.archive.org/web/20190612191336/https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Guide/Receiving_startup_notifications|registers an XPCOM service to run at Zotero startup]]. This can (and should if possible) be a [[https://web.archive.org/web/20190613013728/https://developer.mozilla.org/en-US/docs/Archive/Add-ons/Bootstrapped_extensions|bootstrapped extension]]. Alternatively, you could register the endpoint from a overlay or from a chrome URI that you load manually.
-Once registered, going to http://127.0.0.1:23119/myendpoint in a web browser should produce a page containing "Hello world."
+Once registered, going to http://127.0.0.1:23119/myAddon/helloWorld in a web browser should produce a page containing "Hello world."
-When the server receives a request for a given endpoint, it calls the ''init()'' method of the specified object, passing three arguments:
+When the server receives a request for a given endpoint, it calls the ''init()'' method of the specified object, passing two arguments:
-  * ''method'' - the method of the request (''"GET"'' or ''"POST"'')
   * ''data'' - the query string (for a GET request) or POST data (for a POST request)
   * ''sendResponseCallback'' - a function to send a response to the HTTP request. This can be passed a response code alone (e.g., ''sendResponseCallback(404)'') or a response code, MIME type, and response body (e.g., ''sendResponseCallback(200, "text/plain", "Hello World!")'')
-<code>
+The endpoint can also restrict supported methods and data types. Keep in mind that any webpage loaded in a browser can issue a GET request or POST application/x-www-urlencoded or text/plain encoded data to the integrated HTTP server, although cross-origin restrictions prevent webpages from reading the response.
+<code javascript>
 var Zotero = Components.classes["@zotero.org/Zotero;1"]
 	.getService(Components.interfaces.nsISupports)
 	.wrappedJSObject;
-MyEndpoint = {};
+/**
-MyEndpoint.prototype = {
+ * Hello world endpoint
+ *
+ * Accepts:
+ *		Nothing
+ * Returns:
+ *		"Hello world" page
+ */
+var myEndpoint = Zotero.Server.Endpoints["/myAddon/helloWorld"] = function() {};
+myEndpoint.prototype = {
+	"supportedMethods":["GET"],
 	/**
-	 * Gets available translator list
+	 * Sends a fixed webpage
-	 * @param {String} method "GET" or "POST"
 	 * @param {String} data POST data or GET query string
 	 * @param {Function} sendResponseCallback function to send HTTP response
 	 */
-	"init":function(method, data, sendResponseCallback) {
+	"init":function(postData, sendResponseCallback) {
-		// do something with data here?
+		sendResponseCallback(200, "text/html",
-		Zotero.debug("MyEndpoint loaded");
+			'<!DOCTYPE html><html><head/><body>Hello world!</body></html>');
-		sendResponseCallback(
-, 		// 200 OK
-			"Hello world"	// Response body
-		);
 	}
 }
-// Register endpoint
-Zotero.Connector.Endpoints["/myendpoint"] = MyEndpoint;
 </code>