README.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ihtml Module\n",
    "\n",
    "The `ihtml` module allows HTML to be embedded in an iframe in a notebook.  This provides a separate DOM for the HTML, avoiding cross-talk with the notebook itself.  It provides several magics for that purpose.  Importing the module is enough to get it working."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "\n",
       "function add_highlight_mode(mode, pattern) {\n",
       "    var modes = Jupyter.CodeCell.options_default.highlight_modes;\n",
       "    var mode_name = 'magic_' + mode;\n",
       "    if (!modes[mode_name])\n",
       "        modes[mode_name] = {};\n",
       "    if (!modes[mode_name]['reg'])\n",
       "        modes[mode_name]['reg'] = [];\n",
       "    modes[mode_name]['reg'].push(pattern);\n",
       "}\n",
       "add_highlight_mode('html', /^%%ihtml/);\n",
       "add_highlight_mode('javascript', /^%%jsdoc/);\n",
       "add_highlight_mode('css', /^%%cssdoc/);\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import ihtml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Usage\n",
    "\n",
    "The basic magic command, `%%ihtml` displays the contents of that cell as HTML inside of an iframe.  Note that styles and javascript are restricted to that frame.  The argument to the magic sets the height of the iframe.  It is optional, and defaults to 400 px."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "        <iframe\n",
       "            width=\"100%\"\n",
       "            height=\"200\"\n",
       "            src=\"data:text/html;base64,PGh0bWw+CiAgICA8aGVhZD4KICAgICAgICA8c3R5bGU+CiAgICAgICAgICAgIGJvZHkgewogICAgICAgICAgICAgICAgYmFja2dyb3VuZDogI2VlZTsKICAgICAgICAgICAgfQogICAgICAgIDwvc3R5bGU+CiAgICA8L2hlYWQ+CiAgICA8Ym9keT4KICAgICAgICA8aDE+SGVsbG8hPC9oMT4KICAgIDwvYm9keT4KPC9odG1sPg==\"\n",
       "            frameborder=\"0\"\n",
       "            allowfullscreen\n",
       "        ></iframe>\n",
       "        "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%ihtml 200\n",
    "<html>\n",
    "    <head>\n",
    "        <style>\n",
    "            body {\n",
    "                background: #eee;\n",
    "            }\n",
    "        </style>\n",
    "    </head>\n",
    "    <body>\n",
    "        <h1>Hello!</h1>\n",
    "    </body>\n",
    "</html>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Variables in the user namespace can be referenced with `{{ <name> }}` syntax.  Their values are converted to strings and inserted into the document.  Objects can be converted to JSON documents instead with the `{{ <name> | json }}` syntax."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "message = \"Hello!\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "        <iframe\n",
       "            width=\"100%\"\n",
       "            height=\"200\"\n",
       "            src=\"data:text/html;base64,PGh0bWw+CiAgICA8aGVhZD4KICAgICAgICA8c3R5bGU+CiAgICAgICAgICAgIGJvZHkgewogICAgICAgICAgICAgICAgYmFja2dyb3VuZDogI2VlZTsKICAgICAgICAgICAgfQogICAgICAgIDwvc3R5bGU+CiAgICA8L2hlYWQ+CiAgICA8Ym9keT4KICAgICAgICA8aDE+SGVsbG8hPC9oMT4KICAgICAgICA8cHJlPnZhciBtZXNzYWdlID0gIkhlbGxvISI8L3ByZT4KICAgIDwvYm9keT4KPC9odG1sPg==\"\n",
       "            frameborder=\"0\"\n",
       "            allowfullscreen\n",
       "        ></iframe>\n",
       "        "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%ihtml 200\n",
    "<html>\n",
    "    <head>\n",
    "        <style>\n",
    "            body {\n",
    "                background: #eee;\n",
    "            }\n",
    "        </style>\n",
    "    </head>\n",
    "    <body>\n",
    "        <h1>{{ message }}</h1>\n",
    "        <pre>var message = {{ message | json }}</pre>\n",
    "    </body>\n",
    "</html>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sub-documents\n",
    "\n",
    "Both javascript and CSS may be placed inline in the HTML, but good coding practices suggest that they should be split into separate documents.  While the HTML document you write can certainly refer to external documents, ihtml offers a mechanism for mimicking this split.  The `%%cssdoc` and `%%jsdoc` magics can be used to create CSS and javascript documents.  Both must be used with an argument naming the document."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%cssdoc graybg\n",
    "body {\n",
    "    background: #eee;\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Variable substitution works in these as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%jsdoc clicker\n",
    "document.addEventListener(\"DOMContentLoaded\", function(e) {\n",
    "    document.querySelector(\"h1\").addEventListener(\"click\", function(event) {\n",
    "        var div = document.createElement(\"div\");\n",
    "        div.textContent = {{ message | json }};\n",
    "        document.body.appendChild(div);\n",
    "    })\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These documents can be included in an ihtml document with `{{ <name> | cssdoc }}` and `{{ <name> | jsdoc }}`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "        <iframe\n",
       "            width=\"100%\"\n",
       "            height=\"400\"\n",
       "            src=\"data:text/html;base64,PGh0bWw+CiAgICA8aGVhZD4KICAgICAgICA8c3R5bGU+Ym9keSB7CiAgICBiYWNrZ3JvdW5kOiAjZWVlOwp9PC9zdHlsZT4KICAgICAgICA8c2NyaXB0PmRvY3VtZW50LmFkZEV2ZW50TGlzdGVuZXIoIkRPTUNvbnRlbnRMb2FkZWQiLCBmdW5jdGlvbihlKSB7CiAgICBkb2N1bWVudC5xdWVyeVNlbGVjdG9yKCJoMSIpLmFkZEV2ZW50TGlzdGVuZXIoImNsaWNrIiwgZnVuY3Rpb24oZXZlbnQpIHsKICAgICAgICB2YXIgZGl2ID0gZG9jdW1lbnQuY3JlYXRlRWxlbWVudCgiZGl2Iik7CiAgICAgICAgZGl2LnRleHRDb250ZW50ID0gIkhlbGxvISI7CiAgICAgICAgZG9jdW1lbnQuYm9keS5hcHBlbmRDaGlsZChkaXYpOwogICAgfSkKfSk8L3NjcmlwdD4KICAgIDwvaGVhZD4KICAgIDxib2R5PgogICAgICAgIDxoMT5DbGljayBtZSE8L2gxPgogICAgPC9ib2R5Pgo8L2h0bWw+\"\n",
       "            frameborder=\"0\"\n",
       "            allowfullscreen\n",
       "        ></iframe>\n",
       "        "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%ihtml\n",
    "<html>\n",
    "    <head>\n",
    "        {{ graybg | cssdoc }}\n",
    "        {{ clicker | jsdoc }}\n",
    "    </head>\n",
    "    <body>\n",
    "        <h1>Click me!</h1>\n",
    "    </body>\n",
    "</html>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}