Differences

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

--- dev:zotero_7_for_developers [2024/05/23 08:37] – [Dev Builds] dstillman
+++ 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 30: / Line 32: @@
 ===== Using the Firefox Developer Tools =====
-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).
+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.
-To start a Zotero dev build with the DevTools server, pass the ''-debugger'' 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>
-$ /Applications/Zotero\ Dev.app/Contents/MacOS/zotero -ZoteroDebugText -jsconsole -debugger
+$ /Applications/Zotero\ Beta.app/Contents/MacOS/zotero -ZoteroDebugText -jsdebugger
 </code>
-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.)
+When running Zotero from source, passing ''-d'' flag to the [[dev:client_coding/building_the_desktop_app#helper_script|build_and_run script]] will rebuild (''-r'') with the devtools included and pass ''-jsdebugger''.
-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 213: / 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 274: / 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 468: / Line 468: @@
 </code>
-Organizing your pane as a sequence of top-level ''<groupbox>''es inside a ''<vbox>'' will optimize it for the new preferences search mechanism. By default, all text in the DOM is searchable. If you want to manually add keywords to an element (for example, a button that opens a dialog), set its ''data-search-strings-raw'' property to a comma-separated list.
+Organizing your pane as a sequence of top-level ''<groupbox>''es ' will optimize it for the new preferences search mechanism. By default, all text in the DOM is searchable. If you want to manually add keywords to an element (for example, a button that opens a dialog), set its ''data-search-strings-raw'' property to a comma-separated list.
 To use Fluent for [[#localization|localization]], include one or more HTML ''<link>'' elements within a XUL ''<linkset>'':
@@ Line 504: / 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 511: / Line 511: @@
 <code javascript>
-const registeredDataKey = await Zotero.ItemTreeManager.registerColumns({
+const registeredDataKey = await Zotero.ItemTreeManager.registerColumn({
     dataKey: 'rtitle',
     label: 'Reversed Title',
@@ Line 521: / 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 562: / 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 571: / 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 631: / 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 689: / 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 =====