Differences

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

--- dev:zotero_7_for_developers [2024/09/10 09:02] – [Preference Panes] do not recommend wrapping top-level groupboxes inside vbox xiangyu
+++ dev:zotero_7_for_developers [2025/02/02 06:38] (current) – [XUL Overlays → bootstrap.js] dstillman
@@ 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 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.
+Zotero 7 includes a major internal upgrade of the Mozilla platform on which Zotero is based, incorporating changes from Firefox 60 through Firefox 115, and an upcoming version will be based on Firefox 128. 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> 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.--></HTML>
+<html><span style="color: red; font-weight: bold">WARNING:</span></html> These are test builds based on Firefox 128 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><!--  * [[https://www.zotero.org/download/client/dl?channel=dev&platform=mac|Mac]]
+<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]]
   * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win-x64-zip|Windows 64-bit ZIP]]
   * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win-x64|Windows 64-bit Installer]]
+  * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win-arm64-zip|Windows ARM64 ZIP]]
+  * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win-arm64|Windows ARM64 Installer]]
   * [[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]]
+  * [[https://www.zotero.org/download/client/dl?channel=dev&platform=win32|Windows 32-bit Installer]]--></HTML>
---></HTML>
 ===== Sample Plugin =====
@@ Line 32: / Line 34: @@
 Since Zotero is based on Firefox, it's possible to use the Firefox Developer Tools to interact with the DOM, set code breakpoints, follow network requests, and more.
-Zotero 7 beta builds include the Firefox 115 devtools. To start a beta build with the Browser Toolbox open, pass the ''-jsdebugger'' flag on the command line:
+Zotero 7 beta builds include the Firefox 128 devtools. To start a beta build with the Browser Toolbox open, pass the ''-jsdebugger'' flag on the command line:
 <code>
@@ Line 211: / Line 213: @@
 Note that Zotero 6 provides a ''resourceURI'' nsIURI object instead of a ''rootURI'' string, so for Zotero 6 compatibility you'll want to assign ''resourceURI.spec'' to ''rootURI'' if ''rootURI'' isn't provided.
-In Zotero 7, the ''install()'' and ''startup()'' bootstrap methods are called only after Zotero has initialized, and the ''Zotero'' object is automatically made available in the bootstrap scope, along with ''Services'', ''Cc'', ''Ci'', and other Mozilla and browser objects. This isn't the case in Zotero 6, in which these functions can load before the ''Zotero'' object is available and won't automatically get ''window'' properties such as ''URL''. (''Zotero'' also isn't available in ''uninstall()'' in Zotero 6.) The sample plugin provides an example of [[https://github.com/zotero/make-it-red/blob/main/src-1.2/bootstrap.js|waiting for availability of the ''Zotero'' object]] and [[https://github.com/zotero/make-it-red/blob/main/src-1.2/lib.js|importing global properties]] in a bootstrapped plugin that works in both Zotero 6 and 7.
+In Zotero 7, the ''install()'' and ''startup()'' bootstrap methods are called only after Zotero has initialized, and the ''Zotero'' object is automatically made available in the bootstrap scope, along with ''Services'', ''Cc'', ''Ci'', and other Mozilla and browser objects. This isn't the case in Zotero 6, in which these functions can load before the ''Zotero'' object is available and won't automatically get ''window'' properties such as ''URL''. (''Zotero'' also isn't available in ''uninstall()'' in Zotero 6.) The sample plugin provides an example of [[https://github.com/zotero/make-it-red/blob/main/src-1.2/bootstrap.js|waiting for availability of the ''Zotero'' object]] and [[https://github.com/zotero/make-it-red/blob/main/src-1.2/make-it-red.js|importing global properties]] in a bootstrapped plugin that works in both Zotero 6 and 7.
 Bootstrapped plugins can be disabled or uninstalled without restarting Zotero, so you'll need to make sure you remove all functionality in the ''shutdown()'' function.
@@ Line 272: / Line 274: @@
 ==== Localization ====
-Mozilla has introduced a new localization system called [[https://projectfluent.org/|Fluent]], which replaces both .dtd and .properties localization. While both .dtd and .properties are still supported in the current version of Zotero 7, Mozilla has removed .dtd files completely in Firefox 115, which will be the basis for an upcoming version of Zotero, and is working to remove uses of .properties files. To ensure future compatibility, plugin authors should aim to use Fluent for localization going forward.
+Mozilla has introduced a new localization system called [[https://projectfluent.org/|Fluent]], which replaces both .dtd and .properties localization. While both .dtd and .properties are still supported in the current version of Zotero 7, Mozilla has removed .dtd files completely in Firefox 115 and is working to remove uses of .properties files. To ensure future compatibility, plugin authors should aim to use Fluent for localization going forward.
 See the [[https://projectfluent.org/fluent/guide/|Fluent Syntax Guide]] for more information on creating Fluent files.
@@ Line 502: / Line 504: @@
 ==== Custom Item Tree Columns ====
-Zotero 7 beta 23 adds an API for creating custom columns in the item tree. The item tree is widely used in Zotero for displaying a table of items (e.g., the items list in the main library view and the search results in the Advanced Search window).
+Zotero 7 adds an API for creating custom columns in the item tree. The item tree is widely used in Zotero for displaying a table of items (e.g., the items list in the main library view and the search results in the Advanced Search window).
 If you were previously using monkey-patching to add custom columns in Zotero 6, please switch to using the official API in Zotero 7.
@@ Line 509: / Line 511: @@
 <code javascript>
-const registeredDataKey = await Zotero.ItemTreeManager.registerColumns({
+const registeredDataKey = await Zotero.ItemTreeManager.registerColumn({
     dataKey: 'rtitle',
     label: 'Reversed Title',
@@ Line 519: / Line 521: @@
 </code>
-More advanced options are documented in the [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/itemTreeManager.js|source code]].
+More advanced options are documented in the [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/pluginAPI/itemTreeManager.js|source code]].
-When the plugin is disabled or uninstalled, custom columns with the corresponding ''pluginID'' will be automatically removed. If you want to unregister a custom column manually, you can use ''unregisterColumns()'':
+When the plugin is disabled or uninstalled, custom columns with the corresponding ''pluginID'' will be automatically removed. If you want to unregister a custom column manually, you can use ''unregisterColumn()'':
 <code javascript>
-await Zotero.ItemTreeManager.unregisterColumns(registeredDataKey);
+await Zotero.ItemTreeManager.unregisterColumn(registeredDataKey);
 </code>
@@ Line 560: / Line 562: @@
 </code>
-More advanced options are documented in the [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/itemPaneManager.js|source code]].
+More advanced options are documented in the [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/pluginAPI/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()'':
@@ Line 569: / Line 571: @@
 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 Info Section Rows ====
+A new API allows plugins to create custom sections. Plugins should use this official API rather than manually injecting content into the item pane's info section.
+The example below shows registering a custom row, which displays the reversed title of the item.
+<code javascript>
+const registeredID = Zotero.ItemPaneManager.registerInfoRow({
+	rowID: "custom-info-row-example",
+	pluginID: "example@example.com",
+	label: {
+		l10nID: "general-print",
+	},
+	position: "afterCreators",
+	multiline: false,
+	nowrap: false,
+	editable: true,
+	onGetData({ rowID, item, tabType, editable }) {
+		return item.getField("title").split("").reverse().join("");
+	},
+	onSetData({ rowID, item, tabType, editable, value }) {
+		Zotero.debug(`Set custom info row ${rowID} of item ${item.id} to ${value}`);
+	}
+});
+</code>
+More advanced options are documented in the [[https://github.com/zotero/zotero/blob/main/chrome/content/zotero/xpcom/pluginAPI/itemPaneManager.js|source code]].
+When the plugin is disabled or uninstalled, custom rows with the corresponding ''pluginID'' will be automatically removed. If you want to unregister a custom row manually, you can use ''unregisterInfoRow()'':
+<code javascript>
+Zotero.ItemPaneManager.unregisterInfoRow(registeredID);
+</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 Reader Event Handlers ====
-Zotero 7 beta 40 adds an API for creating custom reader event handlers. Available event types are:
+Zotero 7 adds an API for creating custom reader event handlers. Available event types are:
   * ''renderTextSelectionPopup'': inject DOM event, triggered when the selection popup is rendered
@@ Line 629: / Line 669: @@
 ===== Other Platform Changes =====
-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 made many other changes between Firefox 60 and Firefox 128 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 115.
+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 128.
-Earlier Zotero 7 beta releases were based on Firefox 102, so we've listed changes for Firefox 102 and Firefox 115 separately.
+Earlier Zotero 7 beta releases were based on Firefox 102, so we've listed changes for Firefox 102, 115, and 128 separately.
 === Firefox 60 → Firefox 102 ===
@@ Line 687: / Line 727: @@
 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');%%''
+=== Firefox 115 → Firefox 128 ===
+  * Manual ''Services.jsm'' imports must be removed ([[https://github.com/zotero/zotero/commit/97329752a1839210d636b7b8d37deae854d42410|example]])
+  * ''nsIScriptableUnicodeConverter'' was removed; replace ''convertToByteArray()'' and ''convertToInputStream()'' ([[https://github.com/zotero/zotero/commit/24bf583b787d21117000336e4f67ddc9ac7b1deb|example]])
+  * ''nsIOSFileConstantsService'' was removed ([[https://github.com/zotero/zotero/commit/7f619e3fe3044ea968a9bd0fb31d98f45d5cb75b|example]])
+  * ''XPCOMUtils.defineLazyGetter'' → ''ChromeUtils.defineLazyGetter'' ([[https://github.com/zotero/zotero/commit/9606fca3ad39a52d29d0c74ae96fb680c14ad4e3|example]])
+  * ''nsIDOMChromeWindow'' was removed ([[https://github.com/zotero/zotero/commit/45e681431bfd6b77bfaf8f55ce87f04fedb4a475|example]])
+  * Login manager: ''addLogin'' → ''addLoginAsync'' ([[https://github.com/zotero/zotero/commit/fa2073335342f5f8f067b0e2cad12611012bcab5|example]])
+  * ''BrowsingContext'' should be passed to ''nsIFilePicker'' init ([[https://github.com/zotero/zotero/commit/72b56e7a592a6793817e2a7479b08b6f2e334252|example]], but we recommend using Zotero's ''FilePicker'' module instead)
+  * ''DataTransfer#types'': ''contains()'' → ''includes()'' — now a standard array ([[https://github.com/zotero/zotero/commit/f28fa763ccfc5aac4575c1a2b28f532d84c89bf2|example]])
+  * ''-moz-nativehyperlinktext'' → ''LinkText'' ([[https://github.com/zotero/zotero/commit/b85864595754fe54ae841902df2e4f3276a7574f|example]])
 ==== Zotero Platform =====