[IPython-dev] How to make a notebook extension

[Doug Blank]

Follow-ups (suggestions, options, overall betterness) available in the
associated issue tracker:

https://github.com/ipython/ipython/issues/6229

Hopefully will lead to good documentation.

-Doug


On Sun, Jul 27, 2014 at 1:24 PM, Doug Blank <doug.blank at gmail.com> wrote:

> Ok, I think I have this figured out, and if the following is right, and
> best practice, I'd be glad to put in the docs.
>
> First, write your JavaScript programs. There should be a main JS file. The
> JavaScript file should generally take the form:
>
> ```
> define( function () {
>     var load_ipython_extension = function () {
>         ...
>     };
>
>     return {
>         load_ipython_extension : load_ipython_extension,
>     };
> });
> ```
>
> This function will return a JS object with "load_ipython_extension"
> defined to be a function that is called when loading the extension.
>
> Name this JS file with a unique name that won't collide with other
> extensions. For example, use "jones-feature-name.js" where "jones" is the
> name of your group, and "feature-name" is the name of what the feature you
> are adding/enhancing.
>
> If there is only the single .js file, then you can easily make a download
> for it.
>
> If more than one file is needed for your extension (additional libraries,
> css, etc) it is advised to make a zip file for easy install. The zip file
> should have your main JS file in the root.
>
> To install the zip or js file, use:
>
> ipython install-nbextension URL
>
> The files are saved to $(ipython locale)/nbextensions/
>
> At this point, you can use your extension by interactively loading it in a
> notebook (regardless of kernel, as long as your kernel supports running
> javascript); in the native kernel, that is:
>
> ```
> %%javascript
> IPython.load_extensions("jones-feature-name")
> ```
>
> Your feature is now active, and will be loaded automatically each time you
> open this notebook if you leave this cell in the notebook. [Is that right?
> How does it work?]
>
> What if you have an associated CSS file? It is not loaded automatically.
>
> Add this to your defined JS object:
>
> ```
>     var load_css = function () {
>         var link = document.createElement("link");
>         link.type = "text/css";
>         link.rel = "stylesheet";
>         link.href = require.toUrl("/nbextensions/jones-feature-name.css");
>         console.log(link);
>         document.getElementsByTagName("head")[0].appendChild(link);
>     };
> ```
>
> and call it in load_ipython_extension.
>
> Finally, if you want to load your extension automatically (or need to have
> your script loaded earlier to handle opening functions) then you can add
> this single line to your $(ipython
> locale)/profile_XXX/static/custom/custom.js:
>
> IPython.load_extensions("jones-feature-name");
>
> There are more options (having things execute on notebook open, adding
> toolbar buttons, menu items), and those are explain here ...
>
> How does that sound? Did I miss anything?
>
> -Doug
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20140729/01631eea/attachment.html>