Custom user plugin [fix #574]

[Edouard2laire]

Hello,

As discussed here: https://github.com/brainstorm-tools/brainstorm3/issues/574 , this allows the usage of custom plugins that are not officially supported in Brainstorm. This can be used to share processes within a lab by having a common GitHub repository and having that repo as a custom plugin in Brainstorm.

This is done by defining the customs plugin in specific JSON files under the .brainstorm folder. Each json can contain one or multiple plugins (although one plugin per json might be better as recommended by Francois)

Here is an example of plugins.json file with 2 plugin definition: plugins.json

Splitted into two files:

plugin_bids_matlab.json plugin_bst_users.json

The creation of the JSON file can be a bit tedious and prone to error but this is just the first PR to get feedback and we might improve the addition of a plugin in that json file later :) As you suggested, made json file could easily be shared in the bst_plugin repo.

Edouard

[Hs: i cant believe i posted that issue in 2022]

TODOs

• [x] Update plugin menu without restarting Brainstorm
• [x] Add user-defined plugins with URL
• [x] Add user-defined plugins with file
• [x] Add user-defined plugins manually (user input)
• [x] Remove user-defined plugins
• [x] Tests with archiving
• [x] Tests with deploy
• [x] Documentation

[rcassani]

Can we save the user from creating the json file?

If the scripts to be shared are a public repo, and they are thought to be used as Brainstorm processes. This can work as:

1. An option in the GUI. Plugin > Add from URL
2. User provides the URL to the repo (may branch as well)
3. The repo is downloaded
4. Brainstorm checks for the json file in it
5. If the json file exists the plugin gets added following those instructions

[Edouard2laire]

Can we save the user from creating the json file?

yes, I just wanted to make sure you were still ok with the idea since it is from 2022 before working on the user-friendly part :)

If the scripts to be shared are a public repo, and they are thought to be used as Brainstorm processes. This can work as:

1. An option in the GUI. Plugin > Add from URL
2. User provides the URL to the repo (may branch as well)
3. The repo is downloaded
4. Brainstorm checks for the json file in it
5. If the json file exists the plugin gets added following those instructions

Seems like a good plan, and if the json file doesn't exist then we ask the user to fill it being extra cautious. I would also add the option to Add directly from json in addition to the URL from step 1. I will add that to the current PR and ping you when ready. (hopefully before 2026 :D)

Edit: the only thing I don't necessarily like with the add from URL is that we might end up downloading each plugin twice : one to get the .json and then to actually download the plugin.

[rcassani]

We can retrieve only the .json file, something like this:

text = bst_webread('https://raw.githubusercontent.com/brainstorm-tools/brainstorm3/master/README.md');

[Edouard2laire]

Here is a first implementation. The following code is adding the plugin in the .brainstorm folder.

bst_plugin('AddCustom','https://github.com/Edouard2laire/bst-users/blob/custom_plugin/plugins/plugin_bids_matlab.json')

Is there a way to update the plugin menu without starting brainstorm again ?

[Edouard2laire]

ok . This is ready to be reviewed. The only issue is that when adding a new plugin, brainstorm needs to be restarted to update the menu.

[Edouard2laire]

is there any news for that PR by any chance ? :)

[rcassani]

Just started with it

[rcassani]

@Edouard2laire, I'm still working on this PR. Meanwhile, what do you think on deleting the json file (in the plugin dir) when uninstall a 'User defined' plugin? I think it makes sense, as if they are not needed for the moment, they can be unloaded. Otherwise, a method to delete the json files would be needed.

[Edouard2laire]

@Edouard2laire, I'm still working on this PR. Meanwhile, what do you think on deleting the json file (in the plugin dir) when uninstall a 'User defined' plugin? I think it makes sense, as if they are not needed for the moment, they can be unloaded. Otherwise, a method to delete the json files would be needed.

yes, I think that make sense too. Users can easily add back the plugin if they want.

[rcassani]

yes, I think that make sense too. Users can easily add back the plugin if they want.

It looked as a good idea, but now it is quite asymmetric. "Add", just adds, Install is needed 'Uninstall', uninstalls and deletes the json file

I'll add the option of remove the custom plugin:

• Add > Install
• Uninstall > Remove (with remove uninstalling if needed)

[Edouard2laire]

Wow it looks great! thanks a lot. (sorry I didn't realize there was so much code left to write)

For the addition of new plugin, do we need to have 3 options ( file, URL, and manual)? I have the feeling that the file and URL would already cover most of the options.

[rcassani]

Wanted to add the manual, as a way to start create a basic .json without having to type it.

In addition, documentation is needed for this new feature. I'll start with draft and share it with you. Do you have access to edit pages in the Brainstorm wiki?

[Edouard2laire]

Wanted to add the manual, as a way to start create a basic .json without having to type it.

In addition, documentation is needed for this new feature. I'll start with draft and share it with you. Do you have access to edit pages in the Brainstorm wiki?

Yes, I have access (username: EdouardDelaire). Let me know if there is anything else you want me to do.

[rcassani]

@Edouard2laire, documentation is in the link below, please check it out and edit it if needed. https://neuroimage.usc.edu/brainstorm/Tutorials/Plugins

This PR seems to be read to be merged!

[Edouard2laire]

Looks good to me. Thx :)

For the documentation; maybe we want to add a sentence saying the procedure if a user wants their plugin to be officially integrated in Brainstorm ?

[rcassani]

@Edouard2laire 🎉 (and before 2026 🤣)

[Edouard2laire]

🎉🎉 Thanks for your help in this PR :) (hopefully, I'll have graduated by 2026 lol)