[IPython-dev] How to make a notebook extension

[Doug Blank]

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/20140727/3859348d/attachment.html>