{
"cells": [
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"import sys\n",
"sys.path.insert(0, '..')\n",
"\n",
"from branca.element import *"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Element"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This is the base brick of `branca`. You can create an `Element` in providing a template string:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"e = Element(\"This is fancy text\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Each element has an attribute `_name` and a unique `_id`. You also have a method `get_name` to get a unique string representation of the element."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Element a1d0f648f7444f96b526931944247fd6\n",
"element_a1d0f648f7444f96b526931944247fd6\n"
]
}
],
"source": [
"print(e._name, e._id)\n",
"print(e.get_name())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can render an `Element` using the method `render`:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'This is fancy text'"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"e.render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In the template, you can use keyword `this` for accessing the object itself ; and the keyword `kwargs` for accessing any keyword argument provided in the `render` method:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'Hello World, my name is `element_6f17661abddb45c7bf2aa794cadd327d`.'"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"e = Element(\"Hello {{kwargs['you']}}, my name is `{{this.get_name()}}`.\")\n",
"e.render(you='World')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Well, this is not really cool for now. What makes elements useful lies in the fact that you can create trees out of them. To do so, you can either use the method `add_child` or the method `add_to`."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"child = Element('This is the child.')\n",
"parent = Element('This is the parent.').add_child(child)\n",
"\n",
"parent = Element('This is the parent.')\n",
"child = Element('This is the child.').add_to(parent)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now in the example above, embedding the one in the other does not change anything."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"This is the parent. This is the child.\n"
]
}
],
"source": [
"print(parent.render(), child.render())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"But you can use the tree structure in the template."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"''"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"parent = Element(\"{% for child in this._children.values() %}{{child.render()}}{% endfor %}\")\n",
"Element('').add_to(parent)\n",
"Element('').add_to(parent)\n",
"parent.render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see, the child of an element are referenced in the `_children` attibute in the form of an `OrderedDict`. You can choose the key of each child in specifying a `name` in the `add_child` (or `add_to`) method:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"OrderedDict([('child_1', )])"
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"parent = Element(\"{% for child in this._children.values() %}{{child.render()}}{% endfor %}\")\n",
"Element('').add_to(parent, name='child_1')\n",
"parent._children"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"That way, it's possible to overwrite a child in specifying the same name:"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"''"
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Element('').add_to(parent, name='child_1')\n",
"parent.render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"I hope you start to find it useful.\n",
"\n",
"In fact, the real interest of `Element` lies in the classes that inherit from it. The most important one is `Figure` described in the next section."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Figure\n",
"\n",
"A `Figure` represents an HTML document. It's composed of 3 parts (attributes):\n",
"\n",
"* `header` : corresponds to the `` part of the HTML document,\n",
"* `html` : corresponds to the `` part,\n",
"* `script` : corresponds to a `\n"
]
}
],
"source": [
"f = Figure()\n",
"print(f.render())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can for example create a beatiful cyan \"hello-world\" webpage in doing:"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
" \n",
" \n",
" \n",
"\n",
" \n",
"
\"))\n",
"print(f.render())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can simply save the content of the `Figure` to a file, thanks to the `save` method:"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
" \n",
" \n",
" \n",
"\n",
" \n",
"
Hello world
\n",
"\n",
"\n"
]
}
],
"source": [
"f.save('foo.html')\n",
"print(open('foo.html').read())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you want to visualize it in the notebook, you can let `Figure._repr_html_` method do it's job in typing: "
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
""
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"f"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If this rendering is too large for you, you can force it's width and height:"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"f.width = 300\n",
"f.height = 200\n",
"f"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that you can also define a `Figure`'s size in a matplotlib way:"
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Figure(figsize=(5,5))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## MacroElement"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It happens you need to create elements that have multiple effects on a Figure. For this, you can use `MacroElement` whose template contains macros ; each macro writes something into the parent Figure's header, body and script."
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
" \n",
" \n",
" This is header of macro_element_ea36a310ab8a4212a8c7ca754a4140fc\n",
"\n",
" \n",
" This is html of macro_element_ea36a310ab8a4212a8c7ca754a4140fc\n",
"\n",
"\n"
]
}
],
"source": [
"macro = MacroElement()\n",
"macro._template = Template(\n",
" '{% macro header(this, kwargs) %}'\n",
" 'This is header of {{this.get_name()}}'\n",
" '{% endmacro %}'\n",
"\n",
" '{% macro html(this, kwargs) %}'\n",
" 'This is html of {{this.get_name()}}'\n",
" '{% endmacro %}'\n",
"\n",
" '{% macro script(this, kwargs) %}'\n",
" 'This is script of {{this.get_name()}}'\n",
" '{% endmacro %}'\n",
" )\n",
"\n",
"print(Figure().add_child(macro).render())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Link"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To embed javascript and css links in the header, you can use these class:"
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"''"
]
},
"execution_count": 18,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"js_link = JavascriptLink('https://example.com/javascript.js')\n",
"js_link.render()"
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"''"
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"css_link = CssLink('https://example.com/style.css')\n",
"css_link.render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Html"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"An `Html` element enables you to create custom div to put in the *body* of your page."
]
},
{
"cell_type": "code",
"execution_count": 26,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'
Hello world
'"
]
},
"execution_count": 26,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"html = Html('Hello world')\n",
"html.render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It's designed to render the text *as you gave it*, so it won't work directly it you want to embed HTML code inside the div."
]
},
{
"cell_type": "code",
"execution_count": 25,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'
<b>Hello world</b>
'"
]
},
"execution_count": 25,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Html('Hello world').render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"For this, you have to set `script=True` and it will work:"
]
},
{
"cell_type": "code",
"execution_count": 28,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'
Hello world
'"
]
},
"execution_count": 28,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"Html('Hello world', script=True).render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## IFrame"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you need to embed a full webpage (with separate javascript environment), you can use `IFrame`."
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'
'"
]
},
"execution_count": 21,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"iframe = IFrame('Hello World')\n",
"iframe.render()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see, it will embed the full content of the iframe in a *base64* string so that the ouput looks like:"
]
},
{
"cell_type": "code",
"execution_count": 22,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 22,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"f = Figure(height=180)\n",
"f.html.add_child(Element(\"Before the frame\"))\n",
"f.html.add_child(IFrame('In the frame', height='100px'))\n",
"f.html.add_child(Element(\"After the frame\"))\n",
"f"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Div"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"At last, you have the `Div` element that behaves almost like `Html` with a few differences:\n",
"\n",
"* The style is put in the header, while `Html`'s style is embedded inline.\n",
"* `Div` inherits from `MacroElement` so that:\n",
" * It cannot be rendered unless it's embedded in a `Figure`.\n",
" * It is a useful object toinherit from when you create new classes."
]
},
{
"cell_type": "code",
"execution_count": 29,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
" \n",
" \n",
" \n",
"\n",
" \n",
"