From 1feb3960d8b14b91b38bb5426799e015b8e6278b Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Wed, 25 Nov 2015 19:22:10 +0100 Subject: [PATCH 1/3] Start documenting how to write font end extension This if course require more work, but the request for custom key binding is too high, and the process of writing extensions too widespread on the internet. --- docs/source/extending/frontend_extensions.rst | 145 ++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/source/extending/frontend_extensions.rst diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.rst new file mode 100644 index 0000000000..c16c7624bc --- /dev/null +++ b/docs/source/extending/frontend_extensions.rst @@ -0,0 +1,145 @@ +Custom front-end extesions +========================== + +This describe the basic steps to write a JavaScript extension for the Jupyter +notebook front-end. This allows you to customize the behavior of the various +pages like the dashboard, the notebook, the text editor. + +The structure of an extension +----------------------------- + +.. note:: + + The notebook fontend and Javascript API are not stable, and are subject to + lot of changes. Any extension written for the current notebook is almost + guarantied to break in the next release. + +A front-end extension is a JavaScript file that define an AMD module which +expose at least a function called `load_ipython_extension` which takes no +arguments. We will not get into details about what each of these term are, +but here is the minimal code needed for a working extension: + +.. code:: javascript + + //file myext/main.js + + define(function(){ + + function load_ipython_extension(){ + console.info('this is my first extension') + } + + return {load_ipython_extension: load_ipython_extension }; + }) + +.. note:: + + for historical reason the function is called `load_ipython_extension`, + though it does apply to the Jupyter notebook as well and will work + regardless of the kernel you use. + +If you are familiar with JavaScript, you can use this template to require any +Jupyter module and modify their configuration. Your extension will be loaded +at the right time during the notebook page initialisation for you to hook +listener for the various even that the page can trigger. + +You might want to access to the current instances of the various component on +the page, these a re exposed by a module name `base/js/namespace`. If you plan +on accessing instances on the page, be careful to require this module and not +access the global variable `Jupyter`. + +Here is how to do that: + + +.. code:: javascript + + //file myext/main.js + + define(['base/js/namespace'],function(Jupyter){ + + function load_ipython_extension(){ + console.log('This is the current notebook application instance', Jupyter.notebook); + } + + return {load_ipython_extension: load_ipython_extension }; + }) + + + +Modify key bindings +------------------- + +One of the ability of extensions is to modify key bindings, once again this is +a API which is not guarantied to be stable. Though the request for custom key +bindings is often require and helpful to increase accessibility, so in the +following we show how to access theses. + +Here is an example of extension that will unbind `0,0` in command mode to +restart the kernel, and bind `0,0,0` in it's place. + +.. code:: javascript + + //file myext/main.js + + define(['base/js/namespace'],function(Jupyter){ + + function load_ipython_extension(){ + Jupyter.keyboard_manager.command_shortcuts.remove_shortcut('0,0') + Jupyter.keyboard_manager.command_shortcuts.add_shortcut('0,0,0', 'jupyter-notebook:restart-kernel') + } + + return {load_ipython_extension: load_ipython_extension }; + }) + +.. note:: + + We are awre the keybindings might not work correctly on non US keyboard, + unfortunately it is a limitation of browser implmentation and teh status of + the keyboard handling on the web. We appreciate you input if you have issue + binding some keys, or help to improve the situation. + +You can see that I have used the **command name** +`jupyter-notebook:restart-kernel` to bind the new shortcut. There is no API yet +to access the list of all available *commands*, though the following in the +JavaScript console of your browser on a notebook page should give you an idea +of what of available. + + + +.. code:: javascript + + Object.keys(IPython.actions._actions) + +I'm also binding keyboard shortcut on the **command mode** you can also bind +them on the edit mode. Keep in mind though the most keyboard shortcuts on the +edit mode are handled by CodeMirror which also support custom key bindings, but +not using the system describe here. + +You can also define and register your own action to be used, but the +documentation for it has not been written yet. If you need to do it, +please ask us, we can give you the necessary information, and we would appreciate +if you could format them in a detailed way in place of this paragraph. + + + +installation and activation of extension +---------------------------------------- + +You can install your extension in the Jupyter configuration directory, under +the `nbextensions` subdirectory. On Unix system this will likely be +`~/.jupyter/nbextensions/`. + +You thus will likely end up with the file +`~/.jupyter/nbextensions/myextension/main.js` that now need to be loaded by the +notebook. You can configure you Jupyter Notebook to do so using the Jupyter +front-end configuration system described later in these docs. + +A 1 line to activate you extension would be to issue the following **once** in +a notebook JavaScript console: + +.. code:: javascript + + Jupyter.notebook.config.update({ + "load_extensions": {"myextension/main": true} + }) + From 92caca5683f6cfb638aa3917340447bfc2f81b45 Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Mon, 30 Nov 2015 18:26:25 +0000 Subject: [PATCH 2/3] English fixes and update description of installing and activating extensions --- docs/source/extending/frontend_extensions.rst | 105 ++++++++---------- 1 file changed, 49 insertions(+), 56 deletions(-) diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.rst index c16c7624bc..7b7e72f822 100644 --- a/docs/source/extending/frontend_extensions.rst +++ b/docs/source/extending/frontend_extensions.rst @@ -1,22 +1,22 @@ Custom front-end extesions ========================== -This describe the basic steps to write a JavaScript extension for the Jupyter -notebook front-end. This allows you to customize the behavior of the various -pages like the dashboard, the notebook, the text editor. +This describes the basic steps to write a JavaScript extension for the Jupyter +notebook front-end. This allows you to customize the behaviour of the various +pages like the dashboard, the notebook, or the text editor. The structure of an extension ----------------------------- .. note:: - The notebook fontend and Javascript API are not stable, and are subject to - lot of changes. Any extension written for the current notebook is almost - guarantied to break in the next release. + The notebook frontend and Javascript API are not stable, and are subject to + a lot of changes. Any extension written for the current notebook is almost + guaranteed to break in the next release. -A front-end extension is a JavaScript file that define an AMD module which -expose at least a function called `load_ipython_extension` which takes no -arguments. We will not get into details about what each of these term are, +A front-end extension is a JavaScript file that defines an AMD module +exposing at least a function called `load_ipython_extension`, which takes no +arguments. We will not get into the details of what each of these terms are, but here is the minimal code needed for a working extension: .. code:: javascript @@ -34,22 +34,19 @@ but here is the minimal code needed for a working extension: .. note:: - for historical reason the function is called `load_ipython_extension`, - though it does apply to the Jupyter notebook as well and will work + For historical reasons, the function is called `load_ipython_extension`, + but it does apply to the Jupyter notebook as well, and will work regardless of the kernel you use. If you are familiar with JavaScript, you can use this template to require any -Jupyter module and modify their configuration. Your extension will be loaded -at the right time during the notebook page initialisation for you to hook -listener for the various even that the page can trigger. +Jupyter module and modify its configuration. Your extension will be loaded +at the right time during the notebook page initialisation for you to set up a +listener for the various events that the page can trigger. You might want to access to the current instances of the various component on -the page, these a re exposed by a module name `base/js/namespace`. If you plan -on accessing instances on the page, be careful to require this module and not -access the global variable `Jupyter`. - -Here is how to do that: - +the page, these are exposed by a module named `base/js/namespace`. If you plan +on accessing instances on the page, you should require this module rather than +accessing the global variable `Jupyter`. Here is how to do that: .. code:: javascript @@ -66,16 +63,15 @@ Here is how to do that: -Modify key bindings -------------------- +Modifying key bindings +---------------------- -One of the ability of extensions is to modify key bindings, once again this is -a API which is not guarantied to be stable. Though the request for custom key -bindings is often require and helpful to increase accessibility, so in the -following we show how to access theses. +Extensions have the ability to modify key bindings. Once again, this API +is not guaranteed to be stable, but changing key bindings is a common request. +This is how to do it in the current version of the notebook. -Here is an example of extension that will unbind `0,0` in command mode to -restart the kernel, and bind `0,0,0` in it's place. +Here is an example of extension that will unbind `0,0` in command mode, which +normally restarts the kernel, and bind `0,0,0` in it's place. .. code:: javascript @@ -93,53 +89,50 @@ restart the kernel, and bind `0,0,0` in it's place. .. note:: - We are awre the keybindings might not work correctly on non US keyboard, - unfortunately it is a limitation of browser implmentation and teh status of - the keyboard handling on the web. We appreciate you input if you have issue - binding some keys, or help to improve the situation. + Keybindings might not work correctly on non-US keyboards. + Unfortunately, this is a limitation of browser implementations and the status of + keyboard event handling on the web. We appreciate your feedback if you have + issues binding keys, or ideas to help improve the situation. You can see that I have used the **command name** `jupyter-notebook:restart-kernel` to bind the new shortcut. There is no API yet to access the list of all available *commands*, though the following in the JavaScript console of your browser on a notebook page should give you an idea -of what of available. - - +of what of available: .. code:: javascript Object.keys(IPython.actions._actions) -I'm also binding keyboard shortcut on the **command mode** you can also bind -them on the edit mode. Keep in mind though the most keyboard shortcuts on the -edit mode are handled by CodeMirror which also support custom key bindings, but -not using the system describe here. +In this example, we changed keyboard shortcuts in **command mode**; you can also +customise keyboard shortcuts in edit mode. +However, most of the keyboard shortcuts in edit mode are handled by CodeMirror, +which supports custom key bindings via a completely different API. You can also define and register your own action to be used, but the -documentation for it has not been written yet. If you need to do it, +documentation for this has not been written yet. If you need to do it, please ask us, we can give you the necessary information, and we would appreciate if you could format them in a detailed way in place of this paragraph. +Installing and enabling extensions +---------------------------------- +You can install your nbextension with the command: -installation and activation of extension ----------------------------------------- - -You can install your extension in the Jupyter configuration directory, under -the `nbextensions` subdirectory. On Unix system this will likely be -`~/.jupyter/nbextensions/`. + jupyter nbextension install path/to/myext/ -You thus will likely end up with the file -`~/.jupyter/nbextensions/myextension/main.js` that now need to be loaded by the -notebook. You can configure you Jupyter Notebook to do so using the Jupyter -front-end configuration system described later in these docs. +Where myext is the directory containing the Javascript files. This will copy +it to a Jupyter data directory (the exact location is platform dependent - see +:ref:`jupyter_path`). -A 1 line to activate you extension would be to issue the following **once** in -a notebook JavaScript console: +For development, you can use the ``--symlink`` flag to symlink your extension +rather than copying it, so there's no need to reinstall after changes. -.. code:: javascript +To use your extension, you'll also need to **enable** it, which tells the +notebook interface to load it. You can do that with another command: - Jupyter.notebook.config.update({ - "load_extensions": {"myextension/main": true} - }) + jupyter nbextension enable myext/main +The argument refers to the Javascript module containing your ``load_ipython_extension`` +function, which is ``myext/main.js`` in this example. There is a corresponding +``disable`` command to stop using an extension without installing it. From 66f7390f8d3cf289d28cbda010f9e8b37ff04b71 Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Tue, 1 Dec 2015 10:27:36 +0100 Subject: [PATCH 3/3] missing N --- docs/source/extending/frontend_extensions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/extending/frontend_extensions.rst b/docs/source/extending/frontend_extensions.rst index 7b7e72f822..5fbade66ca 100644 --- a/docs/source/extending/frontend_extensions.rst +++ b/docs/source/extending/frontend_extensions.rst @@ -1,5 +1,5 @@ -Custom front-end extesions -========================== +Custom front-end extensions +=========================== This describes the basic steps to write a JavaScript extension for the Jupyter notebook front-end. This allows you to customize the behaviour of the various