ImageMetaTag.webpage

This sub-module contains functions to write out an ImageMetaTag.ImageDict to a webpage.

The webpages are made up of a single .html file, which is the page to be loaded to view the images. Alongside this is a short ImageMetaTag javascript library held in a ‘.js’ file (currently held in a single file) and a .json file contain the ImageMetaTag.ImageDict tree strcuture as a JSON data strcuture.

To reduce file size, the JSON data structure can be compressed using zlib. If this is the case, then the pako javascript library is used restore the JSON data in the browser.

This can either be done using write_full_page, to produce a page with just a set of selectors to browse the ImageDict, or the different components can be added to a page as it is being constructed (reading in an html template, for instance).

To write out a full page, use ImageMetaTag.webpage.write_full_page().

If the latter, then the following sections are needed:

An easy example of creating a webpage, using an ImageMetaTag.ImageDict is shown in simplest_image_dict.py

Tip

At present, the only webpage style that can be produced is a set of horizontal dropdownmenus, but more will hopefully be added soon.

(C) Crown copyright Met Office. All rights reserved. Released under BSD 3-Clause License. See LICENSE for more details.

Writing a whole page

ImageMetaTag.webpage.write_full_page(img_dict, filepath, title, page_filename=None, tab_s_name=None, preamble=None, postamble=None, postamble_no_imt_link=False, compression=False, initial_selectors=None, show_selector_names=False, show_singleton_selectors=True, optgroups=None, url_type='int', only_show_rel_url=False, verbose=False, style='horiz dropdowns', write_intmed_tmpfile=False, description=None, keywords=None, css=None, load_err_msg=None, last_img_in_list_is_slider=False, last_img_still_show=False)[source]

Writes out an ImageMetaTag.ImageDict as a webpage, to a given file location. The files are created as temporary files and when complete they replace any files that are currently in the specified location.

If the img_dict supplied is None, rather than the appropriate class, then a page will be produced with the image selectors missing, and a message saying no images are available.

Currently only able to write out a page with horizontal dropdown menus, but other webpage styles could be added.

Options:

  • page_filename - the file name, within the directory (defaults to the name of the file) but can be set if tab_s_name is also used.

  • tab_s_name : used to denote the name of the page, when it is used as a frame of a larger page.

  • preamble : html text added at the top of the <body> text, but before the ImageMetaTag section. Can be quite extensive.

  • postable : html text added after the ImageMetaTag section. A link to the ImageMetaTag documentation will be appended unless postamble_no_imt_link is True.

  • postamble_no_imt_link : if True, no link to the ImageMetaTag documentation will be added to the postamble.

  • initial_selectors - A list of initial values for the selectors, to be passed into ImageMetaTag.webpage.write_js_setup().

  • show_selector_names - switches on displaying the selector full names defined by the ImageMetaTag.ImageDict.full_name_mapping

  • show_singleton_selectors - When set to False, selectors that have only one element are not displayed (default=True).

  • optgroups - The contents of selectors can be grouped together to make large lists more readable. This is passed into ImageMetaTag.webpage.write_js_to_header().

  • url_type - determines the type of URL at the bottom of the ImageMetaTag section. Can be ‘int’ or ‘str’.

  • only_show_rel_url - If True, the wepage will only show relative urls in is link section.

  • verbose - If True, stdout will be more verbose

  • style - the style of output page to write, currently only ‘horiz dropdowns’ is valid

  • write_intmed_tmpfile - If True, files are written out to temporary filenames and then moved when completed.

  • description - html description metadata

  • keywords - html keyword metadata

  • compression - default False. If True, then the json data object will be compressed using zlib string compression. When read into the browser, we will use pako to inflate it (https://github.com/nodeca/pako)

  • css - Optional CSS file used to style webpage. By default a small amount of css is written out in the page header.

  • load_err_msg - additional message to show after ‘Please wait while the page is loading’. default is None, but very large pages can crash with Internet Explorer so a message along the lines of this may be useful: ‘If the page does not load correctly in Internet Explorer, please try using firefox or Chrome.’

  • last_img_in_list_is_slider - for the ‘horiz dropdowns’ page style, when the image payload contains a list of images, then when this is True, the last images is used as an on overlay/slider on the other images.

  • last_img_still_show - when last_img_in_list_is_slider applies a set of sliders, this toggles whether or not the last image is still shown, as a static image or not.

Returns a list of files that the the created webpage is dependent upon.

As indidividual components

ImageMetaTag.webpage.write_js_to_header(img_dict, initial_selectors=None, optgroups=None, style=None, file_obj=None, json_files=None, js_css_files=None, pagename=None, tabname=None, selector_prefix=None, show_singleton_selectors=True, url_separator='|', url_type='str', only_show_rel_url=False, ind=None, compression=False, last_img_in_list_is_slider=False, last_img_still_show=False, description=None, keywords=None)[source]

Writes out the required ImageMetaTag config and data paths into a html header section for an input ImageMetaTag.ImageDict.

Currently only able to write out a page with horizontal dropdown menus, but other webpage styles could be added.

  • initial_selectors - A list of initial values for the selectors.

  • optgroups - The contents of selectors can be grouped together to make large lists more readable. These groups are specified as a 2-level dictionary where the first level is the index of the selectors to have groups. The second level contains the {‘group name’: [contents]}.

    By specifying an optgroup, the order of the elements in a selector uses the optgroups first. By default the optgroup names are sorted, but the order of the optgroups can be specified by including a ‘imt_optgroup_order’: [ordered list of opgroup names], in a second level dictionary that specifies the ‘group name’: [contents] Within each optgroup the order of elements is taken from their order in the image dict.

  • style - the style of the output webpage, currently only ‘horiz dropdowns’ is available

  • file_obj - the open file object to write the header to.

  • json_files - a list of the json (or other similar object) containing the representation of the ImageDict data.

  • js_file - the javascript file containing the actual scripting for the selected style.

  • pagename - the file name, within the directory (defaults to the name of the file) but can be set if tab_s_name is also used.

  • tabname : used to denote the name of the page, when it is used as a frame of a larger page.

  • selector_prefix - prefix to use for javascript selector names (defaults to ‘sel’)

  • show_singleton_selectors - When set to False, selectors that have only one element are not displayed (default=True).

  • url_type - determines the type of URL at the bottom of the ImageMetaTag section. Can be ‘int’ or ‘str’.

  • only_show_rel_url - If True, the wepage will only show relative urls in is link section.

  • ind - indentation going into the header section.

  • compression - Indicates the json file is compressed using zlib.

  • last_img_in_list_is_slider - indicates the last image in a list of images in a payload should be used as an overlay/slider

  • last_img_still_show - if last_img_in_list_is_slider, then this controls if the last image is shown as a static image or not, at the end.

  • description - html description metadata7

  • keywords - html keyword metadata

ImageMetaTag.webpage.write_js_placeholders(img_dict, file_obj=None, dict_depth=None, selector_prefix=None, style='horiz dropdowns', level_names=False, show_singleton_selectors=True, last_img_in_list_is_slider=False, animated_level=None, load_err_msg=None)[source]

Writes the placeholders into the page body, for the javascript to manipulate

  • file_obj - an open file object to write to

  • dict_dept - the depth of the ImageMetaTag.ImageDict being written

  • selector_prefix - prefix for the variable names of the selectors (these are visible to people viewing the webpage!)

  • style - In future, it would be great to write out different types of webpages. For now they are always horizontal dropdown menus.

  • show_singleton_selectors - When set to False, selectors that have only one element are not displayed (default=True).

  • level_names - if supplied, this need to be a list of full names, for the selectors, of length dict_depth.

  • animated_level - if supplied, as a string, this will be used to label the animator buttons.

  • load_err_msg - additional message to show after ‘Please wait while the page is loading’. default is None, but very large pages can crash with Internet Explorer so a message along the lines of this may be useful: ‘If the page does not load correctly in Internet Explorer, please try using firefox or Chrome.’

ImageMetaTag.webpage.write_json(img_dict, file_name_no_ext, compression=False, chunk_char_limit=10000000.0)[source]

Writes a json dump of the ImageMetaTag.ImageDict tree strucuture to a target file path.

Options:

  • compression : If True, json is compressed using zlib compresion

  • chunk_char_limit : large strings are split into chunks for memory efficency in the browser.

Returns a list of json files as (tempfile, final_file) tuples.

ImageMetaTag.webpage.copy_required_js_css_etc(file_dir, style, compression=False, last_img_in_list_is_slider=False, overwrite=True)[source]

Copies the required javascript library to the directory containing the required page (file_dir) for a given webpage style.

If a file is already present it will be checked based it’s first line. If the file is different, it will be overwritten if overwrite is True.

Also copies/obtains required javascript for reading files compressed with zlib, if compression=True.