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
[source]¶ 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')[source]¶ Bases:
object
An instance of
Webviz
is a collection ofPage
instances, and optionally alsoSubMenu
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)[source]¶ Adds an item to the top-level navigation bar of the
Webviz
instance.Parameters: menu_item – A Page
orSubmenu
to add to theWebviz
instance.Raises: ValueError
, ifmenu_item
is neitherPage
nor aSubMenu
.
-
write_html
(destination, display=False, overwrite=False)[source]¶ 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
ifoverwrite
isFalse
and destination folder exists.
-
-
class
webviz.
Html
(html, js_deps=[], css_deps=[])[source]¶ 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.
-
class
webviz.
Page
(title, icon=None)[source]¶ Bases:
object
Container for
PageElement
instances. In order to be rendered thePage
should be added to aWebviz
instance.Parameters: - title – String. A title for the page.
- icon – Optional parameter. Name of an icon provided by the
webviz.Theme
used in theWebviz
instance this page will be added to.
-
add_content
(content)[source]¶ Add a
PageElement
to the page.Parameters: content – The PageElement
to add.Raises: ValueError
ifcontent
is not aPageElement
.
-
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)[source]¶ 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 theWebviz
instance this submenu will be added to.
-
add_page
(page)[source]¶ Adds a
Page
to the submenu.Parameters: page – A Page
to add to the submenu.Raises: ValueError
ifpage
is not aPage
.
-
location
¶ Returns: The location of the first page, or None if the submenu is empty.
-
class
webviz.
Markdown
(md)[source]¶ Bases:
webviz._page_element.PageElement
A page element for adding markdown.
-
class
webviz.
PageElement
[source]¶ 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.
-
class
webviz.
Theme
[source]¶ 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 aswebviz.resources('images/my_image.jpg')
. - icons – A dictionary of icons provided by the theme.
- template_loader – A loader where the
-
class
webviz.
JSONPageElement
[source]¶ Bases:
webviz._page_element.PageElement
A
JSONPageElement
is aPageElement
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
()[source]¶ 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)[source]¶ Dumps the given json-key.
Raises: KeyError, if there is no value for the given json-key.
-