14.3.126. crate_anon.crateweb.research.html_functions

crate_anon/crateweb/research/html_functions.py

Copyright (C) 2015, University of Cambridge, Department of Psychiatry. Created by Rudolf Cardinal (rnc1001@cam.ac.uk).

This file is part of CRATE.

CRATE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

CRATE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with CRATE. If not, see <https://www.gnu.org/licenses/>.

Helper functions for low-level HTML, used in the “research” section of the CRATE web site.

class crate_anon.crateweb.research.html_functions.HtmlElementCounter(prefix: str = '')[source]

Class to maintain element counters, for use with pages having lots of collapsible divs (or other HTML elements requiring individual numbering).

__init__(prefix: str = '') → None[source]
Parameters

prefix – text to be prefixed to the tag used for HTML elements

collapsible_div_contentdiv(contents: str, extra_div_classes: Optional[Iterable[str]] = None, small: bool = True) → str[source]

Returns a “collapsible” content <div>

Parameters

  • contents – HTML contents of the div

  • extra_div_classes – extra CSS classes to add to the content div

  • small – start collapsed, rather than expanded?

Returns

HTML

Return type

str

next() → None[source]

Increments the elementnum counter.

overflow_div(contents: str, extra_div_classes: Optional[Iterable[str]] = None, small: bool = True) → str[source]

Returns a “overflow” <div> with content and an expand/collapse button.

Parameters

  • contents – HTML contents of the div

  • extra_div_classes – extra CSS classes to add to the content div

  • small – start collapsed, rather than expanded?

Returns

HTML

Return type

str

tag() → str[source]

Returns a tag based on the prefix and current element number.

visibility_div_contentdiv(contents: str, extra_div_classes: Optional[Iterable[str]] = None, small: bool = True) → str[source]

Returns a “visibility” content <div>.

Parameters

  • contents – HTML contents of the content div

  • extra_div_classes – extra CSS classes to add to the div

  • small – start invisible, rather than visible?

Returns

HTML

Return type

str

visibility_div_spanbutton(small: bool = True) → str[source]

Returns a visibility button in an HTML <span>.

Parameters

small – start in “hidden” rather than “visible” mode?

Returns

HTML

Return type

str

visibility_div_with_divbutton(contents: str, title_html: str = '', extra_div_classes: Optional[Iterable[str]] = None, small: bool = True) → str[source]

Returns a “visibility” <div> with a show/hide button.

Parameters

  • contents – HTML contents of the content div

  • title_html – HTML to put inside the button element

  • extra_div_classes – extra CSS classes to add to the content div

  • small – start invisible, rather than visible?

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.escape_literal_string_for_regex(s: str) → str[source]

Escape any regex characters.

  • Start with ` -> `\``. This should be the first replacement in REGEX_METACHARS.

crate_anon.crateweb.research.html_functions.get_regex_from_highlights(highlight_list: Iterable[Highlight], at_word_boundaries_only: bool = False) → Pattern[source]

Takes a list of the user’s chosen highlights to apply to results, and builds a compiled regular expression for (any of) them.

Parameters
Returns

a compiled regular expression (case-insensitive)

crate_anon.crateweb.research.html_functions.highlight_text(x: str, n: int = 0) → str[source]

Transforms text (from a query result) into HTML that highlights it.

Parameters

  • x – original text

  • n – highlight colour number to use (as per our static/base.css)

Returns:

crate_anon.crateweb.research.html_functions.make_collapsible_sql_query(sql: Optional[str], element_counter: crate_anon.crateweb.research.html_functions.HtmlElementCounter, sql_not_formatted: bool = False, args: Optional[List[Any]] = None, collapse_at_len: int = 400, collapse_at_n_lines: int = 5) → str[source]

Formats an SQL query (and its arguments, if any) in a collapsible HTML <div>.

Parameters

  • sql – SQL text

  • element_counter –

  • args – optional list of arguments

  • sql_not_formatted – is the sql already highlighted and formatted?

  • collapse_at_len – if specified, the string length beyond which the cell will be collapsed

  • collapse_at_n_lines – if specified, the number of lines beyond which the cell will be collapsed

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.make_highlight_replacement_regex(n: int = 0) → str[source]

Makes a regex replacement string that highlights the first “found” group with a specific highlight colour.

Parameters

n – highlight colour number to use (as per our static/base.css)

Returns

regex text like <span class="highlight1">\1</span>

Return type

str

crate_anon.crateweb.research.html_functions.make_result_element(x: Any, element_counter: crate_anon.crateweb.research.html_functions.HtmlElementCounter, highlight_dict: Dict[int, List[Highlight]] = None, collapse_at_len: int = None, collapse_at_n_lines: int = None, line_length: int = None, keep_existing_newlines: bool = True, collapsed: bool = True, null: str = '<i>NULL</i>') → str[source]

Returns a collapsible HTML <div> for a result cell, with optional highlighting of results.

Parameters

  • x – the value

  • element_counter – a :class:HtmlElementCounter, used for distinguishing multiple elements; it will be modified

  • highlight_dict – an optional dictionary mapping highlight colour to all the crate_anon.crateweb.research.models.Highlight objects that use it (e.g.: 2 maps to highlight objects for all the separate pieces of text to be highlighted in colour 2)

  • collapse_at_len – if specified, the string length beyond which the cell will be collapsed

  • collapse_at_n_lines – if specified, the number of lines beyond which the cell will be collapsed

  • line_length – if specified, the line length to word-wrap at

  • keep_existing_newlines – retain existing newlines from the source?

  • collapsed – start cells collapsed rather than expanded?

  • null – HTML string to use for database NULL values

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.overflow_div(tag: str, contents: str, extra_div_classes: Optional[Iterable[str]] = None, small: bool = True) → str[source]

Returns an HTML <div> with an expand/collapse button and contents.

Parameters

  • tag – tag used for this set of elements; used as part of the parameters to Javascript toggleVisible or toggleCollapsed functions; see crate_anon/crateweb/static/collapse.js

  • contents – HTML contents of the content div

  • extra_div_classes – extra CSS classes to add to the content div

  • small – start collapsed rather than expanded?

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.pre(x: str = '') → str[source]

Applies an HTML <pre>...</pre> tag.

Parameters

x – input

Returns

the input within a pre tag

crate_anon.crateweb.research.html_functions.prettify_sql_and_args(sql: str, args: Optional[List[Any]] = None, sql_not_formatted: bool = True, reformat: bool = False, indent_width: int = 4) → str[source]

Returns HTML for both some SQL and its arguments.

Parameters

  • sql – SQL text

  • args – optional list of arguments

  • sql_not_formatted – is the sql already highlighted and formatted?

  • reformat – reformat the layout?

  • indent_width – if reformatting, what indent should we use?

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.prettify_sql_html(sql: str, reformat: bool = False, indent_width: int = 4) → str[source]

Formats SQL (optionally), and highlights it with Pygments.

Parameters

  • sql – raw SQL text

  • reformat – reformat the layout?

  • indent_width – if reformatting, what indent should we use?

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.visibility_button(tag: str, small: bool = True, title_html: str = '', as_span: bool = False, as_visibility: bool = True) → str[source]

Returns HTML for a “(+)/(-)” button. Used for:

  • visibility (show/hide): to show/hide things

  • collapse (expand/collapse): to collapse large cells in query results.

Parameters

  • tag – tag used for this set of elements; used as part of the parameters to Javascript toggleVisible or toggleCollapsed functions; see crate_anon/crateweb/static/collapse.js

  • small – start small (or invisible) rather than big (or visible)?

  • title_html – HTML to put inside the element

  • as_span – return a <span> element rather than a <div> element?

  • as_visibility – “visibility” style, rather than “collapse” style?

Returns

HTML

Return type

str

See visibility_contentdiv() for the associated content.

crate_anon.crateweb.research.html_functions.visibility_contentdiv(tag: str, contents: str, extra_div_classes: Optional[Iterable[str]] = None, small: bool = True, as_visibility: bool = True) → str[source]

Returns HTML for a content <div> that can be collapsed by a button (for which, see visibility_button()).

Parameters

  • tag – tag used for this set of elements; used as part of the parameters to Javascript toggleVisible or toggleCollapsed functions; see crate_anon/crateweb/static/collapse.js

  • contents – HTML contents of the div

  • extra_div_classes – extra CSS classes to add to the div

  • small – start small (or invisible) rather than big (or visible)?

  • as_visibility – “visibility” style, rather than “collapse” style?

Returns

HTML

Return type

str

crate_anon.crateweb.research.html_functions.visibility_div_with_divbutton(tag: str, contents: str, title_html: str = '', extra_div_classes: Optional[Iterable[str]] = None, small: bool = True) → str[source]

Returns an HTML <div> with a show/hide button and contents.

Parameters

  • tag – tag used for this set of elements; used as part of the parameters to Javascript toggleVisible or toggleCollapsed functions; see crate_anon/crateweb/static/collapse.js

  • contents – HTML contents of the content div

  • title_html – HTML to put inside the button element

  • extra_div_classes – extra CSS classes to add to the content div

  • small – start invisible rather than visible?

Returns

HTML

Return type

str

  • The HTML pre-hides, rather than using an onload method.