14.3.131. 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: Iterable[str] | None = 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: Iterable[str] | None = 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: Iterable[str] | None = 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: Iterable[str] | None = 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:

highlight_list – list of crate_anon.crateweb.research.models.Highlight objects, which represent text to find and a colour to highlight it with
at_word_boundaries_only – match at word boundaries only?

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: str | None, element_counter: HtmlElementCounter, sql_not_formatted: bool = False, args: List[Any] | None = 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: 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: Iterable[str] | None = 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: List[Any] | None = 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: Iterable[str] | None = 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: Iterable[str] | None = 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.