uw.web.html package¶
Submodules¶
uw.web.html.bootstrapform module¶
-
uw.web.html.bootstrapform.
parse_bootstrap_date
(form, name)[source]¶ Parse form results from a one-menu date selector.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name – the form result name to use.
-
uw.web.html.bootstrapform.
render_bootstrap_date_range_selector
(name, end, start=datetime.date(2021, 5, 5), current=None, class_=None, disable_days=[], days_of_week_disabled='06')[source]¶ Return form controls for choosing a date with a single input and a visual calendar upon clicking the input.
- Parameters
name – the form control name to use.
end – the last selectable date value.
start – the earlest selectable date value (defaults to today).
current – the initial value of the form controls (defaults to today).
class – CSS class to apply to the input.
disable_days – a list of dates to disable from selecting (date objects).
days_of_week_disabled – a string of week days to disable from selecting (e.g. ‘06’ means weekends are disabled)
- Returns
an HTML input menu controls, for entry of date in the isoformat (yyyy-mm-dd). User can either manually write date or select date from calender.
-
uw.web.html.bootstrapform.
render_bootstrap_date_selector
(name, start=None, current=None, months=4, class_=None, disable_days=[], days_of_week_disabled='06')[source]¶ Return form controls for choosing a date with a single input and a visual calendar upon clicking the input.
- Parameters
name – the form control name to use.
start – the earliest selectable date value
current – the initial value of the form control.
months – the number of months to include.
class – CSS class to apply to the input
disable_dates – a list of dates to disable from selecting (date objects)
days_of_week_disabled – a string of week days to disable from selecting (e.g. ‘06’ means weekends are disabled)
Returns a HTML input menu controls, for entry of date in the isoformat (yyyy-mm-dd). User can either manually write date or select date from calendar.
-
uw.web.html.bootstrapform.
render_bootstrap_form
(rows, class_='', method='get')[source]¶ Returns a submit button styled with bootstrap.
- Parameters
rows – the content of the form, usually created with a list of
render_bootstrap_form_row()
name – the form control name to use.
class – CSS class to apply to the button
-
uw.web.html.bootstrapform.
render_bootstrap_form_row
(form_tuples, head_class=None, tail_class=None)[source]¶ Wrapper functions intended for creating a bootstrap ‘row’ of elements with optional labels. Renders a tuples contraining a tuple consisting of an optional label followed by a form div.
- Parameters
form_tuples – a list in the form [(label_name, input, class)] where in each tuple: label_name: Is a string that is used as a label, if False, label is unsed A pre_rendered input object (e.g. input, select, checkmark), assumes it has the ‘form-control’ class Classes to add to individual bootstrap column sizes (e.g. ‘col-xs-6’) used for the label and input
head_class – a class to be applied to the label div (first)
tail_class – a class to be applied to the inputs div (last)
-
uw.web.html.bootstrapform.
render_bootstrap_submit
(value, class_='', name='')[source]¶ Returns a submit button styled with bootstrap.
- Parameters
value – the name and value of the submit button
name – the form control name to use.
class – CSS class to apply to the button
-
uw.web.html.bootstrapform.
render_bootstrap_upload
(accept='', name='')[source]¶ Make a select element with a given name and given option values.
- Parameters
name – the form control name to use.
accept – the accept property of the file input element e.g. ‘image/*’ limiting what types of file the user can select
-
uw.web.html.bootstrapform.
render_bootstrap_upload_submit
(submit_name='', upload_name='', accept='')[source]¶ Render a file upload with a submit button.
- Parameters
submit_name – form name for the submit button
upload_name – form name for the submitted file
accept – the accept property of the file input element e.g. ‘image/*’ limiting what types of file the user can select
Returns the html for a button that has the ability to enter copytext into the clipboard when clicked.
- Parameters
name – Text to be displayed on button
copytext – Text to be copied on clicked
value – Value attribute for button (needed for ZeroClipboard)
class – CSS class(es) to apply to button
-
uw.web.html.bootstrapform.
render_icon
(glyphicon_icon)[source]¶ Parse form results for a combined date and time.
- Parameters
glyphicon_icon – a string with the final component of the name, e.g. ‘pencil’ for glyphicon-pencil. See full list: http://glyphicons.com/
Uses the specified parse_date and parse_time to parse the date and time, respectively, from the form results, using the specified form result name with “d” and “t” appended. The result is a datetime.datetime.
uw.web.html.form module¶
Form generation routines.
Simple routines for generating HTML form elements and parsing the corresponding form submission results.
-
uw.web.html.form.
advance_month
(day)[source]¶ Add one month to the given date.
- Parameters
day (datetime.date) – a date.
Returns the date one month later.
-
uw.web.html.form.
monthrange
(start, months)[source]¶ Iterate through months, represented as date objects.
- Parameters
start – the starting date.
months – the number of months to span.
The first result is start with the day forced to 1. Subsequent results correspond to the 1st of each succeeding month, until months months later. Note that the actual number of months returned will be one greater if the start day is not 1. The idea is to yield all months that include days within the specified number of months of the start date.
-
uw.web.html.form.
parse_date_1
(form, name)[source]¶ Parse form results from a one-menu date selector.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name (str) – the form result name to use.
Returns the date specified by the form results. This is meant to be used with
render_date_hidden_1()
orrender_date_selector_1()
.
-
uw.web.html.form.
parse_date_2
(form, name)[source]¶ Parse form results from a two-menu date selector.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name – the form result name prefix.
Returns the date specified by the form results. The form result names used begin with the specified name, with “ym” and “d” appended. This is compatible with render_date_selector_2 and is meant to be used with that function.
-
uw.web.html.form.
parse_datetime
(form, name, parse_date, parse_time)[source]¶ Parse form results for a combined date and time.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name – the form result name prefix.
parse_date – the parser to use for the date.
parse_time – the parser to use for the time.
Uses the specified parse_date and parse_time to parse the date and time, respectively, from the form results, using the specified form result name with “d” and “t” appended. The result is a datetime.datetime.
-
uw.web.html.form.
parse_time_1
(form, name)[source]¶ Parse form results from a one-menu time selector.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name (str) – the form result name to use.
Returns the time specified by the form results. This is meant to be used with
render_time_selector_1()
.
-
uw.web.html.form.
parse_time_2
(form, name)[source]¶ Parse form results from a two-menu time selector.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name – the form result name prefix.
Returns the time specified by the form results. The form result names used begin with the specified name, with “h” and “m” appended. This is compatible with render_time_selector_2 and is meant to be used with that function.
-
uw.web.html.form.
render_check_radio
(name, checked=False, value='', fixed=False, type=None, class_=None)[source]¶ Return an HTML <input> which is a checkbox or radio button.
- Parameters
name – the form control name to use.
checked – whether the radio button should be checked.
value – the value to associate with the form control.
fixed – whether the control should be fixed and uneditable.
type – either “radio” or “checkbox” as appropriate.
class – CSS class to be applied to input
If fixed is specified, the result is a disabled form control <input> together with a hidden <input> representing the name/value pair. If fixed is not specified, the result is a regular form control <input> with the name/value pair set directly.
HTML implementation note: we tried to use Unicode characters, as follows:
- if type == “checkbox”:
fixed_text = [u’◻’, u’◼’]
- elif type == “radio”:
fixed_text = [u’⚪’, u’⚫’]
Unfortunately, apparently not supported by all browsers. Disabled controls cannot be successful, so still need to render chosen button or checkbox as hidden.
-
uw.web.html.form.
render_checkbox
(name, checked=False, value='', fixed=False, class_=None)[source]¶ Return an HTML <input> which is a checkbox.
- Parameters
name – the form control name to use.
checked – whether the checkbox should be checked.
value – the value to associate with the form control.
fixed – whether the control should be fixed and uneditable.
class – a css class to be applied to the checkbox
If fixed is specified, the result is a disabled checkbox <input> together with a hidden <input> representing the name/value pair. If fixed is not specified, the result is a regular checkbox <input> with the name/value pair set directly.
Render a date as an HTML hidden control.
- Parameters
name – the form control name to use.
current – the date to use.
Returns an HTML hidden form control representing the specified date.
-
uw.web.html.form.
render_date_selector_1
(name, current=None, start=None, days=None, dates=None, class_=None)[source]¶ Return form controls for choosing a date with a single pull-down menu.
- Parameters
name (str) – The form control name to use.
current (datetime.date) – The initial value of the control.
start (datetime.date) – The earliest selectable date, or None for today (if dates is None).
days (int) – The number of days to include (if dates is None).
dates (list) – The dates to include (or None to use start and days).
class (str) – CSS class to apply to result.
-
uw.web.html.form.
render_date_selector_2
(name, current=None, start=None, months=12, class_=None)[source]¶ Return form controls for choosing a date with two pull-down menus.
- Parameters
name – the form control name to use.
current – the initial value of the form control.
start – the earliest selectable date.
months – the number of months to include.
Returns two HTML pulldown menu controls, one for year and month, the other for the day within the month. This is intended for selecting a date within a range of a few months, where it would not make sense to have a separate year selector that only allowed one or two choices.
Return hidden controls equivalent to a form result.
- Parameters
form (uw.web.wsgi.form.CGIFormResults) – form results.
name – the form result name.
Pulls all the values from the specified form results associated with the given form control name, and produces a list of HTML form hidden controls corresponding to the values.
Return an HTML <input> which is a hidden control.
- Parameters
name – the form control name to use.
value – the value to associate with the form control.
-
uw.web.html.form.
render_multi_select
(name, form_values, values={}, blank=False, class_=None)[source]¶ Make a multi select element with a given name and given option values.
- Parameters
name – the form control name to use.
values – the values to associate with the form control, expressed as a sequence of tuples (code, label), where the code is the value used to report the form value while the label is what will be displayed to the user.
values – the code(s) of the alternative that should be selected by as a list, or None to indicate that an extra blank option should be selected instead.
blank – whether the extra blank option should always be included.
multiple – whether the select should have multiple selectable options
class – a string to be applied as a css class to the select element.
-
uw.web.html.form.
render_radio
(name, checked=False, value='', fixed=False)[source]¶ Return an HTML <input> which is a radio button.
- Parameters
name – the form control name to use.
checked – whether the radio button should be checked.
value – the value to associate with the form control.
fixed – whether the control should be fixed and uneditable.
If fixed is specified, the result is a disabled radio button <input> together with a hidden <input> representing the name/value pair. If fixed is not specified, the result is a regular radio button <input> with the name/value pair set directly.
-
uw.web.html.form.
render_select
(name, values, value=None, blank=False, class_=None)[source]¶ Make a select element with a given name and given option values.
- Parameters
name – the form control name to use.
values – the values to associate with the form control, expressed as a sequence of tuples (code, label), where the code is the value used to report the form value while the label is what will be displayed to the user.
value – the code of the alternative that should be selected by default, or None to indicate that an extra blank option should be selected instead.
blank – whether the extra blank option should always be included.
class – a string to be applied as a css class to the select element.
-
uw.web.html.form.
render_time_selector_1
(name, current=None, times=None, class_=None)[source]¶ Return form controls for choosing a time with a single pull-down menu.
- Parameters
name (str) – The form control name to use.
current (datetime.time) – The initial value of the control.
times (list) – List of times to allow choosing.
class (str) – CSS class to apply to result.
-
uw.web.html.form.
render_time_selector_2
(name, start, hours, current=None, class_=None)[source]¶ Return form controls for choosing a time with two pull-down menus.
- Parameters
name – the form control name to use.
start – the earliest selectable time.
hours – the number of hours to include.
current – the initial value of the form controls.
Returns two HTML pulldown menu controls, one for hour, the other for the minute within the hour. This is intended for selecting a time within a range of a few hours.
uw.web.html.format module¶
Miscellaneous HTML formatting routines.
Routines for formatting various objects as HTML, a convenience routine for slightly simplifying the provision of manually-generated “breadcrumb” links, and a routine for formatting simple HTML tables.
-
uw.web.html.format.
format
(item)[source]¶ Format an item as HTML.
- Parameters
item – a value to format as HTML in a reasonable default way.
If the input is None, the output is None. If the input is a datetime type, the .isoformat() method is used. Otherwise, the item is converted to a string using str().
-
uw.web.html.format.
format_date
(date, none=None)[source]¶ Format a date in the standard ISO 8601 form.
- Parameters
date – The date to format (datetime.date) or None.
none – The value to use if the input is None.
Formats the date in the standard ISO 8601 format. If the input is None or the maximum date or datetime, the output is the specified alternate value or None.
-
uw.web.html.format.
format_datetime
(time, none=None)[source]¶ Format a datetime in the standard ISO 8601 form.
- Parameters
time – The datetime to format (datetime.datetime) or None.
none – The value to use if the input is None.
Formats the datetime in the standard ISO 8601 format, to the minute. If the input is None or the maximum datetime, the output is the specified alternate value or None.
-
uw.web.html.format.
format_email
(email, subject=None)[source]¶ Format an email address as HTML.
- Parameters
email – an email address.
Returns a mailto link for the specified email address.
-
uw.web.html.format.
format_expandable_div
(lst)[source]¶ Format a list of expandable div name and expandable div content pairs as html.
- Parameters
lst – List of (Name, Content) of the expandable divs.
- Returns
Formatted HTML for WCMS expandable divs from a list of div title and div content tuples.
-
uw.web.html.format.
format_return
(*names, **keys)[source]¶ Return HTML formatting of “breadcrumbs”.
- Parameters
*names – the short titles to use for href=”..”, href=”../..”, etc.
keys['dot'] – the short title to use for href=”.”.
Returns an HTML <p> with relative links to parent directories corresponding to the parameter names provided, and possibly an additional link to the current directory if a “dot” keyword argument is provided. The link text is the provided names. If a provided name is None, the corresponding link is skipped.
This is a way of making it easy to jump back from a detailed page to a higher level of the application. Unfortunately higher levels of the navigation tend to get repeated everywhere.
TODO: implement real breadcrumbs integrated with a menu system and with page titles.
-
uw.web.html.format.
format_tabs
(lst, active_id=None)[source]¶ Format a list of tab name, tab id, and tab content triples as HTML.
- Parameters
lst – List of (tab name, tab id, tab content).
active_id – id of the default tab.
- Returns
Formatted HTML for WCMS tabs that is recognizable by the WCMS CSS and Javascript.
-
uw.web.html.format.
format_time
(time, none=None)[source]¶ Format a time in the standard ISO 8601 form.
- Parameters
time – The date to format (datetime.time) or None.
none – The value to use if the input is None.
Formats the time in the standard ISO 8601 format. If the input is None, the output is the specified alternate value or None.
-
uw.web.html.format.
make_table_format
(*columns, **keys)[source]¶ Compute a function for producing an HTML <table>.
- Parameters
columns – a list of column definitions.
keys['header_row'] – a function to be invoked before the first item row which may also return an extra row.
keys['before_row'] – a function to be invoked before each item row which may also return an extra row.
keys['after_row'] – a function to be invoked after each item row which may also return an extra row.
keys['footer_row'] – a function to be invoked after the last item row which may also return an extra row.
keys['row_attributor'] – a function to be invoked on each item which returns a dictionary of attributes for the <tr> element.
keys['use_colgroup'] – whether or not to include an HTML <colgroup> element at the beginning of the table.
Returns a function which, when passed a list of items, returns an HTML <table> with one column for each entry in columns, and one row for each item in the list of items, as well as a header row and possibly some additional rows depending on the optional keyword parameters supplied.
Each element of columns is a column definition, which is a 4-tuple consisting of:
an HTML <col> element for the column;
the HTML contents of the header for the column;
a function which takes an item and returns HTML for the column;
- a function which takes an item and returns HTML attributes for the <td>
element.
The later elements of the tuple may be omitted in which case appropriate neutral values will be used. The <col> element may also be omitted; this case is recognized when the first element of the tuple is not an ll.xist.ns.html.col object.
The *_row keyword parameters specify additional computations to take place at the noted point in computation of the result table. They may also return additional rows if that is useful in a particular use. One use of this is for header_row to initialize counters or totals, and footer_row to produce a row which displays the final results.
uw.web.html.join module¶
Routines for rendering lists of items as HTML.
Contains a routine for rendering a list as a typical English sentence, and one for rendering a list with a specified separator between the items.
-
uw.web.html.join.
english_join
(*items)¶ Join a list of items in typical English style.
- Parameters
jointext (str) – The conjunction (“and” or “or”) to be used to join the items.
*items – the list of HTML fragments to join.
This is for putting together lists of items in English text. For two items, they are simply joined by putting the conjunction between them. For more than two items, they are joined by commas, and the conjunction is inserted before the last one. A single item is returned unmodified. If no items are supplied, the result is None.
The items are preprocessed by removing any items that are None.
-
uw.web.html.join.
english_join_and
(*items)¶ Join a list of items in typical English style.
- Parameters
jointext (str) – The conjunction (“and” or “or”) to be used to join the items.
*items – the list of HTML fragments to join.
This is for putting together lists of items in English text. For two items, they are simply joined by putting the conjunction between them. For more than two items, they are joined by commas, and the conjunction is inserted before the last one. A single item is returned unmodified. If no items are supplied, the result is None.
The items are preprocessed by removing any items that are None.
-
uw.web.html.join.
english_join_flex
(jointext, *items)[source]¶ Join a list of items in typical English style.
- Parameters
jointext (str) – The conjunction (“and” or “or”) to be used to join the items.
*items – the list of HTML fragments to join.
This is for putting together lists of items in English text. For two items, they are simply joined by putting the conjunction between them. For more than two items, they are joined by commas, and the conjunction is inserted before the last one. A single item is returned unmodified. If no items are supplied, the result is None.
The items are preprocessed by removing any items that are None.
-
uw.web.html.join.
english_join_or
(*items)¶ Join a list of items in typical English style.
- Parameters
jointext (str) – The conjunction (“and” or “or”) to be used to join the items.
*items – the list of HTML fragments to join.
This is for putting together lists of items in English text. For two items, they are simply joined by putting the conjunction between them. For more than two items, they are joined by commas, and the conjunction is inserted before the last one. A single item is returned unmodified. If no items are supplied, the result is None.
The items are preprocessed by removing any items that are None.
-
uw.web.html.join.
html_join
(items, sep=None)[source]¶ Join a list of HTML items with the specified HTML separator.
- Parameters
items – the list of HTML fragments to join.
sep – an HTML fragment to use for the separator, if any.
This is for putting together lists of items where a separator is required between each adjacent pair of items. A single item is returned unmodified. If no items are supplied, the result is None.
The items are preprocessed by removing any items that are None.
uw.web.html.sorttable module¶
Sort table routines.
This module makes it easy to use tables that can be sorted by clicking the headers.
The main routine provided by this module is render_sort_table()
. In
order for this to work, the header_insert provided to
uw.local.webtools.web_main()
should include the header_insert values
from this module.
-
uw.web.html.sorttable.
make_table_format_sortable
(*columns, **keys)[source]¶ Compute a function for producing an HTML <table> which is sortable.
- Parameters
columns – a list of column definitions.
keys['header_row'] – a function to be invoked before the first item row which may also return an extra row.
keys['before_row'] – a function to be invoked before each item row which may also return an extra row.
keys['after_row'] – a function to be invoked after each item row which may also return an extra row.
keys['footer_row'] – a function to be invoked after the last item row which may also return an extra row.
keys['row_attributor'] – a function to be invoked on each item which returns a dictionary of attributes for the <tr> element.
Returns a function which, when passed a list of items, returns an HTML <table> with one column for each entry in columns, and one row for each item in the list of items, as well as a header row and possibly some additional rows depending on the optional keyword parameters supplied.
Each element of columns is a column definition, which is an instance of
table_column
.The *_row keyword parameters specify additional computations to take place at the noted point in computation of the result table. They may also return additional rows if that is useful in a particular use. One use of this is for header_row to initialize counters or totals, and footer_row to produce a row which displays the final results.
-
class
uw.web.html.sorttable.
table_column
[source]¶ Bases:
uw.web.html.sorttable.table_column
A namedtuple class representing the definition of a table column.
The namedtuple elements are col, head, content, attr, and sort_style. The constructor of this class, however, allows omitting elements, in which case the natural default will be used in each case. An additional sort_order element may be provided, which should be a function from a data row to a sort order value. This is a convenient way of adding the data-sort-value attribute which could otherwise be provided by the attr function.
Module contents¶
HTML generation routines.
This package contains various routines for generating HTML. Uses the ll.xist library to generate HTML structures that can be included in larger HTML pages and serialized to text later.