Differences

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

--- dev:client_coding:connector_http_server [2011/04/19 12:02] – created rmzelle
+++ dev:client_coding:connector_http_server [2019/06/19 19:49] (current) – bwiernik
@@ Line 1: / Line 1: @@
-The following code registers an endpoint with the built-in connector HTTP server. This HTTP server is enabled by default in Zotero Standalone. It can be enabled in Firefox setting extensions.zotero.connector.enabled to true in about:config.
+====== Zotero Connector HTTP 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.
+Zotero has a built-in HTTP server to communicate with the [[/support/standalone#zotero_connectors|Zotero Connector]] browser extensions.
-Once registered, going to http://127.0.0.1:23119/myendpoint in a web browser should produce a page containing "Hello world."
+The connector server defines several endpoints by default, including:
+  * ''/connector/savePage''
+  * ''/connector/saveItems''
+  * ''/connector/saveSnapshot''
+  * ''/connector/selectItems''
+  * ''/connector/getTranslatorCode''
+  * ''/connector/ping''
-<code>
+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 connector server.
+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/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 two arguments:
+  * ''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!")'')
+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>