New official API for custom columns in the item tree

[XY Wong]

Hi everyone!

I am glad to announce that the new official API for custom columns in the item tree is ready.

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).

If you were previously using monkey-patching to add custom columns in Zotero 6, please switch to using the official API in Zotero 7.

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

I started working on the plugin ecosystem as one of the Zotero team since May 2023. This API is our first step to make developing plugins more easy. Please let us know if you encounter any problems with this API. We will continuously bring more APIs in the future.

Best,

Xiangyu

[Emiliano Heyns]

That's a great mechanism - could we have such automatic removal for document elements, notifier listeners and idle listeners also? 

[XY Wong]

@Emiliano Heyns

Thanks. I'm afraid we won't support automatic removal for elements. You may need to implement yourself, or use third-party lib (e.g. plugin-toolkit, but do not rely on them too much).

Other listeners do not support auto-removal yet, and even if we want them to, it might not be now. I have many other new APIs to work on before enhancing the existing ones.

[Emiliano Heyns]

That's OK, I have my own mechanisms, but this autoremoval made one of them superfluous, might as well see if others could go too :) 

[iseexuhs]

Hello, I tried this new API.

I can succeed to add a new custom column by using the API, but it seems the added column fails to be removed by using the command "await Zotero.ItemTreeManager.unregisterColumns(registeredDataKey);", and it always returns false, but not true as the Zotero source code tells.

Please help check it. Thanks a lot.

[XY Wong]

We need the source code that can reproduce your problem.

[iseexuhs]

  const registeredDataKey = await Zotero.ItemTreeManager.registerColumns({
      dataKey: 'translateTitle',
      label: '标题翻译',
      pluginID: 'make-...@zotero.org',
      dataProvider: (item, dataKey) => {
          return item.getField('shortTitle');
      },
  });
 
  await Zotero.ItemTreeManager.unregisterColumns('translateTitle');

[XY Wong]

Nop. This is not how the API should be called: Use await Zotero.ItemTreeManager.unregisterColumns(registeredDataKey);

as you mentioned.

在2023年8月3日星期四 UTC+8 10:13:29<iseexuhs> 写道：

[XY Wong]

And, you do not need to call it manually to unregister the columns, if you have pluginID set correctly.
Zotero will remove all the plugin's columns when the plugin is disabled.

[iseexuhs]

I checked the source code, If run above codes,  registeredDataKey in the "const registeredDataKey.. " should get true or false.

So, 'await Zotero.ItemTreeManager.unregisterColumns(registeredDataKey) ' is not reasonable. 

Also, the source code also tells to use ''await Zotero.ItemTreeManager.unregisterColumns('translateTitle');"

It is very confusing.

在2023年8月3日星期四 UTC+8 10:23:33<XY Wong> 写道：

[iseexuhs]

My purpose it to unregister the added column instantly, I mean without restart.

For now, I can't not seen anything happen by running the ''unregisterColumns" API. The column can not be removed instantly.

[XY Wong]

1. It's reasonable. We will prefix the dataKey, which is `translateTitle` in your case, to avoid conflicts between plugins. The actually registered `dataKey` is something like `make-it-red-zotero-org-translateTitle` in your case, which is the one you get from the return of `registerColumns`.

2. registerColumns returns a string, or an array of strings, on success and returns false on fail.

3. It is a common behavior to unregister something with the return of the register call, e.g. addEventListener.

[XY Wong]

*addEventListener -> Zotero.Notifier.registerObserver

[iseexuhs]

Ok, it succeeds. As you say, the  code annotation 'Zotero.ItemTreeManager.unregisterColumns('rtitle');' in the Zotero source code should be fixed to avoid confusion.

Thanks a lot.

在2023年8月3日星期四 UTC+8 10:45:15<XY Wong> 写道：

[XY Wong]

We now offer support for custom cell rendering in the latest Zotero 7 beta, with an example available in the source code accessible at https://github.com/zotero/zotero/blob/e1def9971c18999b0e0bb127fa3f2cb1ccd59d5f/chrome/content/zotero/xpcom/itemTreeManager.js#L91-L101.

[Emiliano Heyns]

But this is optional, right? If I just provide dataProvider and not renderCell it still gets displayed?

[XY Wong]

Yes of course. Displaying a citation key or some plain-text content does not need that.

[Emiliano Heyns]

Will this API also work for the item viewer in the PDF display tab?

[XY Wong]

Theoretically, it works for every item tree. If you find it not working with any of them, let me know and I'll do a fix.