webviz package

This package contains the core functionality for putting together different Page instances into a Webviz instance. Each Page is a collection of PageElement instances, which are rendered in the input order on the corresponding page when running Webviz.write_html().

from webviz import Webviz, Page

web = Webviz('Main title')
page = Page("Demo", icon='graph')
web.add(page)
web.write_html("./simple_webviz_example", overwrite=True, display=True)

This small example will create an instance web, add one empty page to it (in addition to the default index/front page), and write the output to a folder ./simple_webviz_example.

class webviz.HeaderElement

Bases: webviz._header_element.HeaderElement

A HeaderElement describes one action taken to include a header element to a Page.

Parameters:

• tag – The tag of the header element, such as ‘script’ or ‘link’.
• attributes – Dictinary of attributes of the tag, such as {‘src’: ‘jquery.js’}. Value strings can include the template value {root_folder} which will be substituted with the path to the root of the site.
• content – The content of the text (inner html).
• source_file – If the header element refers to a file, then the absolute path to that file.
• target_file – The relative path to the file, as it is referred to in the attributes.

class webviz.Webviz(title, banner_title='Webviz', banner_image=None, copyright_notice=None, theme='default')

Bases: object

An instance of Webviz is a collection of Page instances, and optionally also SubMenu instances. Webviz is used to build a collection of these, which can afterwards be rendered as html.

There is one special Page included as default, index, which is the front page in the html output.

add(menu_item)

Adds an item to the top-level navigation bar of the Webviz instance.

Parameters:menu_item – A Page or Submenu to add to the Webviz instance. Raises:ValueError, if menu_item is neither Page nor a SubMenu.

pages

List of all Pages in the Webviz instance.

write_html(destination, display=False, overwrite=False)

Writes the html to the destination folder.

Parameters:

• destination – Directory to write the html output to.
• overwrite – Optional Parameter. Whether to ignore if the given destination already exists. Content inside the folder may be deleted.
• display – Optional Parameter. Whether to open browser to the index page.

Raises:

ValueError if overwrite is False and destination folder exists.

class webviz.Html(html, js_deps=[], css_deps=[])

Bases: webviz._page_element.PageElement

A page element for adding html.

Parameters:

• html – The html string to add to the page.
• js_deps – A list of js files (absolute path) to be included in the html code.
• css_deps – A list of css files (absolute path) to be included in the html code.

get_template()

Returns:The corresponding jinja2 template for the plot, which can be rendered using:

html = self.get_template().render(element=self)

class webviz.Page(title, icon=None)

Bases: object

Container for PageElement instances. In order to be rendered the Page should be added to a Webviz instance.

Parameters:

• title – String. A title for the page.
• icon – Optional parameter. Name of an icon provided by the webviz.Theme used in the Webviz instance this page will be added to.

add_content(content)

Add a PageElement to the page.

Parameters:content – The PageElement to add. Raises:ValueError if content is not a PageElement.

header_elements

Returns:The set of css dependencies for all page elements in the page

resources

Returns:The set of css dependencies for all page elements in the page

class webviz.SubMenu(title, icon=None)

Bases: object

A submenu is a collection of pages with its own title and icon. The pages in a submenu are grouped together in the naviagation of the Webviz .

Parameters:

• title – The title of the submenu.
• icon – Optional parameter. Name of an icon provided by the webviz.Theme used in the Webviz instance this submenu will be added to.

add_page(page)

Adds a Page to the submenu.

Parameters:page – A Page to add to the submenu. Raises:ValueError if page is not a Page.

location

Returns:The location of the first page, or None if the submenu is empty.

class webviz.Markdown(md)

Bases: webviz._page_element.PageElement

A page element for adding markdown.

get_template()

Returns:The corresponding jinja2 template for the plot, which can be rendered using:

html = self.get_template().render(element=self)

class webviz.PageElement

Bases: object

A page element with data and a template which renders to html.

Each element also has a unique containerId in order to make unique DOM IDs in the template.

get_template()

Returns:The corresponding jinja2 template for the plot, which can be rendered using:

html = self.get_template().render(element=self)

class webviz.Theme

Bases: webviz._theme.Theme

A theme contains the templates and files related to building Webviz instance.

There is one entry template, main.html, which is rendered for each page.

Webviz exposes a set of jinja2 macros that set up includes the content. A minimal example of a theme is as follows:

{% import macros as webviz with context %}
<html>
<head>
{{ webviz.header() }}
</head>
<body>
{% call(banner) webviz.banner() %}
<img src='{{banner}}'></img>
{% endcall %}
<ul>
  {% call(loc, title, current, icon, sub) webviz.iter_menu() %}
    <li> <a href='{{loc}}'> {{icon}} {{title}}</a>
      {% if sub %}
      <ul>
          {% call(sub_loc, sub_title) webviz.iter_sub_menu(sub) %}
              <li><a href='{{sub_loc}}'> {{icon}} {{sub_title}}</a></li>
          {% endcall %}
        </li>
      </ul>
       {% endif %}
  {% endcall %}
</ul>
{{ webviz.content() }}

{% if copyright_notice %}
  {{ copyright_notice }}
{% endif%}
</body>
</html>

See the webviz_default_theme plugin for a more advanced example.

Parameters:

• template_loader – A loader where the main.html, and all the templates it references, can be found.
• css_files – List of additional css files to be included on each page.
• js_files – List of additional js files to be included on each page.
• resources – Dictionary of additional files to be included by the template. The key is the relative location where this resource should be found. For instance, if resources['images'] = ['/absolute/path/to/my_image.jpg'], the image can be included in the template by the resources macro as webviz.resources('images/my_image.jpg').
• icons – A dictionary of icons provided by the theme.

class webviz.JSONPageElement

Bases: webviz._page_element.PageElement

A JSONPageElement is a PageElement which stores some json-data. The data is either assigned to some key in the json store object or otherwise can be accessed as a json-string.

>>> json_page_element['my_json_data'] = {'key': 3}
>>> json_page_element['my_json_data']
{'key': 3}

>>> json_page_element.get_json_dump('my_json_data')
'{"key": 3}'

The json data can be “dumped”, i.e. stored in a key of the json store object.

>>> json_page_element.dump_all_jsons('/my/dir')
{'my_json_data': (json_store['123-567-8910'] = {"key": 3};')}

Asking for the json dump will then instead return a lookup in the json-store:

>>> json_page_element.get_json_dump('my_json_data')
'json_store["123-567-8910"]'

get_js_dep is overriden including js files with assignments to the json store.

dump_all_jsons()

Returns:A map from all json-keys to assignments to the json_store.

>>> json_page_element.dump_all_jsons()
{'my_json_data' : 'json_store["123-567-8910"] = {"data": 3};'}

dump_json_key(key)

Dumps the given json-key.

Raises:KeyError, if there is no value for the given json-key.

get_json_dump(key)

Returns:Dumped value for the given key. Either lookup in store or a json string.

is_dumped(key)

Returns:Whether the json-value with the given key has been dumped.