Module reahl.web.ui¶

Basic Widgets and related user interface elements.

Widgets for constructing a page¶

HTML5Page¶

class reahl.web.ui.HTML5Page(view, title='$current_title', style=None, css_id=None)¶

A web page that may be used as the page of a web application. It ensures that everything needed by the framework (linked CSS and JavaScript, etc) is available on such a page.

Styling

Renders as an HTML5 page with customised <head> and an empty <body>.

Parameters:	view – (See `reahl.web.fw.Widget`) title – Text for a template to be used as document Title (See also `Title`). style – Pass a string denoting a predifined set of css styles. css_id – (See `HTMLElement`)

head = None¶: The Head HTMLElement of this page

body = None¶: The Body HTMLElement of this page

TwoColumnPage¶

class reahl.web.ui.TwoColumnPage(view, title='$current_title', style=None, css_id=None)¶

An HTML5Page with a basic layout: It has a header area which displays at top of two columns. A footer area

displays below the two columns. The main column is to the right, and larger. The secondary column is to the left, and smaller.

Styling

Renders as a page structured using Yui 2, with two template preset columns: (main and secondary).

The TwoColumnPage has the following Slots:

main: Used by Views to plug content into the main column.
secondary: Used by Views to plug content into the secondary column.
header: Used by Views to plug content into the header area.
footer: Used by Views to plug content into the footer area.

param view:	(See `reahl.web.fw.Widget`)
param title:	Text for a template to be used as document Title (See also `Title`).
param style:	(See `reahl.web.ui.HTML5Page`)
param css_id:	(See `HTMLElement`)

Deprecated since version 3.1: Please use reahl.web.pure:PageColumnLayout instead.

footer¶: The Panel used as footer area.

header¶: The Panel used as header area.

main¶: The Panel used as main column.

secondary¶: The Panel used as secondary column.

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

Slot¶

class reahl.web.ui.Slot(view, name)¶: A Slot is a placeholder into which Views can plug Widgets on the fly.

RunningOnBadge¶

class reahl.web.ui.RunningOnBadge(view)¶

A visual badge proclaiming that a website is “Running on Reahl”. Using it on your site is a bit of advertising for Reahl!

Styling

Renders as an HTML <a class=”runningon”> containing an <img>

Parameters:	view – (See `reahl.web.fw.Widget`)

Very low-level Widgets that correspond to HTML¶

HTMLElement¶

class reahl.web.ui.HTMLElement(view, tag_name, children_allowed=False, css_id=None, wrapper_widget=None, read_check=None, write_check=None)¶

A Widget that is represented by an HTML element.

Parameters:

view – (See reahl.web.fw.Widget)
tag_name – The element name used to render tags for this HTMLElement
children_allowed – Elements that are not allowed to have children are rendered only with opening tags, others have an opening and closing tag. (See HTML5 void elements.)
css_id – If specified, the HTMLElement will have an id attribute set to this. Mandatory when a Widget has query_fields().
wrapper_widget – Inputs are Widgets that are not HTMLElements. Such an Input acts as “wrapper_widget” for the HTMLElement representing it in HTML. This wrapper_widget (the Input) dictates some of the attributes its HTML representative should have.
read_check – (See reahl.web.fw.Widget)
write_check – (See reahl.web.fw.Widget)

enable_refresh()¶: Sets this HTMLElement up so that it will refresh itself without reloading its page when it senses that one of its query_fields have changed.

add_to_attribute(name, values)¶: Ensures that the value of the attribute name of this HTMLElement includes the words listed in values (a list of strings).

set_attribute(name, value)¶: Sets the value of the attribute name of this HTMLElement to the string value.

get_attribute(name)¶: Answers the value of the attribute named name.

has_attribute(name)¶: Answers whether this HTMLElement has an attribute named name.

attributes¶: Override this method if you want to change the attributes of this HTMLElement on the fly, based on the state of the HTMLElement at the point in time when it is rendered.

contextualise_selector(selector, context)¶: Returns a JQuery selector for finding selector within the elements matched by context (another selector).

jquery_selector¶

Returns a string (including its ” delimeters) which can be used to target this HTMLElement using JQuery. By default this uses the id attribute of the HTMLElement, but this property can be overridden to not be dependent on the id attribute of the HTMLElement.

Raises ProgrammerError:
	Raised when accessing jquery_selector if the css_id of this HTMLElement is not set.

set_title(title)¶: A convenience method to set the “title” attribute of this HTMLElement.

set_id(css_id)¶: A convenience method to set the “id” attribute of this HTMLElement.

append_class(css_class)¶: A convenience method to add the word in css_class to the “class” attribute of thie HTMLElement.

TextNode¶

class reahl.web.ui.Title(view, text, css_id=None)¶

The title of an HTML page (the title of a reahl.web.fw.View is usually shown via a Title).

Styling

Rendered as a <title> element.

Parameters:	view – (See `reahl.web.fw.Widget`) text – A string for use in a PEP-292 <http://www.python.org/dev/peps/pep-0292/> template. The final value after substituting this string Template will be used as the value of this Title. The template string may use one placeholder: $current_title which contains the title of the current View. css_id – (See `HTMLElement`)

Title¶

class reahl.web.ui.Title(view, text, css_id=None)

The title of an HTML page (the title of a reahl.web.fw.View is usually shown via a Title).

Styling

Rendered as a <title> element.

Parameters:	view – (See `reahl.web.fw.Widget`) text – A string for use in a PEP-292 <http://www.python.org/dev/peps/pep-0292/> template. The final value after substituting this string Template will be used as the value of this Title. The template string may use one placeholder: $current_title which contains the title of the current View. css_id – (See `HTMLElement`)

Link¶

class reahl.web.ui.Link(view, rel, href, _type, css_id=None)¶

A link to an external resource.

Styling

Renders as an HTML <link> element.

Parameters:	view – (See `reahl.web.fw.Widget`) rel – The value of the “rel” attribute of this HTMLElement. href – The value of the “href” attribute of this HTMLElement. _type – The value of the “type” attribute of this HTMLElement. css_id – (See `HTMLElement`)

Head¶

class reahl.web.ui.Head(view, title, css_id=None)¶

A container for metadata of a View.

Styling

Renders as an HTML <head> element.

Parameters:	view – (See `reahl.web.fw.Widget`) title – Text for a template to be used as document Title (See also `Title`). css_id – (See `HTMLElement`)

Body¶

class reahl.web.ui.Body(view, css_id=None)¶

The content of an HTML document.

Styling

Renders as an HTML <body> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Span¶

class reahl.web.ui.Span(view, text=None, css_id=None)¶

A logical grouping of other HTMLElements which fits in with text flow.

Styling

Renders as an HTML <span> element.

Parameters:	view – (See `reahl.web.fw.Widget`) text – Will be added as text content of the Span if given. css_id – (See `HTMLElement`)

More commonly used Widgets that correspond to HTML¶

A¶

class reahl.web.ui.A(view, href, description=None, ajax=False, read_check=None, write_check=None, css_id=None)¶

A hyper link.

Styling

Renders as an HTML <a> element.

Parameters:	view – (See `reahl.web.fw.Widget`) href – The URL (or URL fragment) to which the hyperlink leads. description – The textual description to be shown on the hyperlink. ajax – (Not for general use) read_check – (See `reahl.web.fw.Widget`) write_check – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

classmethod from_bookmark(view, bookmark)¶: Creates an A for the given bookmark on view.

classmethod factory_from_bookmark(bookmark)¶: Creates a reahl.web.fw.WidgetFactory for creating an A for the given bookmark.

set_active(active)¶

Explicitly sets whether this hyperlink is “active” or not. An active hyperlink cannot be clicked on, because conceptually, the user is already at its target.

Parameters:	active – A boolean – send True if active, else False.

H¶

class reahl.web.ui.H(view, priority, text=None, css_id=None)¶

The heading for a section.

Styling

Renders as an HTML <h1>, <h2> ... , <h6> element, depending on priority.

Parameters:	view – (See `reahl.web.fw.Widget`) priority – The heading level (a value from 1 to 6) text – The text value displayed in the heading (if given) css_id – (See `HTMLElement`)

P¶

class reahl.web.ui.P(view, text=None, css_id=None, html_escape=True)¶

A paragraph of text.

Styling

Renders as an HTML <p> element.

Parameters:	view – (See `reahl.web.fw.Widget`) text – The text value displayed in the paragraph (if given) css_id – (See `HTMLElement`) html_escape – If text is given, by default such text is HTML-escaped. Pass False in here to prevent this from happening.

format(*args, **kwargs)¶

A complicated paragraph may consist of many TextNodes interspersed with other Widgets. Creating such a paragraph programmatically can be cumbersome. Instead, the text of a P can be a template resembling a PEP-292 <http://www.python.org/dev/peps/pep-0292/> template. This format method works analogously to string.format(), except that Widgets can be passed in to be substituted into the original P.

Parameters:	args – Positional arguments for substituting into the “template P” kwargs – Named arguments for substituting into the “template P”

Div¶

class reahl.web.ui.Div(view, css_id=None)¶

A logical grouping of other HTMLElements.

Styling

Renders as an HTML <div> element

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Nav¶

class reahl.web.ui.Nav(view, css_id=None)¶

A grouping of HTMLElements that refer to or link to other pages or parts within the current page.

Styling

Renders as an HTML <nav> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Article¶

class reahl.web.ui.Article(view, css_id=None)¶

An independent section of informational content.

Styling

Renders as an HTML <article> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Header¶

class reahl.web.ui.Header(view, css_id=None)¶

A grouping of elements representing metadata pertaining to a section, such as an Article.

Styling

Rendered as an HTML <article> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Footer¶

class reahl.web.ui.Footer(view, css_id=None)¶

The footer of a section (such as an Article).

Styling

Renders as an HTML <footer> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Li¶

class reahl.web.ui.Li(view, css_id=None)¶

A list item.

Styling

Renders as an HTML <li> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Ul¶

class reahl.web.ui.Ul(view, css_id=None)¶

An unordered list.

Styling

Renders as an HTML <ul> element.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Img¶

class reahl.web.ui.Img(view, src, alt=None, css_id=None)¶

An embedded image.

Styling

Renders as an HTML <img> element.

Parameters:	view – (See `reahl.web.fw.Widget`) src – The URL from where the embedded image file should be fetched. alt – Alternative text describing the image. css_id – (See `HTMLElement`)

Widgets for Input¶

Form¶

class reahl.web.ui.Form(view, unique_name, rendered_form=None)¶

All Inputs have to belong to a Form. When a user clicks on a Button associated with a Form, the Event to which the Button is linked occurs at the server. All the values of the Inputs that are associated with the Form are sent with the Event to the server.

Styling

Renders as an HTML <form class=”reahl-form”> element.

Parameters:	view – (See `reahl.web.fw.Widget`) unique_name – A name for this form, unique in the UserInterface where it is used.

exception¶: The reahl.component.exceptions.DomainException which occurred, if any.

NestedForm¶

class reahl.web.ui.NestedForm(view, unique_name, css_id=None)¶

Forms may not be children of other Forms. A NestedForm may be the child of another Form, which means that visually, it will be rendered inside the other Form.

Styling

Rendered as an HTML <div class=”reahl-nested-form”> element.

Parameters:	view – (See `reahl.web.fw.Widget`) unique_name – (See `Form`) css_id – (See `HTMLElement`)

InputGroup¶

class reahl.web.ui.InputGroup(view, label_text=None, css_id=None)¶

A visual grouping of HTMLElements inside a Form.

Styling

Rendered as an HTML <fieldset> element.

Parameters:	view – (See `reahl.web.fw.Widget`) label_text – If given, the FieldSet will have a label containing this text. css_id – (See `HTMLElement`)

FieldSet¶

class reahl.web.ui.FieldSet(view, label_text=None, css_id=None)¶

Input¶

class reahl.web.ui.Input(form, bound_field)¶

A Widget that proxies data between a user and the web application.

Parameters:	form – The `Form` with which this Input is associated. bound_field – The `reahl.component.modelinterface.Field` which validates and marshalls user input given via this Input.

append_class(css_class)¶: Adds the word css_class to the “class” attribute of the HTMLElement which represents this Input in HTML to the user.

set_id(value)¶: Set the “id” attribute of the HTMLElement which represents this Input in HTML to the user.

set_title(value)¶: Set the the “title” attribute of the HTMLElement which represents this Input in HTML to the user.

add_to_attribute(name, values)¶: Ensures that the value of the attribute name of the HTMLElement which represents this Input in HTML to the user includes the words listed in values (a list of strings).

set_attribute(name, value)¶: Sets the value of the attribute name of the HTMLElement which represents this Input in HTML to the user to the string value.

create_html_input()¶: Override this in subclasses to create the HTMLElement that represents this Input in HTML to the user.

get_wrapped_html_attributes(attributes)¶: Sets the HTML attributes which should be present on the HTMLElement that represents this Input in HTML to the user.

get_value_from_input(input_values)¶: Obtains the value received for this Input from the browser, given a cgi.FieldStorage containing name, value pairs of user input as sent by the browser. Override this method if your Input needs special handling to obtain its value.

TextArea¶

class reahl.web.ui.TextArea(form, bound_field, rows=None, columns=None)¶

A muli-line Input for plain text.

Styling

Represented in HTML as a <textarea> element.

Parameters:	form – (See `Input`) bound_field – (See `Input`) rows – The number of rows that this Input should have. columns – The number of columns that this Input should have.

SelectInput¶

class reahl.web.ui.SelectInput(form, bound_field)¶

An Input that lets the user select an reahl.component.modelinterface.Choice from a dropdown list of valid ones.

Styling

Represented in HTML as a <select> element which can contain <option> and <optgroup> children.

Parameters:	form – (See `Input`) bound_field – (See `Input`)

RadioButtonInput¶

class reahl.web.ui.RadioButtonInput(form, bound_field)¶

An Input that lets the user select an reahl.component.modelinterface.Choice from a list of valid ones shown as radio buttons.

Styling

Represented in HTML as a <div class=”reahl-radio-button-input”> element which contains an <input type=”radio”>, wrapped in a <span class=”reahl-radio-button”> for each valid reahl.component.modelinterface.Choice.

Parameters:	form – (See `Input`) bound_field – (See `Input`)

TextInput¶

class reahl.web.ui.TextInput(form, bound_field, fuzzy=False)¶

A single line Input for typing plain text.

Styling

Represented in HTML by an <input type=”text” class=”reahl-textinput”> element.

Parameters:

form – (See Input)
bound_field – (See Input)
fuzzy – If True, the typed input will be dealt with as “fuzzy input”. Fuzzy input is when a user is allowed to type almost free-form input for structured types of input, such as a date. The assumption is that the bound_field used should be able to parse such “fuzzy input”. If fuzzy=True, the typed value will be changed on the fly to the system’s interpretation of what the user originally typed as soon as the TextInput looses focus.

PasswordInput¶

class reahl.web.ui.PasswordInput(form, bound_field)¶

A PasswordInput is a single line text input, but it does not show what the user is typing.

Styling

Represented in HTML by a <input type=”password”> element.

Parameters:	form – (See `Input`) bound_field – (See `Input`)

CheckboxInput¶

class reahl.web.ui.CheckboxInput(form, bound_field)¶

A checkbox.

Styling

Represented in HTML by an <input type=”checkbox”> element.

Parameters:	form – (See `Input`) bound_field – (See `Input`)

Button¶

class reahl.web.ui.Button(form, event, css_id=None)¶

A button.

Styling

Represented in HTML by an <input type=”submit”> element, wrapped in a <span class=”reahl-button”>.

Parameters:	form – (See `Input`) event – The `reahl.web.fw.Event` that will fire when the user clicks on this ButtonInput. css_id – (See `HTMLElement`)

Label¶

class reahl.web.ui.Label(view, text=None, for_input=None, css_id=None)¶

A label for an Input.

If for_input is given, the Label will only be visible if for_input is visible.

Styling

Rendered as an HTML <label> element.

Parameters:	view – (See `reahl.web.fw.Widget`) text – If given, used as the text for the label. for_input – If given, the `Input` to which this Label applies (its .label is also used as text). css_id – (See `HTMLElement`)

InputLabel¶

class reahl.web.ui.InputLabel(html_input, text=None, css_id=None)¶

A label for the Input given in html_input.

Styling

Rendered as an HTML <label> element.

Parameters:	html_input – The `Input` labelled by this Label. text – If given, used as the text for the label rather than the default value (html_input.label). css_id – (See `HTMLElement`)

ErrorLabel¶

class reahl.web.ui.ErrorLabel(html_input, text=None, css_id=None)¶

Widgets to help with layout of Inputs¶

HorizontalLayout¶

class reahl.web.ui.HorizontalLayout¶

A Layout that causes Widgets to be displayed horizontally.

Styling

Adds class reahl-horizontal to its Widget.

(Only works for Menu and subclasses.)

VerticalLayout¶

class reahl.web.ui.VerticalLayout¶

A Layout that causes Widgets to be displayed vertically.

Styling

Adds class reahl-vertical to its Widget.

(Only works for Menu and subclasses.)

LabelledInlineInput¶

class reahl.web.ui.LabelledInlineInput(html_input, css_id=None)¶

A Widget that wraps around a given Input, adding a Label to the Input. Adheres to text flow.

Styling

Rendered as a <span class=”reahl-labelledinput”> containing the <label> followed by another <span> which contains the html_input. If the current input is not valid, it will also have class reahl-state-error.

Parameters:	html_input – (See `InputLabel`) css_id – (See `HTMLElement`)

LabelledBlockInput¶

class reahl.web.ui.LabelledBlockInput(html_input, css_id=None)¶

A Widget that wraps around a given Input, adding a Label to the Input. Labels and their corresponding Inputs are arranged in columns. Successive LabelledBlockInputs are positioned underneath one another. This has the effect that the Labels and Inputs of successive LabelledBlockInputs line up.

Styling

Rendered as a <div class=”reahl-labelledinput”> containing two <div> elements: one with the Label in it, and the other with html_input itself. If the current input is not valid, it will also have class reahl-state-error.

Parameters:	html_input – (See `InputLabel`) css_id – (See `HTMLElement`)

CueInput¶

class reahl.web.ui.CueInput(html_input, cue_widget, css_id=None)¶

A Widget that wraps around a given Input, adding a Label to the Input and a “cue” - a hint that appears only when the Input has focus. The intention of the cue is to give the user a hint as to what to input into the Input.

Successive CueInputs are arranged underneath each other, with their labels, Inputs and Cue’s lined up.

Styling

Rendered as a <div class=”reahl-cueinput reahl-labelledinput”> containing two <div> elements: one with the Label in it, and the other with two more <div> elements. The first of these contains the html_input itself. The last contains the cue_widget. If the current input is not valid, it will also have class reahl-state-error.

Parameters:	html_input – (See `InputLabel`) css_id – (See `HTMLElement`)

LabelOverInput¶

class reahl.web.ui.LabelOverInput(html_input, css_id=None)¶

A LabelledInlineWidget that shows the Label superimposed over the Input itself. The label is only visible while the Input is empty.

Styling

Rendered like a LabelledInlineWidget with reahl-labeloverinput appended to the class of the containing <div> element.

Parameters:	html_input – (See `InputLabel`) css_id – (See `HTMLElement`)

Menus¶

MenuItem¶

class reahl.web.ui.MenuItem(view, a, active_regex=None, exact_match=False, css_id=None)¶

One item in a Menu.

Styling

Rendered as a <li> element. When active, includes class=”active”.

Normally, a programmer would not instantiate this class directly, rather use MenuItem.from_bookmark().

Parameters:	view – (See `reahl.web.fw.Widget`) a – The `A` to use as link. active_regex – If the href of a matches this regex, the MenuItem is deemed active. exact_match – (See `reahl.web.fw.Url.is_currently_active()`) css_id – (See `HTMLElement`)

classmethod from_bookmark(view, bookmark, active_regex=None)¶

Creates a MenuItem from a given Bookmark.

Parameters:	view – (See `reahl.web.fw.Widget`) bookmark – The `reahl.web.fw.Bookmark` for which to create the MenuItem. active_regex – (See `MenuItem`)

Menu¶

class reahl.web.ui.Menu(view, a_list, css_id=None)¶

A visual menu that lists a number of Views to which the user can choose to go to.

Styling

Rendered as a <ul class=”reahl-menu”> element that contains a <li> for each MenuItem.

Parameters:	view – (See `reahl.web.fw.Widget`) a_list – A list of `A` instances to which each `MenuItem` will lead. css_id – (See `HTMLElement`)

classmethod from_languages(view)¶

Constructs a Menu which contains a MenuItem for each locale supported by all the components in this application.

Parameters:	view – (See `reahl.web.fw.Widget`)

classmethod from_bookmarks(view, bookmark_list)¶: Creates a Menu with a MenuItem for each Bookmark given in bookmark_list.

add_item(item)¶: Adds MenuItem item to this Menu.

SubMenu¶

class reahl.web.ui.SubMenu(view, title, menu, css_id=None)¶

A MenuItem that can contain another complete Menu itself.

Styling

Rendered as a <li> element that contains a Menu (see the latter for how it is rendered).

Parameters:	view – (See `reahl.web.fw.Widget`) title – Text to use as a title for this SubMenu. menu – The `Menu` contained inside this SubMenu. css_id – (See `HTMLElement`)

HMenu¶

class reahl.web.ui.HMenu(view, a_list, css_id=None)¶

A Menu, with items displayed next to each other.

Styling

Rendered as a <ul class=”reahl-menu reahl-horizontal”>

param view: (See reahl.web.fw.Widget)

param a_list: (See Menu)

keyword css_id: (See HTMLElement)

Deprecated since version 3.1: Please use Menu().with_layout(HorizontalLayout()) instead.

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

from_bookmarks(view, bookmark_list)¶: Creates a Menu with a MenuItem for each Bookmark given in bookmark_list.

from_languages(view)¶

Constructs a Menu which contains a MenuItem for each locale supported by all the components in this application.

Parameters:	view – (See `reahl.web.fw.Widget`)

VMenu¶

class reahl.web.ui.VMenu(view, a_list, css_id=None)¶

A Menu, with items displayed underneath each other.

Styling

Rendered as a <ul class=”reahl-menu reahl-vertical”>

param view: (See reahl.web.fw.Widget)

param a_list: (See Menu)

keyword css_id: (See HTMLElement)

Deprecated since version 3.1: Please use Menu().with_layout(VerticalLayout()) instead.

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

from_bookmarks(view, bookmark_list)¶: Creates a Menu with a MenuItem for each Bookmark given in bookmark_list.

from_languages(view)¶

Constructs a Menu which contains a MenuItem for each locale supported by all the components in this application.

Parameters:	view – (See `reahl.web.fw.Widget`)

Tables¶

Table¶

class reahl.web.ui.Table(view, caption_text=None, summary=None, css_id=None)¶

An HTML table element: data displayed on columns and rows.

Parameters:	view – (See `reahl.web.fw.Widget`) caption_text – If text is given here, a caption will be added to the table containing the caption text. summary – A textual summary of the contents of the table which is not displayed visually, but may be used by a user agent for accessibility purposes. css_id – (See `HTMLElement`)

classmethod from_columns(view, columns, items, caption_text=None, summary=None, css_id=None)¶

Creates a table populated with rows, columns, header and footer, with one row per provided item. The table is defined by the list of DynamicColumn or StaticColumn instances passed in.

Parameters:

view – (See reahl.web.fw.Widget)
columns – The reahl.web.ui.DynamicColumn instances that define the contents of the table.
items – A list containing objects represented in each row of the table.
caption_text – If given, a reahl.web.ui.Caption is added with this text.
summary – If given, a summary attribute is added to the table containing this text.
css_id – (See HTMLElement)

DynamicColumn¶

class reahl.web.ui.DynamicColumn(make_heading_or_string, make_widget, sort_key=None)¶

DynamicColumn defines a logical column of a table, specifying how its heading will be rendered, and how the cell in this column will be displayed for each data item in the table.

Parameters:

make_heading_or_string – A string to be used as heading for this column, or a single-argument callable that will be called (passing the current view) in order to compute a Widget to be displayed as heading of the column.
make_widget – A callable that takes two arguments: the current view, and an item of data of the current table row. It will be called to compute a Widget to be displayed in the current column for the given data item.
sort_key – If specified, this value will be passed to sort() for sortable tables.

StaticColumn¶

class reahl.web.ui.StaticColumn(field, attribute_name, sort_key=None)¶

StaticColumn defines a column whose heading and contents are derived from the given field.

Parameters:	field – The `Field` that defines the heading for this column, and which will also be used to get the data to be displayed for each row in this column. attribute_name – The name of the attribute to which field should be bound to on each data item when rendering this column. sort_key – If specified, this value will be passed to sort() for sortable tables.

DataTable¶

class reahl.web.table.DataTable(view, columns, items, items_per_page=10, caption_text=None, summary=None, css_id=None)¶

A table containing a potentially large set of data items. DataTable does not display all its items on the current page. It renders as a table spread over different pages between which a user can navigate, thus preventing a large data set sent back to a single page.

If a DynamicColumn is used to define the table also specifies a sort_key, the table is rendered with controls on that column heading that allows it to be sorted on that column. The sort operation applies to the entire dataset even though the user stays on the current page and only sees a subset of that data.

Parameters:

view – (See reahl.web.fw.Widget)
columns – The reahl.web.ui.DynamicColumn instances that define the contents of the table.
items – A list containing objects represented in each row of the table.
items_per_page – The maximum number of rows allowed per page.
caption_text – If given, a reahl.web.ui.Caption is added with this text.
summary – If given, a reahl.web.ui.Summary is added with this text.
css_id – (See HTMLElement)

Caption¶

class reahl.web.ui.Caption(view, text=None, css_id=None)¶

An HTML caption element.

Styling

Renders as an HTML <caption> element.

Parameters:	view – (See `reahl.web.fw.Widget`) text – Text to be displayed inside the caption element. css_id – (See `HTMLElement`)

Thead¶

class reahl.web.ui.Thead(view, css_id=None)¶

An HTML thead element. Contains the header of the table columns.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Tfoot¶

class reahl.web.ui.Tfoot(view, css_id=None)¶

An HTML tfoot element. Contains the footer of the table columns.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Tbody¶

class reahl.web.ui.Tbody(view, css_id=None)¶

An HTML tbody element. Contains the rows with data in the table.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Tr¶

class reahl.web.ui.Tr(view, css_id=None)¶

An HTML tr element represents one row of data in a table.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

Td¶

class reahl.web.ui.Td(view, rowspan=None, colspan=None, css_id=None)¶

An HTML td element - a single cell of data inside a row of a table.

Parameters:	view – (See `reahl.web.fw.Widget`) rowspan – The number of rows this table cell should span. colspan – The number of columns this table cell should span. css_id – (See `HTMLElement`)

Th¶

class reahl.web.ui.Th(view, rowspan=None, colspan=None, css_id=None)¶

An HTML th element - a single cell heading for a column of a table.

Parameters:	view – (See `reahl.web.fw.Widget`) rowspan – The number of rows this table cell should span. colspan – The number of columns this table cell should span. css_id – (See `HTMLElement`)

Tabbed or sliding panels¶

Tab¶

class reahl.web.ui.Tab(view, title, tab_key, contents_factory, css_id=None)¶

One Tab in a TabbedPanel.

Styling

Rendered like a MenuItem, with the <a> containing title.

Parameters:	view – (See `reahl.web.fw.Widget`) title – Text that is displayed inside the Tab itself. tab_key – A name for this tag identifying it uniquely amongst other Tabs in the same `TabbedPanel`. contents_factory – A `WidgetFactory` specifying how to create the contents of this Tab, once selected. css_id – (See `HTMLElement`)

MultiTab¶

class reahl.web.ui.MultiTab(view, title, tab_key, contents_factory, css_id=None)¶

A composite tab. Instead of a single choice for the user, clicking on a MultiTab results in a dropdown menu with more choices for the user.

Styling

Rendered like a Tab, but with more contents. The usual <a> containing the title is followed by an   and an <a class=”dropdown-handle”>. This is followed by a normal VMenu.

Parameters:	view – (See `reahl.web.fw.Widget`) title – (See `Tab`) tab_key – (See `Tab`) contents_factory – (See `Tab`) css_id – (See `HTMLElement`)

TabbedPanel¶

class reahl.web.ui.TabbedPanel(view, css_id)¶

A Panel sporting different Tabs which the user can select to change what is displayed. The contents of a TabbedPanel are changed when the user clicks on a different Tab without refreshing the entire page, provided that JavaScript is available on the user agent.

Styling

Rendered as a <div class=”reahl-tabbedpanel”> which contains two children: an HMenu containing instances of Tab for MenuItems, followed by a <div> that will be populated by the current contents of the TabbedPanel.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`)

add_tab(tab)¶: Adds the Tab tab to this TabbedPanel.

SlidingPanel¶

class reahl.web.ui.SlidingPanel(view, css_id=None, next='>', prev='<')¶

A Panel which contains a number of other Panels, only one of which is displayed at a time. It sports controls that can be clicked by a user to advance the displayed content to the next or previous Panel. Advancing is done by visually sliding in the direction indicated by the user if JavaScript is available. The panels advance once every 10 seconds if no user action is detected.

Styling

Rendered as a <div class=”reahl-slidingpanel”> which contains three children: a <div class=”viewport”> flanked on either side by an <a> (the controls for forcing it to transition left or right). The labels passed as next and prev are embedded in <span> tags inside the <a> tags. The Panel instances added to the SlidingPanel are marked with a class="contained".

For a SlidingPanel to function property, you need to specify a height and width to div.reahl-slidingpanel div.viewport.

Parameters:	view – (See `reahl.web.fw.Widget`) css_id – (See `HTMLElement`) next – Text to put in the link clicked to slide to the next panel. prev – Text to put in the link clicked to slide to the previous panel.

add_panel(panel)¶: Adds panel to the list of Panel instances that share the same visual space.

Uploading of files¶

SimpleFileInput¶

class reahl.web.ui.SimpleFileInput(form, bound_field)¶

An Input for selecting a single file which will be uploaded once the user clicks on any Button associated with the same Form as this Input.

Styling

Represented in HTML by an <input type=”file”> element. Can have attribute multiple set, if allowed by the bound_field.

Parameters:	form – (See `Input`) bound_field – (See `Input`, must be of type `reahl.component.modelinterface.FileField`

FileUploadInput¶

class reahl.web.ui.FileUploadInput(form, bound_field)¶

An Input which allows a user to choose several files for uploding to a server. As each file is chosen, the file is uploaded to the server in the background (if JavaScript is enabled on the user agent). A file being uploaded can be cancelled and uploaded files can be removed from the list.

Styling

Represented in HTML by a <div class=”reahl-file-upload-panel”> with three children:

a NestedForm,
an <ul> which contains a <li class=”reahl-file-upload-li”> for each file that was uploaded (or is still being uploaded), and
a <div> which contains a SimpleFileInput and a Button.

While a file is being uploaded, its <li class=”reahl-file-upload-li”> contains a cancel button of type Button, and a <span> containing the name of the file. These elements are followed by a <progress> element.

Once a file has been uploaded, its <li class=”reahl-file-upload-li”> is changed. The <progress> element is removed, and cancel button is replaced with a Remove button.

Should an error occur while uploading the file, the <progress> element is replaced with a <label class=”error> containing an error message.

Parameters:	form – (See `Input`) bound_field – (See `Input`, must be of type `reahl.component.modelinterface.FileField`

Support for Yui 2 CSS Grids¶

Deprecated since version 3.1: Please use the new layout concepts based on Pure instead.

YuiDoc¶

class reahl.web.ui.YuiDoc(view, doc_id, doc_class, css_id=None)¶

A Yui 2 #doc div: the container of the #hd, #bd and #ft ( see http://developer.yahoo.com/yui/grids/#start ) .. deprecated:: 3.1

Please use reahl.web.pure:PageColumnLayout instead.

hd = None¶

bd = None¶

secondary_block = None¶: the secondary div (see Yui 2 template presents)

main_block = None¶: the #yui-main div (see Yui 2 template presents)

ft = None¶

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

YuiUnit¶

class reahl.web.ui.YuiUnit(view, first=False)¶

A Yui 2 unit: see http://developer.yahoo.com/yui/grids/#start

param view: (See reahl.web.fw.Widget)

param first: Pass True for the first YuiUnit in a YuiGrid

Deprecated since version 3.1: Please use reahl.web.pure:ColumnLayout instead.

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

YuiGrid¶

class reahl.web.ui.YuiGrid(view, css_id=None)¶

A Yui 2 grid: see http://developer.yahoo.com/yui/grids/#start .. deprecated:: 3.1

Please use reahl.web.pure:ColumnLayout instead.

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

YuiBlock¶

class reahl.web.ui.YuiBlock(view, css_id=None)¶

A Yui 2 block: see http://developer.yahoo.com/yui/grids/#start .. deprecated:: 3.1

Please use reahl.web.pure:ColumnLayout instead.

factory(*widget_args, **widget_kwargs)¶: Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.

Misc¶

Panel¶

class reahl.web.ui.Panel(view, css_id=None)¶: A logical container for other Widgets.

Styling

Renders as an HTML <div> element.

LiteralHTML¶

class reahl.web.ui.LiteralHTML(view, contents, transform=<function LiteralHTML.<lambda>>)¶: The LiteralHTML Widget renders a chunk of HTML as given in contents. If a single-argument callable is given as transform, contents will first be passed to that callable to possibly change the HTML on-the-fly before rendering (the callable should return the changed HTML to be rendered).

PriorityGroup¶

class reahl.web.ui.PriorityGroup¶

A PriorityGroup ensures that only one of the Widgets added to it has primary priority, the others in the group can have secondary priority, or no priority specified. This is used for styling Widgets based on their priority in the PriorityGroup.

add(widget)¶: Adds widget, with no priority set.

add_secondary(widget)¶: Adds widget, with secondary priority.

add_primary(widget)¶: Adds widget, with primary priority.

ErrorFeedbackMessage¶

class reahl.web.ui.ErrorFeedbackMessage(view, text=None, css_id=None, html_escape=True)¶: A user message indicating some error condition, such as a form validation which failed.

Styling

Renders as an HTML <p class=”error feedback”> element.

Module reahl.web.ui
- Widgets for constructing a page
- Very low-level Widgets that correspond to HTML
  - HTMLElement
  - TextNode
  - Title
  - Link
  - Head
  - Body
  - Span
- More commonly used Widgets that correspond to HTML
  - A
  - H
  - P
  - Div
  - Nav
  - Article
  - Header
  - Footer
  - Li
  - Ul
  - Img
- Widgets for Input
  - Form
  - NestedForm
  - InputGroup
  - FieldSet
  - Input
  - TextArea
  - SelectInput
  - RadioButtonInput
  - TextInput
  - PasswordInput
  - CheckboxInput
  - Button
  - Label
  - InputLabel
  - ErrorLabel
- Widgets to help with layout of Inputs
- Menus
  - MenuItem
  - Menu
  - SubMenu
  - HMenu
  - VMenu
- Tables
  - Table
  - DynamicColumn
  - StaticColumn
  - DataTable
  - Caption
  - Thead
  - Tfoot
  - Tbody
  - Tr
  - Td
  - Th
- Tabbed or sliding panels
  - Tab
  - MultiTab
  - TabbedPanel
  - SlidingPanel
- Uploading of files
  - SimpleFileInput
  - FileUploadInput
- Support for Yui 2 CSS Grids
  - YuiDoc
  - YuiUnit
  - YuiGrid
  - YuiBlock
- Misc

Previous topic

Module reahl.web.fw

Next topic

Module reahl.web.pure

param view:	(See `reahl.web.fw.Widget`)
param a_list:	(See `Menu`)
keyword css_id:	(See `HTMLElement`)

param view:	(See `reahl.web.fw.Widget`)
param first:	Pass True for the first YuiUnit in a YuiGrid

Navigation

Module reahl.web.ui¶

Widgets for constructing a page¶

HTML5Page¶

TwoColumnPage¶

Slot¶

RunningOnBadge¶

Very low-level Widgets that correspond to HTML¶

HTMLElement¶

TextNode¶

Title¶

Link¶

Head¶

Body¶

Span¶

More commonly used Widgets that correspond to HTML¶

A¶

H¶

P¶

Div¶

Nav¶

Article¶

Header¶

Footer¶

Li¶

Ul¶

Img¶

Widgets for Input¶

Form¶

NestedForm¶

InputGroup¶

FieldSet¶

Input¶

TextArea¶

SelectInput¶

RadioButtonInput¶

TextInput¶

PasswordInput¶

CheckboxInput¶

Button¶

Label¶

InputLabel¶

ErrorLabel¶

Widgets to help with layout of Inputs¶

HorizontalLayout¶

VerticalLayout¶

LabelledInlineInput¶

LabelledBlockInput¶

CueInput¶

LabelOverInput¶

Menus¶

MenuItem¶

Menu¶

SubMenu¶

HMenu¶

VMenu¶

Tables¶

Table¶

DynamicColumn¶

StaticColumn¶

DataTable¶

Caption¶

Thead¶

Tfoot¶

Tbody¶

Tr¶

Td¶

Th¶

Tabbed or sliding panels¶

Tab¶

MultiTab¶

TabbedPanel¶

SlidingPanel¶

Uploading of files¶

SimpleFileInput¶

FileUploadInput¶

Support for Yui 2 CSS Grids¶

YuiDoc¶

YuiUnit¶

YuiGrid¶