Differences

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

--- dev:zotero_7_for_developers [2024/02/16 15:51] – [Using the Firefox Developer Tools] dstillman
+++ dev:zotero_7_for_developers [2024/05/06 08:33] (current) – [Localization] xiangyu
@@ Line 1: / Line 1: @@
 ====== Zotero 7 for Developers ======
-Zotero 7, which will be released in 2024, includes a major internal upgrade of the Mozilla platform on which Zotero is based, incorporating changes from Firefox 60 through Firefox 102. This upgrade brings major performance gains, new JavaScript and HTML features, better OS compatibility and platform integration, and native support for Apple Silicon Macs.
+Zotero 7, which will be released in 2024, includes a major internal upgrade of the Mozilla platform on which Zotero is based, incorporating changes from Firefox 60 through Firefox 115. This upgrade brings major performance gains, new JavaScript and HTML features, better OS compatibility and platform integration, and native support for Apple Silicon Macs.
 While this upgrade required a massive rewrite of the Zotero code base and will require many plugin changes due to technical changes in the Mozilla platform, going forward we expect to keep Zotero current with Firefox Extended Support Release (ESR) versions, with comparatively fewer technical changes between versions.
@@ Line 11: / Line 11: @@
 ===== Dev Builds =====
-<html><!--<span style="color: red; font-weight: bold">WARNING:</span>--></html><html><!-- These are feature-incomplete test builds intended solely for use by Zotero plugin developers and **should not be used in production**. While we're not aware of any problems switching between Zotero 6 and 7, we nevertheless strongly recommend using a [[https://www.zotero.org/support/kb/multiple_profiles|separate profile and data directory]] for development.--></html>
+<html><span style="color: red; font-weight: bold">WARNING:</span></html> These are test builds based on Firefox 115 intended solely for use by Zotero plugin developers and **should not be used in production**. We strongly recommend using a [[https://www.zotero.org/support/kb/multiple_profiles|separate profile and data directory]] for development.
-The ''dev'' channel has been paused. Use [[:beta_builds|Zotero 7 beta builds]] for development.
+<HTML><!--The ''dev'' channel has been paused. Use [[:beta_builds|Zotero 7 beta builds]] for development.--></HTML>
-<html><!--
   * [[https://www.zotero.org/download/client/dl?channel=dev&platform=mac|Mac]]
   * [[https://www.zotero.org/download/client/dl?channel=dev&platform=linux-x86_64|Linux 64-bit]]
@@ Line 22: / Line 21: @@
   * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win32-zip|Windows 32-bit ZIP]]
   * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win32|Windows 32-bit Installer]]
---></html>
 ===== Sample Plugin =====
@@ Line 31: / Line 30: @@
 ===== Using the Firefox Developer Tools =====
-Since Zotero 7 is based on Firefox 102, it's compatible with the [[https://ftp.mozilla.org/pub/firefox/releases/102.15.1esr/|Firefox 102 ESR]] Developer Tools (rather than the Firefox 60 DevTools as before).
+Since Zotero 7 is based on Firefox 115, it's compatible with the [[https://ftp.mozilla.org/pub/firefox/releases/115.9.1esr/|Firefox 115 ESR]] Developer Tools (rather than the Firefox 60 DevTools as before).
 To start a Zotero dev build with the DevTools server, pass the ''-debugger'' flag on the command line:
@@ Line 39: / Line 38: @@
 </code>
-In Firefox 102 ESR, you can then go to about:debugging, add ''localhost:6100'' as a network location, and connect to Zotero. (If you haven't yet, you'll first need to enable the "Enable browser chrome and add-on debugging toolboxes" and "Enable remote debugging" options in the settings of Firefox's Web Developer Tools.)
+In Firefox 115 ESR, you can then go to about:debugging, add ''localhost:6100'' as a network location, and connect to Zotero. (If you haven't yet, you'll first need to enable the "Enable browser chrome and add-on debugging toolboxes" and "Enable remote debugging" options in the settings of Firefox's Web Developer Tools.)
-You should use a separate Firefox profile for 102 ESR and disable automatic updates to prevent Firefox from being automatically updated to an incompatible version.
+You should use a separate Firefox profile for 115 ESR and disable automatic updates to prevent Firefox from being automatically updated to an incompatible version.
 ===== Plugin Changes =====
@@ Line 314: / Line 313: @@
 (''MozXULElement'' will be a property of the window you're modifying.)
+Please ensure that you have inserted the FTL into the window before making any changes to the DOM.
 If adding to an existing window, be sure to remove the ''<link>'' in your plugin's ''shutdown'' function:
@@ Line 526: / Line 527: @@
 <code javascript>
 await Zotero.ItemTreeManager.unregisterColumns(registeredDataKey);
+</code>
+If you encounter any problem with this API, please let us know on the [[https://groups.google.com/g/zotero-dev|dev list]].
+==== Custom Item Pane Sections ====
+The item pane in Zotero 7 has undergone a complete redesign, with the horizontal tabs (Info, Tags, Notes, etc.) replaced by collapsible vertical sections and a side navigation bar for quick access to specific sections.
+A new API in Zotero 7 allows plugins to create custom sections. Plugins should use this official API rather than manually injecting content into the item pane.
+The example below shows how to register a custom section with the item details (e.g., ''id'' and ''editable'') displayed. ''paneID'', ''pluginID'', ''header'', and ''sidenav'' are required.
+<code javascript>
+const registeredID = Zotero.ItemPaneManager.registerSection({
+	paneID: "custom-section-example",
+	pluginID: "example@example.com",
+	header: {
+		l10nID: "example-item-pane-header",
+		icon: rootURI + "icons/16/universal/book.svg",
+	},
+	sidenav: {
+		l10nID: "example-item-pane-header",
+		icon: rootURI + "icons/20/universal/book.svg",
+	},
+	onRender: ({ body, item, editable, tabType }) => {
+		body.textContent
+			= JSON.stringify({
+				id: item?.id,
+				editable,
+				tabType,
+			});
+	},
+});
+</code>
+More advanced options are documented in the [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/itemPaneManager.js|source code]].
+When the plugin is disabled or uninstalled, custom sections with the corresponding ''pluginID'' will be automatically removed. If you want to unregister a custom column manually, you can use ''unregisterSection()'':
+<code javascript>
+Zotero.ItemPaneManager.unregisterSection(registeredID);
 </code>
@@ Line 589: / Line 631: @@
 ===== Other Platform Changes =====
-Mozilla made many other changes between Firefox 60 and Firefox 102 that affect both Zotero code and plugin code, and Zotero 7 includes other API changes as well.
+Mozilla made many other changes between Firefox 60 and Firefox 115 that affect both Zotero code and plugin code, and Zotero 7 includes other API changes as well.
 ==== Mozilla Platform ====
-The following list includes nearly all Mozilla changes that affected Zotero code. You may encounter other breaking changes if you use APIs not used in Zotero. [[https://searchfox.org/|Searchfox]] is the best resource for identifying current correct usage in Mozilla code and changes between Firefox 60 and Firefox 102.
+The following list includes nearly all Mozilla changes that affected Zotero code. You may encounter other breaking changes if you use APIs not used in Zotero. [[https://searchfox.org/|Searchfox]] is the best resource for identifying current correct usage in Mozilla code and changes between Firefox 60 and Firefox 115.
+Earlier Zotero 7 beta releases were based on Firefox 102, so we've listed changes for Firefox 102 and Firefox 115 separately.
+=== Firefox 60 → Firefox 102 ===
   * All ''.xul'' files must be renamed to ''.xhtml''
@@ Line 624: / Line 670: @@
   * Use ''%%native="true"%%'' for native form elements ([[https://github.com/zotero/zotero/commit/89587e6b76e043e74d21bbe713d97fb162215040|example]])
   * ''nsIWebNavigation.loadURI()'' signature change ([[https://github.com/zotero/zotero/commit/abfa09df51cc7a71e34afb77b459a2e24aa64ee4|example]])
-  * ''XPCOMUtils'' → ''ComponentUtils'' for ''generateNSGetFactory'' ([[https://github.com/zotero/zotero/commit/9e9ecc7dcf3a1445e555bab241fc880c8d105263|example]])
   * ''nsILoginManager::findLogins()'' signature change ([[https://github.com/zotero/zotero/commit/f4675c02dffb4f0dcaa668c77ea1318d278fd646|example]])
   * ''nsIURI.clone()'' was removed
@@ Line 632: / Line 677: @@
   * ''Services.console.getMessageArray()'' returns an actual array ([[https://github.com/zotero/zotero/commit/004d5db2c35a83e878e20c98d0118af6755ebbd4|example]])
   * ''OS.Path.join()'' silently drops Number arguments ([[https://github.com/zotero/zotero/commit/f57c462b8588b466f8f95ba8d1c9bc358134763a|example]])
+=== Firefox 102 → Firefox 115 ===
+  * ''OS.File'', ''OS.Path'', and ''OS.Constants.Path'' have been removed in favor of [[https://firefox-source-docs.mozilla.org/dom/ioutils_migration.html|IOUtils]] and [[https://searchfox.org/mozilla-esr115/source/dom/chrome-webidl/PathUtils.webidl|PathUtils]] (which were already available in Firefox 102). To help developers get their code running on 115 as quickly as possible, we've created [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/osfile.mjs|shims]] for most functions, which you can use by adding this line to your files:\\ ''%%var { OS } = ChromeUtils.importESModule("chrome://zotero/content/osfile.mjs");%%''\\ You should update your code to use ''IOUtils'' and ''PathUtils'' as soon as possible rather than relying on these shims long-term. ([[https://github.com/zotero/zotero/commit/920461cd9de098b230c9298015e6c9563123f558|examples]])
+  * UI now uses modern flexbox instead of XUL layout, so Mozilla CSS properties need to be replaced with standard properties (e.g., ''-moz-box-flex: 1'' → ''flex: 1'') and there are various layout differences ([[https://github.com/zotero/zotero/commit/de42dce16ed155b5d180587d965f4745093353ed|example]]; [[https://groups.google.com/a/mozilla.org/g/firefox-dev/c/9sGpF1TNbLk/m/QpU3oTUuAgAJ|details]])
+  * Most Mozilla JSM modules have been renamed to ''.sys.mjs'' and must be imported with ''ChromeUtils.importESModule()'' or ''ChromeUtils.defineESModuleGetters()''
+  * ''nsIPromptService'' → ''Services.prompt'' ([[https://github.com/zotero/zotero/commit/b6a597a7f920e98b22ff369bcadea8d7dc1f09e6|example]])
+  * ''loadURI()'' signature change ([[https://github.com/zotero/zotero/commit/e76c6c6a1a83df3cc9e04129d1c785c28ab57ae4|example]])
+  * ''width'' and ''height'' attributes are no longer recognized on XUL elements (''window'', ''wizard'', ''box'', etc.). Can be replaced with CSS rules (''min-width'', ''width'', ''max-width'', etc.). ([[https://github.com/zotero/zotero/commit/db499fdf2bd51489eaeea1f93f085816f65d5292|example]])
+Additionally, while a Zotero-specific change, the import line for ''FilePicker'' has changed for Firefox 115:\\ ''%%var { FilePicker } = ChromeUtils.importESModule('chrome://zotero/content/modules/filePicker.mjs');%%''
 ==== Zotero Platform =====
@@ Line 637: / Line 694: @@
   * ''tooltiptext'' → ''title'' — works automatically in existing windows; in new windows, requires a [[https://docs.huihoo.com/mozilla/xul/elemref/ref_tooltip.html|XUL <tooltip id="html-tooltip"> element]] and a ''%%tooltip="html-tooltip"%%'' attribute on the ''<window>'' ([[https://github.com/zotero/zotero/commit/d018133e9bf691434e061c1f7f5b093cce09be09|example]])
   * ''Zotero.Browser'' → ''HiddenBrowser.jsm'' — post on dev list for further discussion if you're currently relying on a hidden browser ([[https://github.com/zotero/zotero/commit/6a2949be8a87aebe5ddadd881e4ea22d8b5a8f60|details]])
+  * The import line for ''FilePicker'' has changed:\\ ''%%var { FilePicker } = ChromeUtils.importESModule('chrome://zotero/content/modules/filePicker.mjs');%%''
+  * In an upcoming beta, most PNG icons will be removed or replaced by their SVG versions. You can search for the new icons in ''chrome/skin/default/zotero''.