= Plugins =
''Authors: Francois Tadel''

Brainstorm connects with features from many third-party libraries of methods. The external software can be downloaded or updated automatically by Brainstorm when needed. This tutorial presents the API to register and manage plugins.

== Interactive management ==
The Brainstorm interface offers menus to Install/Update/Uninstall plugins.

{{attachment:example1.gif}}

'''Install''': The package is downloaded in the Brainstorm user folder:''' $HOME/.brainstorm/plugins/'''

'''Uninstall''': Delete the plugin folder and all its subfolders.

'''Load''': Adds all the subfolders needed by the plugin to the Matlab path, plus other optional taks.

'''Unload''': Removes all the plugin folders from the Matlab path.

'''Update''': Some plugins are designed to update themselves automatically whenever a new version is available online, or requested by Brainstorm. Others plugins must be updated manually.

'''Manual install''': If you already have a given plugin installed on your computer (eg. FieldTrip, SPM12) and don't want Brainstorm to manage the download/update or the Matlab path for you, reference it with the menu: '''Custom install''' > Set installation folder.

'''List''': You can list all the installed plugins with the menu List:

{{attachment:list.gif}}

== Command-line management ==
The calls to install or manage plugins are all documented in the header of '''bst_plugin.m''':

<<HTML(<div   style="border:1px solid black;  background-color:#EEEEFF; width:720px;   height:400px; overflow:scroll;  padding:10px; font-family:   Consolas,Menlo,Monaco,Lucida  Console,Liberation Mono,DejaVu Sans   Mono,Bitstream Vera Sans  Mono,Courier New,monospace,sans-serif;   font-size: 13px; white-space: pre;">)>><<EmbedContent("https://neuroimage.usc.edu/bst/viewcode.php?core=bst_plugin.m")>><<HTML(</div >)>>

== Plugin definition ==
The plugins registered in Brainstorm are listed in '''bst_plugin.m''' / '''GetSupported'''. Each one is an entry in the PlugDesc array, following the structure defined in '''db_template('plugdesc')'''. The fields allowed are described below.

Mandatory fields:

 * '''Name''': String, Plugin name = subfolder in the Brainstorm user folder
 * '''Version''': String, version of the plugin (eg. '1.2', '21a', 'github-master', 'latest')
 * '''URLzip''': Download URL (zip file accessible over HTTP/HTTPS/FTP)
 * '''URLinfo''': Information URL: Software website

Optional fields:

 * '''Category''': String, sub-menu in which the plugin is listed
 * '''AutoUpdate''': If 1, plugin is updated automatically when there is a new version available
 * '''ExtraMenus''': Cell matrix {Nx2} with list of entries to add to the plugins menu, eg. {'Download page', 'web(''http://...'')'; 'Tutorial', 'web(''http://...'')'}
 * '''TestFile''': Function/file name to check the existence of the plugin outside of the Brainstorm user folder
 * '''ReadmeFile''': Text filename (relative to the plugin path) - If empty, try using brainstorm3/doc/plugin/<Name>_readme.txt
 * '''LogoFile''': Logo filename (relative to the plugin path) - If empty, try using brainstorm3/doc/plugin/<Name>_logo.[gif|png]
 * '''MinMatlabVer''': Minimum Matlab version, as returned by bst_get('MatlabVersion')
 * '''RequiredPlugs''': Cell-array of required plugin names, to install/load before this one: {Nx2}=>{'plugname','version';...} or {Nx1}=>{'plugname';...}
 * '''UnloadPlugs''': Cell-array of incompatible plugin names, to remove from path before adding
 * '''LoadFolders''': Cell-array of subfolders to add to the path when setting the plugin up (use {'*'} to load all subfolders)
 * '''GetVersionFcn''': String to eval to get the version (after installation)
 * '''InstalledFcn''': String to eval or function handle to call after installing the plugin
 * '''UninstalledFcn''': String to eval or function handle to call after uninstalling the plugin
 * '''LoadedFcn''': String to eval or function handle to call after loading the plugin
 * '''UnloadedFcn''': String to eval or function handle to call after unloading the plugin

Fields set when installing or loading the plugin:

 * '''SubFolder''': If all the code is in a subfolder: detect this at installation time
 * '''Path''': Set at runtime: Installation path for this plugin
 * '''Processes''': List of process functions to be added to the pipeline manager
 * '''isLoaded''': Set at runtime: 0=Not loaded, 1=Loaded (folder and specific subfolders added to Matlab path)
 * '''isManaged''': Set at runtime: 0=Installed by the user, 1=Installed automatically by Brainstorm