branca.element

Element

A generic class for creating Elements.

class branca.element.CssLink(url, download=False)

Bases: Link

Create a CssLink object based on a url.

Parameters:

• url (str) – The url to be linked

• download (bool, default False) – Whether the target document shall be loaded right now.

class branca.element.Div(width='100%', height='100%', left='0%', top='0%', position='relative')

Bases: Figure

Create a Div to be embedded in a Figure.

Parameters:

• width (int or str, default '100%') – The width of the div in pixels (int) or percentage (str).

• height (int or str, default '100%') – The height of the div in pixels (int) or percentage (str).

• left (int or str, default '0%') – The left-position of the div in pixels (int) or percentage (str).

• top (int or str, default '0%') – The top-position of the div in pixels (int) or percentage (str).

• position (str, default 'relative') – The position policy of the div. Usual values are ‘relative’, ‘absolute’, ‘fixed’, ‘static’.

get_root()

Returns the root of the elements tree.

render(**kwargs)

Renders the HTML representation of the element.

class branca.element.Element(template=None, template_name=None)

Bases: object

Basic Element object that does nothing. Other Elements may inherit from this one.

Parameters:

• template (str, default None) –

  A jinaj2-compatible template string for rendering the element. If None, template will be:

  {% for name, element in this._children.items() %}
  {{element.render(**kwargs)}}
  {% endfor %}
  

  so that all the element’s children are rendered.

• template_name (str, default None) – If no template is provided, you can also provide a filename.

add_child(child, name=None, index=None)

Add a child.

add_children(child, name=None, index=None)

Add a child.

add_to(parent, name=None, index=None)

Add element to a parent.

get_bounds()

Computes the bounds of the object and all it’s children in the form [[lat_min, lon_min], [lat_max, lon_max]].

get_name()

Returns a string representation of the object. This string has to be unique and to be a python and javascript-compatible variable name.

get_root()

Returns the root of the elements tree.

render(**kwargs)

Renders the HTML representation of the element.

save(outfile, close_file=True, **kwargs)

Saves an Element into a file.

Parameters:

• outfile (str or file object) – The file (or filename) where you want to output the html.

• close_file (bool, default True) – Whether the file has to be closed after write.

to_dict(depth=-1, ordered=True, **kwargs)

Returns a dict representation of the object.

to_json(depth=-1, **kwargs)

Returns a JSON representation of the object.

class branca.element.Figure(width='100%', height=None, ratio='60%', title=None, figsize=None)

Bases: Element

Create a Figure object, to plot things into it.

Parameters:

• width (str, default "100%") – The width of the Figure. It may be a percentage or pixel value (like “300px”).

• height (str, default None) – The height of the Figure. It may be a percentage or a pixel value (like “300px”).

• ratio (str, default "60%") – A percentage defining the aspect ratio of the Figure. It will be ignored if height is not None.

• title (str, default None) – Figure title.

• figsize (tuple of two int, default None) – If you’re a matplotlib addict, you can overwrite width and height. Values will be converted into pixels in using 60 dpi. For example figsize=(10, 5) will result in width=”600px”, height=”300px”.

add_subplot(x, y, n, margin=0.05)

Creates a div child subplot in a matplotlib.figure.add_subplot style.

Parameters:

• x (int) – The number of rows in the grid.

• y (int) – The number of columns in the grid.

• n (int) – The cell number in the grid, counted from 1 to x*y.

• Example

• fig.add_subplot(3 (>>>)

• 2

• 5)

• 2columns (# Create a div in the 5th cell of a 3rows x)

• corner). (grid(bottom-left)

get_root()

Returns the root of the elements tree.

render(**kwargs)

Renders the HTML representation of the element.

to_dict(depth=-1, **kwargs)

Returns a dict representation of the object.

class branca.element.Html(data, script=False, width='100%', height='100%')

Bases: Element

Create an HTML div object for embedding data.

Parameters:

• data (str) – The HTML data to be embedded.

• script (bool) – If True, data will be embedded without escaping (suitable for embedding html-ready code)

• width (int or str, default '100%') – The width of the output div element. Ex: 120 , ‘80%’

• height (int or str, default '100%') – The height of the output div element. Ex: 120 , ‘80%’

class branca.element.IFrame(html=None, width='100%', height=None, ratio='60%', figsize=None)

Bases: Element

Create a Figure object, to plot things into it.

Parameters:

• html (str, default None) – Eventual HTML code that you want to put in the frame.

• width (str, default "100%") – The width of the Figure. It may be a percentage or pixel value (like “300px”).

• height (str, default None) – The height of the Figure. It may be a percentage or a pixel value (like “300px”).

• ratio (str, default "60%") – A percentage defining the aspect ratio of the Figure. It will be ignored if height is not None.

• figsize (tuple of two int, default None) – If you’re a matplotlib addict, you can overwrite width and height. Values will be converted into pixels in using 60 dpi. For example figsize=(10, 5) will result in width=”600px”, height=”300px”.

render(**kwargs)

Renders the HTML representation of the element.

class branca.element.JavascriptLink(url, download=False)

Bases: Link

Create a JavascriptLink object based on a url.

Parameters:

• url (str) – The url to be linked

• download (bool, default False) – Whether the target document shall be loaded right now.

class branca.element.Link(template=None, template_name=None)

Bases: Element

An abstract class for embedding a link in the HTML.

get_code()

Opens the link and returns the response’s content.

to_dict(depth=-1, **kwargs)

Returns a dict representation of the object.

class branca.element.MacroElement

Bases: Element

This is a parent class for Elements defined by a macro template. To compute your own element, all you have to do is:

• To inherit from this class

• Overwrite the ‘_name’ attribute

• Overwrite the ‘_template’ attribute with something of the form:

  {% macro header(this, kwargs) %}
      ...
  {% endmacro %}
  
  {% macro html(this, kwargs) %}
      ...
  {% endmacro %}
  
  {% macro script(this, kwargs) %}
      ...
  {% endmacro %}
  

render(**kwargs)

Renders the HTML representation of the element.