= 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:<<BR>><<BR>> {{attachment:list.gif||width="544",height="156"}}

== 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 ''