NPM Package: Zotero Plugin Toolkit

[XY Wong]

Hi, plugin developers,

I've released a new NPM package: Zotero Plugin Toolkit(zotero-plugin-toolkit - npm (npmjs.com)), which used to be the utils part of the Zotero Addon Template(https://github.com/windingwind/zotero-addon-template) for easier integration.

For example, if you want to make your bootstrapped plugin register preference pane in both Zotero 6 and 7, you only need to:

All APIs are with type hints and comments/examples:

The API documentation are here: zotero-plugin-toolkit/zotero-plugin-toolkit.md at master · windingwind/zotero-plugin-toolkit (github.com)

If you have any suggestions or you need any APIs, welcome issues and pull requests!

Best,

[XY Wong]

Update: The toolkit now provides a new API to easily register and unregister new item tree columns, tested on both Zotero 6 and 7.

Looks like(Windows, Zotero 7 beta):

I borrow the patchy way Better Bibtex and Scite use in overlay plugins. However, this does not work in bootstrapped plugins, as they can be enabled/disabled anytime. The fixes are in the refresh() method.

The documentation: zotero-plugin-toolkit/zotero-plugin-toolkit.itemtreetool.md at 83ef3ecf0aa26292036e5af58cdf1db09ca98388 · windingwind/zotero-plugin-toolkit (github.com)

[volatile static]

I think it's really a charming work that customizing columns with single function!

This NPM package have greatly improved the efficiency of our plugin development.

I'm going to transplant my plug-in into your template.

Thanks a lot~

[Emiliano Heyns]

Monkey patches can be disabled at runtime (have been for a while in prep for bootstrapped): https://github.com/retorquere/zotero-better-bibtex/blob/master/content/monkey-patch.ts

[XY Wong]

Thanks to the great BBT plugin author @Emiliano, I borrowed the monkey patches from your plugin.

Mentioning the patchy way of adding a column, some more details might be helpful:

The fixes I mentioned above are to refresh itemsView outside the Zotero loading stage. I found it is not possible to directly call `refreshAndMaintainSelection`, there are extra steps you need to do:

1. ZoteroPane.itemsView._columnsId = null;

Reset the _columnsId to force update _cloumns, otherwise the new columns are not updated in the itemTree._getColumns()

2. document

      .querySelector(`.${ZoteroPane.itemsView.tree._columns._styleKey}`)

      ?.remove();

Remove the styles so they can be re-initialized later.

3. await ZoteroPane.itemsView.refreshAndMaintainSelection();

4. ZoteroPane.itemsView.tree._columns =

      new ZoteroPane.itemsView.tree._columns.__proto__.constructor(

        ZoteroPane.itemsView.tree

      );

Reload virtualized-table to force update new columns in the itemView.tree._columns._columns.

This is what's happening in the toolkit's ItemTreeTool.refresh(). See https://github.com/windingwind/zotero-plugin-toolkit/blob/108c2d4cc5a1bcde56a10d24a1978cc8a9ab78a4/src/treeView.ts#L319-L339

I think this also explains some loading failures you mentioned in related issues and group discussions that extra columns disappear mysteriously. Overlay plugins do this at the loading stage where ZoteroPane is not yet fully initialized and when the patch is delayed, users suffer this missing columns bug.

This is just a theory of my own though. What proved to be true is these steps work for me and without them, it doesn't work for a bootstrapped plugin.

To be honest, I don't like/even hate the patchy way and am always trying to minimize it in plugin development. However, I have to use it to add a column. One thing we can do is to share a global patch, rather than patch it in every plugin: that's what the toolkit does.

@Emiliano are you interested in this toolkit? BBT is very influential in the community, and influences and encourages many young plugin developers. We could together make the code segmentations into a public lib and make plugin development more easily, which is also a benefit for us when maintaining plugins. 

Some friends and I are trying to bring a better experience to plugin development, as we all suffer from the lacking of documentation (now we have one, step-by-step guidance doc, in Chinese); the lacking type hints, which forces us to dive very deep into the Zotero source code (now we have a zotero-types definition lib, almost covers all APIs that developers concerns); the lacking public tools and plugins APIs (now we are going to have one, which is this one Zotero Plugin Toolkit).

[Emiliano Heyns]

On Friday, December 23, 2022 at 3:24:33 PM UTC+1 wyz...@foxmail.com wrote:

To be honest, I don't like/even hate the patchy way and am always trying to minimize it in plugin development. However, I have to use it to add a column. One thing we can do is to share a global patch, rather than patch it in every plugin: that's what the toolkit does.

It is usually better if monkey patches are avoided, but BBT would not have been/is not currently possible without them.

@Emiliano are you interested in this toolkit? BBT is very influential in the community, and influences and encourages many young plugin developers. We could together make the code segmentations into a public lib and make plugin development more easily, which is also a benefit for us when maintaining plugins. 

 

I'm interested, but I can't join or follow discussions in Chinese.

Not something that needs immediate action, but at some point I'd need commit access; if I have an urgent problem that requires changes to this lib I need to a able to fix it without having to wait out timezone differences. For the same reason I think it'd be good to automate npm publishing through a github action.

[XY Wong]

Hi,  Emiliano,

>   but I can't join or follow discussions in Chinese.

We all can sanpeak English. Language shouldn't be a big problem.

Maybe we could discuss in Discussions · windingwind/zotero-plugin-toolkit (github.com) about the long-term planning of this package? Like, new APIs, suggestions, etc.

>  I'd need commit access

>  I think it'd be good to automate npm publishing through a github action.

Yes, thanks for these suggestions. I'll set up the action and invite you into this repo later.

Happy Christmas!

[XY Wong]

@Emiliano,  I've set up the GitHub action to release the NPM package. Only tagged pushes trigger the action. An invitation is sent!