def radio(name, value, checked=False, label=None, **attrs):
"""Create a radio button.
Arguments:
``name`` -- the field's name.
``value`` -- the value returned to the application if the button is
pressed.
``checked`` -- true if the button should be initially pressed.
``label`` -- a text label to display to the right of the button.
The id of the radio button will be set to the name + '_' + value to
ensure its uniqueness. An ``id`` keyword arg overrides this. (Note
that this behavior is unique to the ``radio()`` helper.)
To arrange multiple radio buttons in a group, see
webhelpers.containers.distribute().
"""
_set_input_attrs(attrs, "radio", name, value)
if checked:
attrs["checked"] = "checked"
if not "id" in attrs:
attrs["id"] = '%s_%s' % (name, _make_safe_id_component(value))
widget = HTML.input(**attrs)
if label:
widget = HTML.label(widget, label)
return widget
def radio(name, value, checked=False, label=None, **attrs):
"""Create a radio button.
Arguments:
``name`` -- the field's name.
``value`` -- the value returned to the application if the button is
pressed.
``checked`` -- true if the button should be initially pressed.
``label`` -- a text label to display to the right of the button.
The id of the radio button will be set to the name + '_' + value to
ensure its uniqueness. An ``id`` keyword arg overrides this. (Note
that this behavior is unique to the ``radio()`` helper.)
To arrange multiple radio buttons in a group, see
webhelpers.containers.distribute().
"""
_set_input_attrs(attrs, "radio", name, value)
if checked:
attrs["checked"] = "checked"
if not "id" in attrs:
attrs["id"] = '%s_%s' % (name, _make_safe_id_component(value))
widget = HTML.input(**attrs)
if label:
widget = HTML.label(widget, label)
return widget
def checkbox(label, name, checked=False, **kwargs):
kwargs['type'] = 'checkbox'
kwargs['name'] = name
if checked:
kwargs['checked'] = 'checked'
kwargs.setdefault('id', name)
return HTML.div(class_='formField checkbox',
id='%s-field' % kwargs['id'],
c=[HTML.label(for_=name, c=[
HTML.input(**kwargs),
HTML.span(class_='labelText', c=[label])
]),
HTML.literal('<form:error name="%s" />' % name)])
def title(title, required=False, label_for=None):
"""Format the user-visible title for a form field.
Use this for forms that have a text title above or next to each
field.
``title`` -- the name of the field; e.g., "First Name".
``required`` -- if true, append a \*" to the title and use the
'required' HTML format (see example); otherwise use the 'not
required' format.
``label_for`` -- if provided, put ``<label for="ID">`` around the
title. The value should be the HTML ID of the input field related
to this title. Per the HTML standard, the ID should point to a
single control (input, select, textarea), not to multiple controls
(fieldset, group of checkboxes, group of radio buttons). ID's are
set by passing the keyword arg ``id`` to the appropriate helper.
Note that checkboxes and radio buttions typically have their own
individual labels in addition to the title. You can set these with
the ``label`` argument to ``checkbox()`` and ``radio()``.
This helper does not accept other keyword arguments.
See webhepers/public/stylesheets/webhelpers.css for suggested styles.
>>> title("First Name")
literal(%(u)s'<span class="not-required">First Name</span>')
>>> title("Last Name", True)
literal(%(u)s'<span class="required">Last Name <span class="required-symbol">*</span></span>')
>>> title("First Name", False, "fname")
literal(%(u)s'<span class="not-required"><label for="fname">First Name</label></span>')
>>> title("Last Name", True, label_for="lname")
literal(%(u)s'<span class="required"><label for="lname">Last Name</label> <span class="required-symbol">*</span></span>')
"""
title_html = title
required_html = literal("")
if label_for:
title_html = HTML.label(title_html, for_=label_for)
if required:
required_symbol = HTML.span("*", class_="required-symbol")
return HTML.span(
title_html,
" ",
required_symbol,
class_="required")
else:
return HTML.span(title_html, class_="not-required")
def input_area(name, title, value='', cols='50', rows='5', help_text=None, disabled=False, **kwargs):
expl = None
if help_text is not None:
expl = HTML.span(class_='helpText', c=help_text)
if disabled:
kwargs['disabled'] = 'disabled'
kwargs.setdefault('id', name)
return HTML.div(class_='formField',
id='%s-field' % kwargs['id'],
c=[HTML.label(for_=name, c=[
HTML.span(class_='labelText', c=[title]),
HTML.span(class_='textField', c=[
HTML.textarea(name_=name, cols=cols, rows=rows, c=[value], **kwargs),
])]),
HTML.literal('<form:error name="%s" />' % name),
expl])
def select_radio(name, title, options, selected=[], help_text=None, **kwargs):
expl = None
if help_text is not None:
expl = HTML.span(class_='helpText', c=help_text)
radios = []
for value, label in options:
checked = value in selected
radios.append(radio(name, value, checked, label, **kwargs))
return HTML.div(class_='formField',
id='%s-field' % name,
c=[HTML.label(for_=name, c=[
HTML.span(class_='labelText', c=[title]),
HTML.span(class_='radioField', c=radios)]),
HTML.literal('<form:error name="%s" />' % name),
expl])
def title(title, required=False, label_for=None):
"""Format the user-visible title for a form field.
Use this for forms that have a text title above or next to each
field.
``title`` -- the name of the field; e.g., "First Name".
``required `` -- if true, append a "*" to the title and use the
'required' HTML format (see example); otherwise use the 'not
required' format.
``label_for`` -- if provided, put ``<label for="ID">`` around the
title. The value should be the HTML ID of the input field related
to this title. Per the HTML standard, the ID should point to a
single control (input, select, textarea), not to multiple controls
(fieldset, group of checkboxes, group of radio buttons). ID's are
set by passing the keyword arg ``id`` to the appropriate helper.
Note that checkboxes and radio buttions typically have their own
individual labels in addition to the title. You can set these with
the ``label`` argument to ``checkbox()`` and ``radio()``.
This helper does not accept other keyword arguments.
See webhepers/public/stylesheets/webhelpers.css for suggested styles.
>>> title("First Name")
literal(u'<span class="not-required">First Name</span>')
>>> title("Last Name", True)
literal(u'<span class="required">Last Name <span class="required-symbol">*</span></span>')
>>> title("First Name", False, "fname")
literal(u'<span class="not-required"><label for="fname">First Name</label></span>')
>>> title("Last Name", True, label_for="lname")
literal(u'<span class="required"><label for="lname">Last Name</label> <span class="required-symbol">*</span></span>')
"""
title_html = title
required_html = literal("")
if label_for:
title_html = HTML.label(title_html, for_=label_for)
if required:
required_symbol = HTML.span("*", class_="required-symbol")
return HTML.span(title_html, " ", required_symbol, class_="required")
else:
return HTML.span(title_html, class_="not-required")
def select_line(name, title, options, selected=[], help_text=None, right_next=None, **kwargs):
expl = None
if help_text is not None:
expl = HTML.span(class_='helpText', c=help_text)
next = None
if right_next is not None:
next = HTML.span(class_='rightNext', c=right_next)
kwargs.setdefault('id', name)
field = select(name, selected, options, **kwargs)
return HTML.div(class_='formField',
id='%s-field' % kwargs['id'],
c=[HTML.label(for_=name, c=[
HTML.span(class_='labelText', c=[title]),
HTML.span(class_='textField', c=[
field,
])]),
next,
HTML.literal('<form:error name="%s" />' % name),
expl])
def input_line(name, title, value='', help_text=None, right_next=None, **kwargs):
expl = None
if help_text is not None:
expl = HTML.span(class_='helpText', c=help_text)
next = None
if right_next is not None:
next = HTML.span(class_='rightNext', c=right_next)
kwargs.setdefault('id', name)
kwargs.setdefault('type', 'text')
return HTML.div(class_='formField',
id='%s-field' % kwargs['id'],
c=[HTML.label(for_=name, c=[
HTML.span(class_='labelText', c=[title]),
HTML.span(class_='textField', c=[
HTML.input(value=value, name_=name, **kwargs),
])]),
next,
HTML.literal('<form:error name="%s" />' % name),
expl])
def checkbox(name, value="1", checked=False, label=None, id=None, **attrs):
"""Create a check box.
Arguments:
``name`` -- the widget's name.
``value`` -- the value to return to the application if the box is checked.
``checked`` -- true if the box should be initially checked.
``label`` -- a text label to display to the right of the box.
``id`` is the HTML ID attribute, and should be passed as a keyword
argument. By default the ID is the same as the name filtered through
``_make_safe_id_component()``. Pass the empty string ("") to suppress the
ID attribute entirely.
d
The following HTML attributes may be set by keyword argument:
* ``disabled`` - If true, checkbox will be grayed out.
* ``readonly`` - If true, the user will not be able to modify the checkbox.
To arrange multiple checkboxes in a group, see
webhelpers.containers.distribute().
Example::
>>> checkbox("hi")
literal(u'<input id="hi" name="hi" type="checkbox" value="1" />')
"""
_set_input_attrs(attrs, "checkbox", name, value)
_set_id_attr(attrs, id, name)
if checked:
attrs["checked"] = "checked"
convert_boolean_attrs(attrs, ["disabled", "readonly"])
widget = HTML.input(**attrs)
if label:
widget = HTML.label(widget, label)
return widget
def checkbox(name, value="1", checked=False, label=None, id=None, **attrs):
"""Create a check box.
Arguments:
``name`` -- the widget's name.
``value`` -- the value to return to the application if the box is checked.
``checked`` -- true if the box should be initially checked.
``label`` -- a text label to display to the right of the box.
``id`` is the HTML ID attribute, and should be passed as a keyword
argument. By default the ID is the same as the name filtered through
``_make_safe_id_component()``. Pass the empty string ("") to suppress the
ID attribute entirely.
d
The following HTML attributes may be set by keyword argument:
* ``disabled`` - If true, checkbox will be grayed out.
* ``readonly`` - If true, the user will not be able to modify the checkbox.
To arrange multiple checkboxes in a group, see
webhelpers.containers.distribute().
Example::
>>> checkbox("hi")
literal(u'<input id="hi" name="hi" type="checkbox" value="1" />')
"""
_set_input_attrs(attrs, "checkbox", name, value)
_set_id_attr(attrs, id, name)
if checked:
attrs["checked"] = "checked"
convert_boolean_attrs(attrs, ["disabled", "readonly"])
widget = HTML.input(**attrs)
if label:
widget = HTML.label(widget, label)
return widget
def field(
label='',
field='',
required=False,
label_desc='',
field_desc='',
sub_label='',
help='',
error=''
):
"""\
Format a field with a label.
``label``
The label for the field
``field``
The HTML representing the field. If not using
``webhelpers.html.tags``, wrap the HTML in a ``literal()``.
``required``
Can be ``True`` or ``False`` depending on whether the label should be
formatted as required or not. By default required fields have an
asterix.
``label_desc``
Any text to appear underneath the label, level with ``field_desc`` .
``field_desc``
Any text to appear underneath the field
``sub_label``
Any text to appear immediately beneath the label but above the
label_desc. This is useful if the field itself is very large and using
label_desc would result in the description of the label being a long
way from the label itself.
``help``
Any HTML or JavaScript to appear imediately to the right of the field
which could be used to implement a help system on the form
``error``
Any text to appear immediately before the HTML field, usually used for
an error message.
It should be noted that when used with FormEncode's ``htmlfill`` module,
errors appear immediately before the HTML field in the position of the
``error`` argument. No ``<form:error>`` tags are added automatically by
this helper because errors are placed there anyway and adding the tags
would lead to this helper generating invalid HTML.
"""
field = error + field
if label:
label = label + literal(":")
output = []
if required:
required = HTML.span("*", class_="required")
else:
required = ""
desc = ""
if sub_label:
desc = HTML.br() + HTML.span(sub_label, class_="small")
if help:
output.append(
HTML.tr(class_="field", c=[
HTML.td(class_="label", valign="top", c=[
required, HTML.label(label), desc),
class_="label", valign="top")
]
]
)
required = HTML.span("*", class_="required")
else:
required = ""
desc = ""
if sub_label:
desc = HTML.br() + HTML.span(sub_label, class_="small")
if help:
output.append(
HTML.tr(class_="field", c=[
HTML.td(class_="label", valign="top", c=[
required, HTML.label(label), desc),
class_="label", valign="top")
]
]
)
output.append(literal('<tr class="field"><td valign="top" class="label">')+required+HTML.label(c=label)+desc+literal('</td><td>')+field+literal('</td><td>')+help+literal('</td></tr>'))
else:
output.append(literal('<tr class="field"><td valign="top" class="label">')+required+HTML.label(c=label)+desc+literal('</td><td colspan="2">')+field+literal('</td></tr>'))
if label_desc or field_desc:
output.append(literal('<tr class="description"><td valign="top" class="label"><span class="small">')+label_desc+literal('</span></td><td valign="top" colspan="2"><span class="small">')+field_desc+literal('</span></td></tr>'))
return ''.join(output)
def options_with_caption(container, caption='Please select...', pos=0, value='', *k, **p):
"""\
Return a some select options adding in a value of '' with a caption specified by ``text``.
"""
if pos=='end':
container.append([caption, value])
else:
def field(
label='',
field='',
required=False,
label_desc='',
field_desc='',
sub_label='',
help='',
error=''
):
"""\
Format a field with a label.
``label``
The label for the field
``field``
The HTML representing the field, wrapped in ``literal()``
``required``
Can be ``True`` or ``False`` depending on whether the label should be
formatted as required or not. By default required fields have an
asterix.
``label_desc``
Any text to appear underneath the label, level with ``field_desc``
``field_desc``
Any text to appear underneath the field
``sub_label``
Any text to appear immediately beneath the label but above the
label_desc. This is useful if the field itself is very large and using
label_desc would result in the description of the label being a long
way from the label itself.
``help``
Any HTML or JavaScript to appear imediately to the right of the field
which could be used to implement a help system on the form
``error``
Any text to appear immediately before the HTML field, usually used for
an error message.
It should be noted that when used with FormEncode's ``htmlfill`` module,
errors appear immediately before the HTML field in the position of the
``error`` argument. No ``<form:error>`` tags are added automatically by
this helper because errors are placed there anyway and adding the tags
would lead to this helper generating invalid HTML.
"""
field = error+field
if label:
label = label + literal(':')
output = []
if required:
required = HTML.span(class_="required", c='*')
else:
required = ''
desc = ''
if sub_label:
desc = '<br /><span class="small">%s</span>'%sub_label
if help:
output.append(literal('<tr class="field"><td valign="top" class="label">')+required+HTML.label(c=label)+desc+literal('</td><td>')+field+literal('</td><td>')+help+literal('</td></tr>'))
else:
output.append(literal('<tr class="field"><td valign="top" class="label">')+required+HTML.label(c=label)+desc+literal('</td><td colspan="2">')+field+literal('</td></tr>'))
if label_desc or field_desc:
output.append(literal('<tr class="description"><td valign="top" class="label"><span class="small">')+label_desc+literal('</span></td><td valign="top" colspan="2"><span class="small">')+field_desc+literal('</span></td></tr>'))
return ''.join(output)
def field(
label='',
field='',
required=False,
label_desc='',
field_desc='',
help='',
error='',
field_pre='',
):
"""\
Format a field with a label.
``label``
The label for the field
``field``
The HTML representing the field, wrapped in ``literal()``
``required``
Can be ``True`` or ``False`` depending on whether the label should be
formatted as required or not. By default required fields have an
asterix.
``label_desc``
Any text to appear underneath the label, level with ``field_desc``
``field_desc``
Any text to appear underneath the field
``help``
Any HTML or JavaScript to appear imediately to the right of the field
which could be used to implement a help system on the form
``error``
Any text to appear immediately before the HTML field, usually used for
an error message.
It should be noted that when used with FormEncode's ``htmlfill`` module,
errors appear immediately before the HTML field in the position of the
``error`` argument. No ``<form:error>`` tags are added automatically by
this helper because errors are placed there anyway and adding the tags
would lead to this helper generating invalid HTML.
``field_pre``
Any HTML to appear immediately above the field.
TIP: For future compatibility, always specify arguments explicitly and do
not rely on their order in the function definition.
Here are some examples:
>>> print field('email >', literal('<input type="text" name="test" value="" />'), required=True)
<tr class="field">
<td class="label" valign="top"><span class="required">*</span><label>email >:</label></td>
<td class="field" colspan="2" valign="top"><input type="text" name="test" value="" /></td>
</tr>
>>> print field(
... label='email >',
... field=literal('<input type="text" name="test" value="" />'),
... label_desc='including the @ sign',
... field_desc='Please type your email carefully',
... error='This is an error message <br />',
... help = 'No help available for this field',
... required=True,
... )
...
<tr class="field">
<td class="label" valign="top"><span class="required">*</span><label>email >:</label></td>
<td class="field" valign="top"><div class="error">This is an error message <br /></div><input type="text" name="test" value="" /></td>
<td class="help" valign="top">No help available for this field</td>
</tr>
<tr class="description">
<td class="label_desc" valign="top"><span class="small">including the @ sign</span></td>
<td class="field_desc" colspan="2" valign="top"><span class="small">Please type your email carefully</span></td>
</tr>
An appropriate stylesheet to use to style forms generated with field() when
the table class is specified as "formbuild" would be::
table.formbuild span.error-message, table.formbuild div.error, table.formbuild span.required {
font-weight: bold;
color: #f00;
}
table.formbuild span.small {
font-size: 85%;
}
table.formbuild form {
margin-top: 20px;
}
table.formbuild form table td {
padding-bottom: 3px;
}
"""
if error:
field = HTML.div(class_='error', c=error)+field
if label:
label = label + literal(':')
if field_pre:
field = HTML.div(c=field_pre) + field
rows = []
if required:
required_html = HTML.span(class_="required", c='*')
else:
required_html = HTML.span(style="visibility: hidden", c='*')
label_html = HTML.td(valign="top", class_="label", c=required_html+HTML.label(c=label))
if help:
field_html = HTML.td(valign="top", class_="field", c=field)
help_html = HTML.td(valign="top", class_="help", c=help)+'\n'
else:
field_html = HTML.td(valign="top", class_="field", colspan="2", c=field)
help_html = ''
rows.append(HTML.tr(class_='field', c='\n'+label_html+'\n'+field_html+'\n'+help_html))
if label_desc or field_desc:
label_desc_html = HTML.td(valign="top", class_="label_desc", c=HTML.span(class_="small", c=label_desc))
field_desc_html = HTML.td(valign="top", class_="field_desc", colspan="2", c=HTML.span(class_="small", c=field_desc))
rows.append(HTML.tr(class_="description", c='\n'+label_desc_html+'\n'+field_desc_html+'\n'))
return literal('\n').join(rows)
def input_wysiwyg(name, title, value='', cols='60', rows='15'):
return HTML.div(class_='form-field', c=[
HTML.label(for_=name, c=[title]),
HTML.textarea(class_='ckeditor', name_=name, id_=name, cols=cols, rows=rows, c=[value]),
HTML.literal('<form:error name="%s" />' % name)
])
