Preferences: Restore Help button (#2803)

Having the macOS Help button in a scrolling view feels kind of weird, but that's
what Apple is doing in the Ventura System Settings app, so I guess we go with
it. I like it better than Firefox's non-contextual "Firefox Support" button
under the pane list in their preferences, anyway - having pane-by-pane
contextual help buttons seems like good UX that there isn't a good reason for us
to ditch.

chrome/content/zotero-platform/mac/preferences.css

@@ -18,3 +18,8 @@ groupbox > label > h2, groupbox > * > label > h2, caption {
 	padding-bottom: 0.2em;
 	font: caption;
 }
+
+.help-button {
+	appearance: auto;
+	-moz-default-appearance: -moz-mac-help-button;	
+}

chrome/content/zotero/preferences/preferences.js

@@ -34,6 +34,7 @@ var Zotero_Preferences = {
 		this._observerSymbols = [];
 		this.navigation = document.getElementById('prefs-navigation');
 		this.content = document.getElementById('prefs-content');
+		this.helpContainer = document.getElementById('prefs-help-container');
 
 		this.navigation.addEventListener('select', () => this._onNavigationSelect());
 		document.getElementById('prefs-search').addEventListener('command',
@@ -64,7 +65,8 @@ var Zotero_Preferences = {
 		this.navigation.replaceChildren();
 		let contentScrollTop = this.content.scrollTop;
 		let contentScrollLeft = this.content.scrollLeft;
-		this.content.replaceChildren();
+		// Remove all children besides the help container
+		this.content.replaceChildren(this.helpContainer);
 		
 		Zotero.PreferencePanes.builtInPanes.forEach(pane => this._addPane(pane));
 		if (Zotero.PreferencePanes.pluginPanes.length) {
@@ -140,13 +142,10 @@ var Zotero_Preferences = {
 	},
 
 	openHelpLink: function () {
-		// TODO: Re-add help and update this for new preferences architecture
-
-		var url = "http://www.zotero.org/support/preferences/";
-		var helpTopic = document.getElementsByTagName("prefwindow")[0].currentPane.helpTopic;
-		url += helpTopic;
-
-		Zotero.launchURL(url);
+		let helpURL = this.panes.get(this.navigation.value)?.helpURL;
+		if (helpURL) {
+			Zotero.launchURL(helpURL);
+		}
 	},
 
 	/**
@@ -167,7 +166,9 @@ var Zotero_Preferences = {
 
 	_onNavigationSelect() {
 		for (let child of this.content.children) {
-			child.setAttribute('hidden', true);
+			if (child !== this.helpContainer) {
+				child.setAttribute('hidden', true);
+			}
 		}
 		let paneID = this.navigation.value;
 		if (paneID) {
@@ -197,6 +198,8 @@ var Zotero_Preferences = {
 	 * 		whitespace-only text nodes are ignored, XUL is the default namespace, and HTML tags are
 	 * 		namespaced under `html:`. Default behavior is the opposite: whitespace nodes are preserved,
 	 * 		HTML is the default namespace, and XUL tags are under `xul:`.
+	 * @param {String} [options.helpURL] If provided, a help button will be displayed under the pane
+	 * 		and the provided URL will open when it is clicked
 	 */
 	_addPane(options) {
 		let { id, parent, label, rawLabel, image } = options;
@@ -234,7 +237,7 @@ var Zotero_Preferences = {
 
 		let container = document.createXULElement('vbox');
 		container.hidden = true;
-		this.content.append(container);
+		this.helpContainer.before(container);
 
 		this.panes.set(id, {
 			...options,
@@ -395,11 +398,15 @@ ${str}
 			if (this.navigation.selectedIndex == -1) {
 				this.navigation.selectedIndex = 0;
 			}
+			this.helpContainer.hidden = !this.panes.get(this.navigation.value)?.helpURL;
 			return;
 		}
 
 		// Clear pane selection
 		this.navigation.clearSelection();
+		
+		// Don't show help button when searching
+		this.helpContainer.hidden = true;
 
 		// Make sure all panes are loaded into the DOM and show top-level ones
 		for (let [id, pane] of this.panes) {

chrome/content/zotero/preferences/preferences.xhtml

@@ -92,7 +92,15 @@
 				</hbox>
 				<search-textbox id="prefs-search" placeholder="&zotero.lookup.button.search;" timeout="1"/>
 			</hbox>
-			<vbox id="prefs-content" flex="1"/>
+			<vbox id="prefs-content" flex="1">
+				<hbox id="prefs-help-container" pack="end">
+					<button
+						oncommand="Zotero_Preferences.openHelpLink()"
+						label="&zotero.preferences.helpButton.label;"
+						class="help-button" 
+						align="end"/>
+				</hbox>
+			</vbox>
 		</vbox>
 	</hbox>
 </window>

chrome/content/zotero/xpcom/preferencePanes.js

@@ -35,6 +35,7 @@ Zotero.PreferencePanes = {
 			src: 'chrome://zotero/content/preferences/preferences_general.xhtml',
 			scripts: ['chrome://zotero/content/preferences/preferences_general.js'],
 			defaultXUL: true,
+			helpURL: 'https://www.zotero.org/support/preferences/general',
 		},
 		{
 			id: 'zotero-prefpane-sync',
@@ -43,6 +44,7 @@ Zotero.PreferencePanes = {
 			src: 'chrome://zotero/content/preferences/preferences_sync.xhtml',
 			scripts: ['chrome://zotero/content/preferences/preferences_sync.js'],
 			defaultXUL: true,
+			helpURL: 'https://www.zotero.org/support/preferences/sync',
 		},
 		{
 			id: 'zotero-prefpane-export',
@@ -51,6 +53,7 @@ Zotero.PreferencePanes = {
 			src: 'chrome://zotero/content/preferences/preferences_export.xhtml',
 			scripts: ['chrome://zotero/content/preferences/preferences_export.js'],
 			defaultXUL: true,
+			helpURL: 'https://www.zotero.org/support/preferences/export',
 		},
 		{
 			id: 'zotero-prefpane-cite',
@@ -59,6 +62,7 @@ Zotero.PreferencePanes = {
 			src: 'chrome://zotero/content/preferences/preferences_cite.xhtml',
 			scripts: ['chrome://zotero/content/preferences/preferences_cite.js'],
 			defaultXUL: true,
+			helpURL: 'https://www.zotero.org/support/preferences/cite',
 		},
 		{
 			id: 'zotero-prefpane-advanced',
@@ -67,6 +71,7 @@ Zotero.PreferencePanes = {
 			src: 'chrome://zotero/content/preferences/preferences_advanced.xhtml',
 			scripts: ['chrome://zotero/content/preferences/preferences_advanced.js'],
 			defaultXUL: true,
+			helpURL: 'https://www.zotero.org/support/preferences/advanced',
 		},
 		{
 			id: 'zotero-subpane-reset-sync',
@@ -75,6 +80,7 @@ Zotero.PreferencePanes = {
 			src: 'chrome://zotero/content/preferences/preferences_sync_reset.xhtml',
 			scripts: ['chrome://zotero/content/preferences/preferences_sync.js'],
 			defaultXUL: true,
+			helpURL: 'https://www.zotero.org/support/preferences/sync#reset',
 		}
 	]),
 
@@ -99,6 +105,8 @@ Zotero.PreferencePanes = {
 	 * 		If not provided, the plugin's icon (from manifest.json) is used
 	 * @param {String[]} [options.extraDTD] Array of URIs of DTD files to use for parsing the XHTML fragment
 	 * @param {String[]} [options.scripts] Array of URIs of scripts to load along with the pane
+	 * @param {String[]} [options.helpURL] If provided, a help button will be displayed under the pane
+	 * 		and the provided URL will open when it is clicked
 	 * @return {Promise<String>} Resolves to the ID of the pane if successfully added
 	 */
 	register: async function (options) {
@@ -120,6 +128,7 @@ Zotero.PreferencePanes = {
 			extraDTD: options.extraDTD,
 			scripts: options.scripts,
 			defaultXUL: false,
+			helpURL: options.helpURL,
 		};
 
 		this.pluginPanes.push(addPaneOptions);

chrome/locale/en-US/zotero/preferences.dtd

@@ -1,5 +1,7 @@
 <!ENTITY zotero.preferences.title						"Zotero Preferences">
 
+<!ENTITY zotero.preferences.helpButton.label "Help">
+
 <!ENTITY zotero.preferences.default					"Default:">
 <!ENTITY zotero.preferences.items						 "items">
 <!ENTITY zotero.preferences.period						 ".">

chrome/skin/default/zotero/preferences.css

@@ -1,6 +1,7 @@
 #prefs-content {
 	min-height: 600px;
 	overflow-y: scroll;
+	padding-bottom: 10px;
 }
 
 #prefs-content > * {