Basic Widgets and related user interface elements.
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: |
|
|---|
head = None¶The Head HTMLElement of this page
body = None¶The Body HTMLElement of this page
reahl.web.ui.TwoColumnPage(view, title='$current_title', style=None, css_id=None)¶displays below the two columns. The main column is to the right, and larger. The secondary column is to the left, and smaller.
Styling
The TwoColumnPage has the following Slots:
| 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 reahl.web.ui.HTMLElement) |
Deprecated since version 3.1: Please use reahl.web.layout:PageLayout instead.
The Div used as footer area.
header¶The Div used as header area.
main¶The Div used as main column.
secondary¶The Div 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.
reahl.web.ui.Slot(view, name)¶A Slot is a placeholder area on a page into which different Views can plug different Widgets on the fly.
Using Slots, one can create a single HTML5page which can be re-used by different Views instead of having to create similar-looking HTML5Pages for each View in an application.
A Slot is added to an HTML5Page to represent an area that will be populated later by a View. When a View is served up the framework can then populate this empty area with Widgets specific to the current View.
| Parameters: |
|
|---|
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) |
|---|
reahl.web.ui.HTMLElement(view, tag_name, children_allowed=False, css_id=None, read_check=None, write_check=None)¶A Widget that is represented by an HTML element.
| Parameters: |
|
|---|
enable_refresh(*for_fields)¶Sets this HTMLElement up so that it will refresh itself without reloading its page when it senses that one of the given query_fields have changed. If no Fields are specified here, the HTMLElement is refreshed when any of its query_fields change.
| Parameters: | for_fields – A selection of the .query_fields defined on this HTMLElement. |
|---|
Changed in version 3.2: The for_fields arguments were added to allow control over which of an HTMLElement’s query_fields trigger a refresh.
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.
reahl.web.ui.TextNode(view, value_or_getter, html_escape=True)¶An HTML TextNode. You can, for example, use a TextNode to add a snippet of text as a child of a P inbetween its other children (which will all be HTMLElements, like Span).
| Parameters: |
|
|---|
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: |
|
|---|
reahl.web.ui.Link(view, rel, href, _type=None, css_id=None)¶A link to an external resource.
Styling
Renders as an HTML <link> element.
| Parameters: |
|
|---|
Changed in version 3.2: Changed _type to be an optional, keyword argument instead of a positional argument.
reahl.web.ui.Head(view, title, css_id=None)¶A container for metadata of a View.
Styling
Renders as an HTML <head> element.
| Parameters: |
|
|---|
reahl.web.ui.Body(view, css_id=None)¶The content of an HTML document.
Styling
Renders as an HTML <body> element.
| Parameters: |
|
|---|
reahl.web.ui.Span(view, text=None, html_escape=True, css_id=None)¶A logical grouping of other HTMLElements which fits in with text flow.
Styling
Renders as an HTML <span> element.
| Parameters: |
|
|---|
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: |
|
|---|
from_bookmark(view, bookmark)¶Creates an A for the given bookmark on view.
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. |
|---|
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: |
|
|---|
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: |
|
|---|
format(*args, **kwargs)¶A complicated paragraph may consist of many TextNodes interspersed with other Widgets. Creating such a
paragraph programmatically is cumbersome. Instead, the text of a P can be a template resembling
a PEP-292 template. This format method works analogously to
string.format(), except that Widgets can be passed in to be substituted into the original P.
| Parameters: |
|
|---|
reahl.web.ui.Div(view, css_id=None)¶A logical grouping of other HTMLElements.
Styling
Renders as an HTML <div> element
| Parameters: |
|
|---|
reahl.web.ui.Article(view, css_id=None)¶An independent section of informational content.
Styling
Renders as an HTML <article> element.
| Parameters: |
|
|---|
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: |
|
|---|
reahl.web.ui.Li(view, css_id=None)¶A list item.
Styling
Renders as an HTML <li> element.
| Parameters: |
|
|---|
reahl.web.ui.Ul(view, css_id=None)¶An unordered list.
Styling
Renders as an HTML <ul> element.
| Parameters: |
|
|---|
reahl.web.ui.Ol(view, css_id=None)¶An ordered list.
Styling
Renders as an HTML <ol> element.
| Parameters: |
|
|---|
reahl.web.ui.Img(view, src=None, alt=None, css_id=None)¶An embedded image.
Styling
Renders as an HTML <img> element.
| Parameters: |
|
|---|
reahl.web.ui.Form(view, unique_name, rendered_form=None)¶A Form is a container for Inputs. Any Input has 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. The value of every Input that is associated with the Form is sent along with the Event to the server.
Styling
Renders as an HTML <form class=”reahl-form”> element.
| Parameters: |
|
|---|
exception¶The reahl.component.exceptions.DomainException which occurred, if any.
reahl.web.ui.NestedForm(view, unique_name, css_id=None)¶A NestedForm can create the appearance of one Form being visually contained in another. Forms are not allowed to be children of other Forms but this restriction does not apply to NestedForms.
Styling
Rendered as an HTML <div class=”reahl-nested-form”> element.
| Parameters: |
|
|---|
reahl.web.ui.InputGroup(view, legend_text=None, label_text=None, css_id=None)¶A visual grouping of HTMLElements inside a Form.
Styling
Rendered as an HTML <fieldset> element.
| Parameters: |
|
|---|
reahl.web.ui.FieldSet(view, legend_text=None, label_text=None, css_id=None)¶A visual grouping of HTMLElements inside a Form.
Styling
Rendered as an HTML <fieldset> element.
| Parameters: |
|
|---|
reahl.web.ui.Legend(view, text=None, css_id=None)¶A caption for an reahl.web.ui.HTMLElement.
Styling
Rendered as an HTML <legend> element.
| Parameters: |
|
|---|
reahl.web.ui.Input(form, bound_field)¶A Widget that proxies data between a user and the web application.
| Parameters: |
|
|---|
includes_label¶If True, the Label of this Input forms part of the input itself.
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: |
|---|
reahl.web.ui.SelectInput(form, bound_field, name=None)¶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: |
|---|
reahl.web.ui.RadioButtonInput(form, bound_field, name=None)¶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: |
|---|
reahl.web.ui.TextInput(form, bound_field, fuzzy=False, placeholder=False)¶A single line Input for typing plain text.
Styling
Represented in HTML by an <input type=”text” class=”reahl-textinput”> element.
| Parameters: |
|
|---|
Changed in version 3.2: Added placeholder.
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: |
|
|---|
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: |
|
|---|
Changed in version 3.2: Added the for_input keyword argument.
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.
param html_input: The Inputlabelled by this Label.keyword text: If given, used as the text for the label rather than the default value (html_input.label). keyword css_id: (See reahl.web.ui.HTMLElement)
Deprecated since version 3.2: Please use Label(for_input=) 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.
reahl.web.ui.ErrorLabel(html_input, text=None, css_id=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.
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
reahl.web.ui.Table(view, caption_text=None, summary=None, css_id=None)¶An HTML table element: data displayed on columns and rows.
| Parameters: |
|
|---|
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: |
|
|---|
with_data(columns, items)¶Populate the table with the given data. Data is arranged into columns as
defined by the list of DynamicColumn or StaticColumn instances passed in.
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
reahl.web.ui.Caption(view, text=None, css_id=None)¶An HTML caption element.
Styling
Renders as an HTML <caption> element.
| Parameters: |
|
|---|
reahl.web.ui.Thead(view, css_id=None)¶An HTML thead element. Contains the header of the table columns.
| Parameters: |
|
|---|
reahl.web.ui.Tfoot(view, css_id=None)¶An HTML tfoot element. Contains the footer of the table columns.
| Parameters: |
|
|---|
reahl.web.ui.Tbody(view, css_id=None)¶An HTML tbody element. Contains the rows with data in the table.
| Parameters: |
|
|---|
reahl.web.ui.Tr(view, css_id=None)¶An HTML tr element represents one row of data in a table.
| Parameters: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
reahl.web.ui.TabbedPanel(view, css_id)¶A Div 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: |
|
|---|
add_tab(tab)¶Adds the Tab tab to this TabbedPanel.
reahl.web.ui.SlidingPanel(view, css_id=None, next='>', prev='<')¶A Div 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 Div. 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 Div 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: |
|
|---|
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: |
|
|---|
reahl.web.ui.FileUploadInput(form, bound_field, name=None)¶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
NestedForm,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: |
|
|---|
Deprecated since version 3.1: Please use the new layout concepts based on Pure instead.
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 since version 3.1: Please use reahl.web.layout:PageLayout 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.
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.
reahl.web.ui.YuiGrid(view, css_id=None)¶A Yui 2 grid: see http://developer.yahoo.com/yui/grids/#start
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.
reahl.web.ui.YuiBlock(view, css_id=None)¶A Yui 2 block: see http://developer.yahoo.com/yui/grids/#start
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.
reahl.web.ui.Panel(view, css_id=None)¶A logical container for other Widgets.
Styling
Renders as an HTML <div> element.
Deprecated since version 3.2: Please use reahl.web.ui:Div 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.
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).
| Parameters: |
|
|---|
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.