From 1838e966e6e192bb592716c3546947028b8b6068 Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Fri, 6 May 2016 12:06:04 -0700 Subject: [PATCH 1/2] Document `kernel.js` extensions. --- docs/source/extending/frontend_extensions.rst | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.rst index 405b362d9..fb11b7873 100644 --- a/docs/source/extending/frontend_extensions.rst +++ b/docs/source/extending/frontend_extensions.rst @@ -229,3 +229,47 @@ extension without uninstalling it. .. versionchanged:: 4.2 Added ``--sys-prefix`` argument + + + + +Kernel Specific extensions +-------------------------- + +.. warning:: + + This feature is only ment as a stop gap for kernels developpers whoneed + specific javascript to be injected on the page. The availability and api are + subject to change at anytime. + + +It is possible to load some JavaScript on the page on a per kernel basis. Be +aware that doing so will will make the browser page reload without warning as +soon as the user switch kernel without warning. + +As a kernel developer, if you need a specif piece of JavaScript to be loaded on +a per kernel basis, typically if you are developing a CodeMirror mode for your +language, or need to enable some specific debugging options, your +``kernelspecs`` are allowed to contain a ``kernel.js`` file that define a AMD +module. The AMD module should define an `onload` function that will be called +when the kernel spec is loaded, that is to say when you load a notebook that +uses your kernelspec, or change the kernelspec of a notebook to your +kernelspec. + +Note that adding a `kernel.js` to your kernelspec will add unexpected side +effect to changing kernel. In particular, as it is impossible to "unload" +JavaScript, any attempt to change kernelspec again will save the current +notebook and reload the page without confirmations. + + +Here is an example of ``kernel.js`` +.. code:: javascript + + // kernel.js + + define(function(){ + retrun {onload: function(){ + console.info('Kernel specific javascript loaded'); + // do more things here, like define a codemirror mode, + }} + }); From eac86ab13be560bb2dfe619cb9a9f3a3ca5202a4 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Fri, 6 May 2016 14:14:55 -0700 Subject: [PATCH 2/2] Edits to text --- docs/source/extending/frontend_extensions.rst | 46 ++++++++++--------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.rst index fb11b7873..66fe560f8 100644 --- a/docs/source/extending/frontend_extensions.rst +++ b/docs/source/extending/frontend_extensions.rst @@ -231,45 +231,47 @@ extension without uninstalling it. Added ``--sys-prefix`` argument - - Kernel Specific extensions -------------------------- .. warning:: - This feature is only ment as a stop gap for kernels developpers whoneed - specific javascript to be injected on the page. The availability and api are - subject to change at anytime. + This feature serves as a stopgap for kernel developers who need specific + JavaScript injected onto the page. The availability and API are subject to + change at anytime. It is possible to load some JavaScript on the page on a per kernel basis. Be -aware that doing so will will make the browser page reload without warning as -soon as the user switch kernel without warning. +aware that doing so will make the browser page reload without warning as +soon as the user switches the kernel without notice. + +If you, a kernel developer, need a particular piece of JavaScript to be loaded +on a "per kernel" basis, such as: + +* if you are developing a CodeMirror mode for your language +* if you need to enable some specific debugging options + +your ``kernelspecs`` are allowed to contain a ``kernel.js`` file that defines +an AMD module. The AMD module should define an `onload` function that will be +called when the kernelspec loads, such as: -As a kernel developer, if you need a specif piece of JavaScript to be loaded on -a per kernel basis, typically if you are developing a CodeMirror mode for your -language, or need to enable some specific debugging options, your -``kernelspecs`` are allowed to contain a ``kernel.js`` file that define a AMD -module. The AMD module should define an `onload` function that will be called -when the kernel spec is loaded, that is to say when you load a notebook that -uses your kernelspec, or change the kernelspec of a notebook to your -kernelspec. +* when you load a notebook that uses your kernelspec +* change the active kernelspec of a notebook to your kernelspec. -Note that adding a `kernel.js` to your kernelspec will add unexpected side -effect to changing kernel. In particular, as it is impossible to "unload" -JavaScript, any attempt to change kernelspec again will save the current -notebook and reload the page without confirmations. +Note that adding a `kernel.js` to your kernelspec will add an unexpected side +effect to changing a kernel in the notebook. As it is impossible to "unload" +JavaScript, any attempt to change the kernelspec again will save the current +notebook and reload the page without confirmations. +Here is an example of ``kernel.js``:: -Here is an example of ``kernel.js`` .. code:: javascript // kernel.js define(function(){ - retrun {onload: function(){ + return {onload: function(){ console.info('Kernel specific javascript loaded'); - // do more things here, like define a codemirror mode, + // do more things here, like define a codemirror mode, }} });