New official API for custom menu items

[XY Wong]

Hi everyone!

I am glad to announce that the new official API for the custom menu items is ready.

Zotero 8.0-beta.8 adds an API for creating custom menu items in Zotero's menu popups.

More details of this API can be found here: https://www.zotero.org/support/dev/zotero_8_for_developers#custom_menu_items

We will continuously bring more APIs in the future.

[David Hoff-Vanoni]

Thank you for continuing to add new plugin APIs! I've been testing this new menu items API and have some issues and questions.

I copied the example from the linked Z8 documentation page, but I can't get the `onCommand` callback to trigger. The `onShowing`, `onShown`, `onHiding`, and `onHidden` callbacks all trigger as expected. I stepped through with the debugger and saw the call to addEventListener("command" happening, but clicking on the menu item does not trigger the menuCommandListener. Any idea why that may be?

I was trying to determine if I should call `Zotero.MenuManager.registerMenu` from my plugin's `startup` or `onMainWindowLoad` bootstrap functions. Calling it from `startup` seems to work, even after closing and reopening the main Zotero window (on macOS). I still have separate code to load my l10n (ftl) file from `onMainWindowLoad`. Is that the correct approach? I see there's an `l10nFiles` option documented, but it doesn’t seem to be implemented.

I also noticed an error being thrown when shutting down my plugin—see screenshot below. It appears this happens because the call to `super._unregisterByPluginID` does not await the returned promise. This appears to break the menu such that it no longer opens at all.

Thanks!

David

[XY Wong]

Thank you David, there will be a fix soon.

[Emiliano Heyns]

Does the API have a method to control visibility? I don't see it in the announcement or in the source. If so, I'd pitch in a vote to have the method be isVisible rather than isHidden -- I find it lots easier to think about when the menu item is actually applicable than the reverse.

[David Hoff-Vanoni]

There's a setVisible method available in the context provided to your menu item callbacks. I assume it's intended to be called in the `onShowing` callback—which seems to work from my testing—but it'd be good for XY to confirm.

Here's an example:

Zotero.MenuManager.registerMenu({
  menuID: 'test',
  pluginID: 'exa...@example.com',
  target: 'main/library/item',
  menus: [
    {
      menuType: 'menuitem',
      l10nID: 'menu-print',
      onShowing: (event, context) => {
        const visible = Math.random() > 0.5;
        Zotero.debug(`setting visible to: ${visible}`);
        context.setVisible(visible);
      },
    },
  ],
});

[XY Wong]

Yes that's how you are supposed to set the visibility of the menu.

[Emiliano Heyns]

Is it possible to specify light mode/dark mode icons for the menu items?

[XY Wong]

@Emiliano: Yes, you can specify the icon based on the light/dark theme.

https://github.com/zotero/zotero/blob/516d2306472530f89f5989eac1ed313ea11fc182/chrome/content/zotero/xpcom/pluginAPI/menuManager.js#L82-L87

[Emiliano Heyns]

Can I detect that a switch was made from/to dark mode?

[XY Wong]

Yes, but I am wondering why would you need to detect the theme for the menu popop item. You only need to pass the icon and darkIcon and the switch should be automatically handled by Zotero.

[Emiliano Heyns]

I'm using Zotero-plugin-toolkit's MenuManager until 8 is finalized.

--
You received this message because you are subscribed to a topic in the Google Groups "zotero-dev" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/zotero-dev/1svdwA_3GZk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to zotero-dev+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/zotero-dev/c30b5f89-bb84-4e5c-8df4-3b37e6d7c3c7n%40googlegroups.com.

[XY Wong]

An example to listen to the theme change on a window: https://github.com/zotero/zotero/blob/516d2306472530f89f5989eac1ed313ea11fc182/chrome/content/zotero/runJS.js#L121-L126

[Emiliano Heyns]

Does this specifically listen to changes from dark to light? How should I read prefers-color-scheme: dark here?

[XY Wong]

It's this CSS media feature: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme

Here it means listening to changes of if there's a matching media prefers-color-scheme: dark, which triggers the callback whenever the matching result changes (from dark to light or vice versa)

[Emiliano Heyns]

But what is the result put in isDarkMQL for this code

const isDarkMQL = window.matchMedia('(prefers-color-scheme: dark)');

when Zotero starts up in light mode?

[XY Wong]

It should be an media query object (https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList). You may want to check it's`matches` property https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList/matches.

[Emiliano Heyns]

So it doesn't matter whether you have

const isDarkMQL = window.matchMedia('(prefers-color-scheme: dark)');

or

const isDarkMQL = window.matchMedia('(prefers-color-scheme: light)');

?

[XY Wong]

The value of property `matches` differs, while you can use both to listen to theme changing.

[XY Wong]

Update: in the latest beta (8.0-beta.10), the above-mentioned issues should be addressed. Thank you for the feedback.

[Wy yw]

I'm currently working on transitioning my add-on to the new menu API. Some things:

1. What is the best way to update the menu items after registering them? Currently what I have implemented is unregistering and re-registering to add/remove menu items, but this seems inefficient.

2. At least on MacOS, if you are right-clicking to open the context menu while the main Zotero pane is in the background (for example, when the error console or pref window is focused), the menu item oncommand doesn't seem to trigger on click. What's the best way around this?

This is on 8.0-beta.19+b9ef88d4f.

[XY Wong]

> 1. What is the best way to update the menu items after registering them? Currently what I have implemented is unregistering and re-registering to add/remove menu items, but this seems inefficient.

Please consider using the onShowing hook [1] to update the locale/icon/hidden with helpers passed to the hook [2]. You should not register and unregister to update menus.

> 2. At least on MacOS, if you are right-clicking to open the context menu while the main Zotero pane is in the background (for example, when the error console or pref window is focused), the menu item oncommand doesn't seem to trigger on click. What's the best way around this?

We need the minimal code to reproduce in order to help.

[1] https://github.com/zotero/zotero/blob/49325e27d9b76094ea83e9106746ef8fbe198593/chrome/content/zotero/xpcom/pluginAPI/menuManager.js#L93

[2] https://github.com/zotero/zotero/blob/49325e27d9b76094ea83e9106746ef8fbe198593/chrome/content/zotero/xpcom/pluginAPI/menuManager.js#L574-L603