Currently the PluginBlocktype abstract class has three methods for loading Javascript libraries, and invoking Javascript code to run when a block is loaded:
1. PluginBlocktype::get_instance_javascript(BlockInstance $instance): Called when a block instance is displayed (either on the page in view mode, or the page in edit mode). Expects to return an array of sub-arrays where each sub-array has a "file" item, which is the relative path to a JS file (relative to the blocktype's root), and an optional "init" item, which is a snippet of code that gets executed once the "file" library has loaded. (It currently uses jQuery.getScript() to do this).
2. PluginBlocktype::get_instance_inline_javascript(BlockInstance $instance): Called when a block instance is displayed (either on the page in view mode, or the page in edit mode). The code here is inserted into a <script> tag and placed after all the files loaded via get_instance_javascript
3. PluginBlocktype::get_instance_config_javascript(BlockInstance $instance): Called when a block instance's config modal is displayed. Seems to behave the same as PluginBlocktipe::get_instance_javascript()
The "init" sub-item in PluginBlocktype::get_instance_javascript() was added a while back to resolve a problem with the older PluginBlocktype::get_instance_inline_javascript() method. Sometimes, when a script was being loaded, the inline javascript would execute before the script finished loading, and that would cause errors. Putting the init code inside of jQuery.getScript()'s success callback resolves that problem.
But now we have a couple of new problems. The return format of get_instance_javascript() is now rather confusing (containing an array of sub-arrays as it does). We have this obsolete "get_instance_inline_javascript()" method, which none of the blocks use anymore. And, when you're on the page editor screen, adding and removing blocks dynamically, any JS library files for the block get called every time you add a block of that type. This is not only redundant, but also causes bugs when library files aren't namespaced properly and contain init code that runs each time they're loaded.
What we should probably switch to, is something like this:
1. PluginBlocktype::get_javascript_libraries(): Returns a list of Javascript library files to load on any page a blocktype of this sort is displayed on. When viewing a page in view mode, we can load the libraries for the blocks on the page; when viewing a page in edit mode, we can load the libraries for all blocktypes pre-emptively.
2. PluginBlocktype::get_javascript_config_libraries(): Likewise, but for libraries needed in the config modal
3. PluginBlocktype::get_instance_javascript(BlockInstance $instance): Returns a snippet of JS code to run when a block instance is loaded. (Should be tied into the JS libraries method, so that it only runs after *all* libraries for this blocktype are loaded.)
4. PluginBlocktype::get_instance_config_javascript(BlockInstance $instance): Likewise, but for the config modal
And to make sure that all JS libraries needed by a blocktype are loaded before the block instance is displayed, we could use the HeadJS library's "Resource Loading" module, which allows for a JS equivalent of PHP's "require_once()", callbacks on file loadings, testing whether a file has been loaded, etc. http://headjs.com/site/api/v1.00.html#load
This needs to be taken into consideration when working on bug #1796587