diff --git a/gluon/html.py b/gluon/html.py index ff826542..6c87dcf6 100644 --- a/gluon/html.py +++ b/gluon/html.py @@ -2,9 +2,12 @@ # -*- coding: utf-8 -*- """ -This file is part of the web2py Web Framework -Copyrighted by Massimo Di Pierro -License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html) +| This file is part of the web2py Web Framework +| Copyrighted by Massimo Di Pierro +| License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html) + +Template helpers +-------------------------------------------- """ import cgi @@ -109,10 +112,11 @@ __all__ = [ def xmlescape(data, quote=True): """ - returns an escaped string of the provided data + Returns an escaped string of the provided data - :param data: the data to be escaped - :param quote: optional (default False) + Args: + data: the data to be escaped + quote: optional (default False) """ # first try the xml function @@ -164,80 +168,92 @@ def URL( language=None, ): """ - generate a URL - - example:: - - >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], - ... vars={'p':1, 'q':2}, anchor='1')) - '/a/c/f/x/y/z?p=1&q=2#1' - - >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], - ... vars={'p':(1,3), 'q':2}, anchor='1')) - '/a/c/f/x/y/z?p=1&p=3&q=2#1' - - >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], - ... vars={'p':(3,1), 'q':2}, anchor='1')) - '/a/c/f/x/y/z?p=3&p=1&q=2#1' - - >>> str(URL(a='a', c='c', f='f', anchor='1+2')) - '/a/c/f#1%2B2' - - >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], - ... vars={'p':(1,3), 'q':2}, anchor='1', hmac_key='key')) - '/a/c/f/x/y/z?p=1&p=3&q=2&_signature=a32530f0d0caa80964bb92aad2bedf8a4486a31f#1' - - >>> str(URL(a='a', c='c', f='f', args=['w/x', 'y/z'])) - '/a/c/f/w/x/y/z' - - >>> str(URL(a='a', c='c', f='f', args=['w/x', 'y/z'], encode_embedded_slash=True)) - '/a/c/f/w%2Fx/y%2Fz' - - >>> str(URL(a='a', c='c', f='f', args=['%(id)d'], url_encode=False)) - '/a/c/f/%(id)d' - - >>> str(URL(a='a', c='c', f='f', args=['%(id)d'], url_encode=True)) - '/a/c/f/%25%28id%29d' - - >>> str(URL(a='a', c='c', f='f', vars={'id' : '%(id)d' }, url_encode=False)) - '/a/c/f?id=%(id)d' - - >>> str(URL(a='a', c='c', f='f', vars={'id' : '%(id)d' }, url_encode=True)) - '/a/c/f?id=%25%28id%29d' - - >>> str(URL(a='a', c='c', f='f', anchor='%(id)d', url_encode=False)) - '/a/c/f#%(id)d' - - >>> str(URL(a='a', c='c', f='f', anchor='%(id)d', url_encode=True)) - '/a/c/f#%25%28id%29d' - generates a url '/a/c/f' corresponding to application a, controller c and function f. If r=request is passed, a, c, f are set, respectively, to r.application, r.controller, r.function. The more typical usage is: - URL(r=request, f='index') that generates a url for the index function + URL('index') + + that generates a url for the index function within the present application and controller. - :param a: application (default to current if r is given) - :param c: controller (default to current if r is given) - :param f: function (default to current if r is given) - :param r: request (optional) - :param args: any arguments (optional) - :param vars: any variables (optional) - :param anchor: anchorname, without # (optional) - :param hmac_key: key to use when generating hmac signature (optional) - :param hash_vars: which of the vars to include in our hmac signature - True (default) - hash all vars, False - hash none of the vars, - iterable - hash only the included vars ['key1','key2'] - :param scheme: URI scheme (True, 'http' or 'https', etc); forces absolute URL (optional) - :param host: string to force absolute URL with host (True means http_host) - :param port: optional port number (forces absolute URL) + Args: + a: application (default to current if r is given) + c: controller (default to current if r is given) + f: function (default to current if r is given) + r: request (optional) + args: any arguments (optional). Additional "path" elements + vars: any variables (optional). Querystring elements + anchor: anchorname, without # (optional) + extension: force an extension + hmac_key: key to use when generating hmac signature (optional) + hash_vars: which of the vars to include in our hmac signature + True (default) - hash all vars, False - hash none of the vars, + iterable - hash only the included vars ['key1','key2'] + salt: salt hashing with this string + user_signature: signs automatically the URL in such way that only the + user can access the URL (use with `URL.verify` or + `auth.requires_signature()`) + scheme: URI scheme (True, 'http' or 'https', etc); forces absolute URL (optional) + host: string to force absolute URL with host (True means http_host) + port: optional port number (forces absolute URL) + encode_embedded_slash: encode slash characters included in args + url_encode: encode characters included in vars + + Raises: + SyntaxError: when no application, controller or function is available + or when a CRLF is found in the generated url + + Examples: + + >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], + ... vars={'p':1, 'q':2}, anchor='1')) + '/a/c/f/x/y/z?p=1&q=2#1' + + >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], + ... vars={'p':(1,3), 'q':2}, anchor='1')) + '/a/c/f/x/y/z?p=1&p=3&q=2#1' + + >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], + ... vars={'p':(3,1), 'q':2}, anchor='1')) + '/a/c/f/x/y/z?p=3&p=1&q=2#1' + + >>> str(URL(a='a', c='c', f='f', anchor='1+2')) + '/a/c/f#1%2B2' + + >>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'], + ... vars={'p':(1,3), 'q':2}, anchor='1', hmac_key='key')) + '/a/c/f/x/y/z?p=1&p=3&q=2&_signature=a32530f0d0caa80964bb92aad2bedf8a4486a31f#1' + + >>> str(URL(a='a', c='c', f='f', args=['w/x', 'y/z'])) + '/a/c/f/w/x/y/z' + + >>> str(URL(a='a', c='c', f='f', args=['w/x', 'y/z'], encode_embedded_slash=True)) + '/a/c/f/w%2Fx/y%2Fz' + + >>> str(URL(a='a', c='c', f='f', args=['%(id)d'], url_encode=False)) + '/a/c/f/%(id)d' + + >>> str(URL(a='a', c='c', f='f', args=['%(id)d'], url_encode=True)) + '/a/c/f/%25%28id%29d' + + >>> str(URL(a='a', c='c', f='f', vars={'id' : '%(id)d' }, url_encode=False)) + '/a/c/f?id=%(id)d' + + >>> str(URL(a='a', c='c', f='f', vars={'id' : '%(id)d' }, url_encode=True)) + '/a/c/f?id=%25%28id%29d' + + >>> str(URL(a='a', c='c', f='f', anchor='%(id)d', url_encode=False)) + '/a/c/f#%(id)d' + + >>> str(URL(a='a', c='c', f='f', anchor='%(id)d', url_encode=True)) + '/a/c/f#%25%28id%29d' + + + - :raises SyntaxError: when no application, controller or function is - available - :raises SyntaxError: when a CRLF is found in the generated url """ from rewrite import url_out # done here in case used not-in web2py @@ -528,7 +544,7 @@ class XML(XmlComponent): use it to wrap a string that contains XML/HTML so that it will not be escaped by the template - example: + Examples: >>> XML('

Hello

').xml() '

Hello

' @@ -564,19 +580,19 @@ class XML(XmlComponent): }, ): """ - :param text: the XML text - :param sanitize: sanitize text using the permitted tags and allowed - attributes (default False) - :param permitted_tags: list of permitted tags (default: simple list of - tags) - :param allowed_attributes: dictionary of allowed attributed (default - for A, IMG and BlockQuote). - The key is the tag; the value is a list of allowed attributes. + Args: + text: the XML text + sanitize: sanitize text using the permitted tags and allowed + attributes (default False) + permitted_tags: list of permitted tags (default: simple list of + tags) + allowed_attributes: dictionary of allowed attributed (default + for A, IMG and BlockQuote). + The key is the tag; the value is a list of allowed attributes. """ if sanitize: - text = sanitizer.sanitize(text, permitted_tags, - allowed_attributes) + text = sanitizer.sanitize(text, permitted_tags, allowed_attributes) if isinstance(text, unicode): text = text.encode('utf8', 'xmlcharrefreplace') elif not isinstance(text, str): @@ -620,7 +636,8 @@ class XML(XmlComponent): def flatten(self, render=None): """ - return the text stored by the XML object rendered by the render function + returns the text stored by the XML object rendered + by the `render` function """ if render: return render(self.text, None, {}) @@ -628,8 +645,9 @@ class XML(XmlComponent): def elements(self, *args, **kargs): """ - to be considered experimental since the behavior of this method is questionable - another options could be TAG(self.text).elements(*args,**kargs) + to be considered experimental since the behavior of this method + is questionable + another option could be `TAG(self.text).elements(*args,**kwargs)` """ return [] @@ -653,15 +671,15 @@ class DIV(XmlComponent): Behaves like a dictionary regarding updating of attributes. Behaves like a list regarding inserting/appending components. - example:: + Examples: - >>> DIV('hello', 'world', _style='color:red;').xml() - '
helloworld
' + >>> DIV('hello', 'world', _style='color:red;').xml() + '
helloworld
' - all other HTML helpers are derived from DIV. + All other HTML helpers are derived from `DIV`. - _something=\"value\" attributes are transparently translated into - something=\"value\" HTML attributes + `_something="value"` attributes are transparently translated into + `something="value"` HTML attributes """ # name of the tag, subclasses should update this @@ -671,10 +689,12 @@ class DIV(XmlComponent): def __init__(self, *components, **attributes): """ - :param *components: any components that should be nested in this element - :param **attributes: any attributes you want to give to this element + Args: + components: any components that should be nested in this element + attributes: any attributes you want to give to this element - :raises SyntaxError: when a stand alone tag receives components + Raises: + SyntaxError: when a stand alone tag receives components """ if self.tag[-1:] == '/' and components: @@ -705,6 +725,8 @@ class DIV(XmlComponent): """ list style appending of components + Examples: + >>> a=DIV() >>> a.append(SPAN('x')) >>> print a @@ -717,7 +739,9 @@ class DIV(XmlComponent): def insert(self, i, value): """ - list style inserting of components + List-style inserting of components + + Examples: >>> a=DIV() >>> a.insert(0,SPAN('x')) @@ -731,12 +755,12 @@ class DIV(XmlComponent): def __getitem__(self, i): """ - gets attribute with name 'i' or component #i. + Gets attribute with name 'i' or component #i. If attribute 'i' is not found returns None - :param i: index - if i is a string: the name of the attribute - otherwise references to number of the component + Args: + i: index. If i is a string: the name of the attribute + otherwise references to number of the component """ if isinstance(i, str): @@ -749,12 +773,12 @@ class DIV(XmlComponent): def __setitem__(self, i, value): """ - sets attribute with name 'i' or component #i. + Sets attribute with name 'i' or component #i. - :param i: index - if i is a string: the name of the attribute - otherwise references to number of the component - :param value: the new value + Args: + i: index. If i is a string: the name of the attribute + otherwise references to number of the component + value: the new value """ self._setnode(value) if isinstance(i, (str, unicode)): @@ -764,11 +788,11 @@ class DIV(XmlComponent): def __delitem__(self, i): """ - deletes attribute with name 'i' or component #i. + Deletes attribute with name 'i' or component #i. - :param i: index - if i is a string: the name of the attribute - otherwise references to number of the component + Args: + i: index. If i is a string: the name of the attribute + otherwise references to number of the component """ if isinstance(i, str): @@ -778,13 +802,13 @@ class DIV(XmlComponent): def __len__(self): """ - returns the number of included components + Returns the number of included components """ return len(self.components) def __nonzero__(self): """ - always return True + Always returns True """ return True @@ -804,10 +828,11 @@ class DIV(XmlComponent): helper for _fixup. Checks if a component is in allowed_parents, otherwise wraps it in wrap_parent - :param allowed_parents: (tuple) classes that the component should be an - instance of - :param wrap_parent: the class to wrap the component in, if needed - :param wrap_lambda: lambda to use for wrapping, if needed + Args: + allowed_parents: (tuple) classes that the component should be an + instance of + wrap_parent: the class to wrap the component in, if needed + wrap_lambda: lambda to use for wrapping, if needed """ components = [] @@ -875,7 +900,7 @@ class DIV(XmlComponent): def _xml(self): """ - helper for xml generation. Returns separately: + Helper for xml generation. Returns separately: - the component attributes - the generated xml of the inner components @@ -883,7 +908,8 @@ class DIV(XmlComponent): do not have a False or None value. The underscore is removed. A value of True is replaced with the attribute name. - :returns: tuple: (attributes, components) + Returns: + tuple: (attributes, components) """ # get the attributes for this component @@ -932,16 +958,18 @@ class DIV(XmlComponent): def __str__(self): """ - str(COMPONENT) returns equals COMPONENT.xml() + str(COMPONENT) returns COMPONENT.xml() """ return self.xml() def flatten(self, render=None): """ - return the text stored by the DIV object rendered by the render function + Returns the text stored by the DIV object rendered by the render function the render function must take text, tagname, and attributes - render=None is equivalent to render=lambda text, tag, attr: text + `render=None` is equivalent to `render=lambda text, tag, attr: text` + + Examples: >>> markdown = lambda text,tag=None,attributes={}: \ {None: re.sub('\s+',' ',text), \ @@ -972,11 +1000,13 @@ class DIV(XmlComponent): def elements(self, *args, **kargs): """ - find all component that match the supplied attribute dictionary, + Find all components that match the supplied attribute dictionary, or None if nothing could be found All components of the components are searched. + Examples: + >>> a = DIV(DIV(SPAN('x'),3,DIV(SPAN('y')))) >>> for c in a.elements('span',first_only=True): c[0]='z' >>> print a @@ -987,6 +1017,8 @@ class DIV(XmlComponent): It also supports a syntax compatible with jQuery + Examples: + >>> a=TAG('
hello

world

') >>> for e in a.elements('div a#1-1, p.is'): print e.flatten() hello @@ -995,7 +1027,6 @@ class DIV(XmlComponent): hello >>> a.elements('a[u:v=$]')[0].xml() 'hello' - >>> a=FORM( INPUT(_type='text'), SELECT(range(1)), TEXTAREA() ) >>> for c in a.elements('input, select, textarea'): c['_disabled'] = 'disabled' >>> a.xml() @@ -1005,6 +1036,8 @@ class DIV(XmlComponent): a "replace" argument (note, a list of the original matching elements is still returned as usual). + Examples: + >>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc')))) >>> b = a.elements('span.abc', replace=P('x', _class='xyz')) >>> print a @@ -1013,6 +1046,8 @@ class DIV(XmlComponent): "replace" can be a callable, which will be passed the original element and should return a new element to replace it. + Examples: + >>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc')))) >>> b = a.elements('span.abc', replace=lambda el: P(el[0], _class='xyz')) >>> print a @@ -1020,6 +1055,8 @@ class DIV(XmlComponent): If replace=None, matching elements will be removed completely. + Examples: + >>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc')))) >>> b = a.elements('span', find='y', replace=None) >>> print a @@ -1030,6 +1067,8 @@ class DIV(XmlComponent): replaced (find_text is ignored if "replace" is not also specified). Like the "find" argument, "find_text" can be a string or a compiled regex. + Examples: + >>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc')))) >>> b = a.elements(find_text=re.compile('x|y|z'), replace='hello') >>> print a @@ -1038,6 +1077,8 @@ class DIV(XmlComponent): If other attributes are specified along with find_text, then only components that match the specified attributes will be searched for find_text. + Examples: + >>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='efg'), SPAN('z', _class='abc')))) >>> b = a.elements('span.efg', find_text=re.compile('x|y|z'), replace='hello') >>> print a @@ -1134,7 +1175,7 @@ class DIV(XmlComponent): def element(self, *args, **kargs): """ - find the first component that matches the supplied attribute dictionary, + Finds the first component that matches the supplied attribute dictionary, or None if nothing could be found Also the components of the components are searched. @@ -1148,7 +1189,7 @@ class DIV(XmlComponent): def siblings(self, *args, **kargs): """ - find all sibling components that match the supplied argument list + Finds all sibling components that match the supplied argument list and attribute dictionary, or None if nothing could be found """ sibs = [s for s in self.parent.components if not s == self] @@ -1175,7 +1216,7 @@ class DIV(XmlComponent): def sibling(self, *args, **kargs): """ - find the first sibling component that match the supplied argument list + Finds the first sibling component that match the supplied argument list and attribute dictionary, or None if nothing could be found """ kargs['first_only'] = True @@ -1211,10 +1252,12 @@ copy_reg.pickle(__tag_div__, TAG_pickler, TAG_unpickler) class __TAG__(XmlComponent): """ - TAG factory example:: + TAG factory - >>> print TAG.first(TAG.second('test'), _key = 3) - test + Examples: + + >>> print TAG.first(TAG.second('test'), _key = 3) + test """ @@ -1239,16 +1282,16 @@ class HTML(DIV): There are four predefined document type definitions. They can be specified in the 'doctype' parameter: - -'strict' enables strict doctype - -'transitional' enables transitional doctype (default) - -'frameset' enables frameset doctype - -'html5' enables HTML 5 doctype - -any other string will be treated as user's own doctype + - 'strict' enables strict doctype + - 'transitional' enables transitional doctype (default) + - 'frameset' enables frameset doctype + - 'html5' enables HTML 5 doctype + - any other string will be treated as user's own doctype 'lang' parameter specifies the language of the document. Defaults to 'en'. - See also :class:`DIV` + See also `DIV` """ tag = 'html' @@ -1289,10 +1332,10 @@ class XHTML(DIV): There are three predefined document type definitions. They can be specified in the 'doctype' parameter: - -'strict' enables strict doctype - -'transitional' enables transitional doctype (default) - -'frameset' enables frameset doctype - -any other string will be treated as user's own doctype + - 'strict' enables strict doctype + - 'transitional' enables transitional doctype (default) + - 'frameset' enables frameset doctype + - any other string will be treated as user's own doctype 'lang' parameter specifies the language of the document and the xml document. Defaults to 'en'. @@ -1300,7 +1343,7 @@ class XHTML(DIV): 'xmlns' parameter specifies the xml namespace. Defaults to 'http://www.w3.org/1999/xhtml'. - See also :class:`DIV` + See also `DIV` """ tag = 'html' @@ -1443,7 +1486,7 @@ class P(DIV): """ Will replace ``\\n`` by ``
`` if the `cr2br` attribute is provided. - see also :class:`DIV` + see also `DIV` """ tag = 'p' @@ -1476,6 +1519,23 @@ class HR(DIV): class A(DIV): + """ + Generates an A() link. + A() in web2py is really important and with the included web2py.js + allows lots of Ajax interactions in the page + + On top of "usual" `_attributes`, it takes + + Args: + callback: an url to call but not redirect to + cid: if you want to load the _href into an element of the page (component) + pass its id (without the #) here + delete: element to delete after calling callback + target: same thing as cid + confirm: text to display upon a callback with a delete + noconfirm: don't display alert upon a callback with delete + + """ tag = 'a' @@ -1546,24 +1606,25 @@ class CENTER(DIV): class CODE(DIV): """ - displays code in HTML with syntax highlighting. + Displays code in HTML with syntax highlighting. - :param attributes: optional attributes: + Args: + language: indicates the language, otherwise PYTHON is assumed + link: can provide a link + styles: for styles - - language: indicates the language, otherwise PYTHON is assumed - - link: can provide a link - - styles: for styles + Examples: - Example:: - - {{=CODE(\"print 'hello world'\", language='python', link=None, - counter=1, styles={}, highlight_line=None)}} + {{=CODE(\"print 'hello world'\", language='python', link=None, + counter=1, styles={}, highlight_line=None)}} - supported languages are \"python\", \"html_plain\", \"c\", \"cpp\", - \"web2py\", \"html\". - The \"html\" language interprets {{ and }} tags as \"web2py\" code, - \"html_plain\" doesn't. + supported languages are + + "python", "html_plain", "c", "cpp", "web2py", "html" + + The "html" language interprets {{ and }} tags as "web2py" code, + "html_plain" doesn't. if a link='/examples/global/vars/' is provided web2py keywords are linked to the online docs. @@ -1607,7 +1668,6 @@ class UL(DIV): If subcomponents are not LI-components they will be wrapped in a LI - see also :class:`DIV` """ tag = 'ul' @@ -1637,7 +1697,6 @@ class TR(DIV): If subcomponents are not TD/TH-components they will be wrapped in a TD - see also :class:`DIV` """ tag = 'tr' @@ -1652,7 +1711,6 @@ class __TRHEAD__(DIV): If subcomponents are not TD/TH-components they will be wrapped in a TH - see also :class:`DIV` """ tag = 'tr' @@ -1702,7 +1760,6 @@ class TABLE(DIV): If subcomponents are not TR/TBODY/THEAD/TFOOT-components they will be wrapped in a TR - see also :class:`DIV` """ tag = 'table' @@ -1724,34 +1781,36 @@ class IFRAME(DIV): class INPUT(DIV): """ - INPUT Component + INPUT Component - examples:: + Takes two special attributes value= and requires=. - >>> INPUT(_type='text', _name='name', value='Max').xml() - '' - - >>> INPUT(_type='checkbox', _name='checkbox', value='on').xml() - '' - - >>> INPUT(_type='radio', _name='radio', _value='yes', value='yes').xml() - '' - - >>> INPUT(_type='radio', _name='radio', _value='no', value='yes').xml() - '' - - the input helper takes two special attributes value= and requires=. - - :param value: used to pass the initial value for the input field. + Args: + value: used to pass the initial value for the input field. value differs from _value because it works for checkboxes, radio, textarea and select/option too. + For a checkbox value should be '' or 'on'. + For a radio or select/option value should be the _value + of the checked/selected item. - - for a checkbox value should be '' or 'on'. - - for a radio or select/option value should be the _value - of the checked/selected item. - - :param requires: should be None, or a validator or a list of validators + requires: should be None, or a validator or a list of validators for the value of the field. + + Examples: + + >>> INPUT(_type='text', _name='name', value='Max').xml() + '' + + >>> INPUT(_type='checkbox', _name='checkbox', value='on').xml() + '' + + >>> INPUT(_type='radio', _name='radio', _value='yes', value='yes').xml() + '' + + >>> INPUT(_type='radio', _name='radio', _value='no', value='yes').xml() + '' + + """ tag = 'input/' @@ -1847,11 +1906,12 @@ class INPUT(DIV): class TEXTAREA(INPUT): """ - example:: + Examples:: - TEXTAREA(_name='sometext', value='blah '*100, requires=IS_NOT_EMPTY()) + TEXTAREA(_name='sometext', value='blah ' * 100, requires=IS_NOT_EMPTY()) 'blah blah blah ...' will be the content of the textarea field. + """ tag = 'textarea' @@ -1898,12 +1958,12 @@ class OPTGROUP(DIV): class SELECT(INPUT): """ - example:: + Examples: - >>> from validators import IS_IN_SET - >>> SELECT('yes', 'no', _name='selector', value='yes', - ... requires=IS_IN_SET(['yes', 'no'])).xml() - '' + >>> from validators import IS_IN_SET + >>> SELECT('yes', 'no', _name='selector', value='yes', + ... requires=IS_IN_SET(['yes', 'no'])).xml() + '' """ @@ -1962,12 +2022,13 @@ class LEGEND(DIV): class FORM(DIV): """ - example:: + Examples: + + >>> from validators import IS_NOT_EMPTY + >>> form=FORM(INPUT(_name="test", requires=IS_NOT_EMPTY())) + >>> form.xml() + '
' - >>> from validators import IS_NOT_EMPTY - >>> form=FORM(INPUT(_name="test", requires=IS_NOT_EMPTY())) - >>> form.xml() - '
' a FORM is container for INPUT, TEXTAREA, SELECT and other helpers @@ -2107,12 +2168,12 @@ class FORM(DIV): you can use it instead of directly form.accepts. Usage: - In controller + In controller:: - def action(): - form=FORM(INPUT(_name=\"test\", requires=IS_NOT_EMPTY())) - form.validate() #you can pass some args here - see below - return dict(form=form) + def action(): + form=FORM(INPUT(_name=\"test\", requires=IS_NOT_EMPTY())) + form.validate() #you can pass some args here - see below + return dict(form=form) This can receive a bunch of arguments @@ -2190,29 +2251,31 @@ class FORM(DIV): """ Perform the .validate() method but returns the form - Usage in controllers: - # directly on return - def action(): - #some code here - return dict(form=FORM(...).process(...)) + Usage in controllers:: - You can use it with FORM, SQLFORM or FORM based plugins + # directly on return + def action(): + #some code here + return dict(form=FORM(...).process(...)) - Examples: - #response.flash messages - def action(): - form = SQLFORM(db.table).process(message_onsuccess='Sucess!') - retutn dict(form=form) + You can use it with FORM, SQLFORM or FORM based plugins:: + + # response.flash messages + def action(): + form = SQLFORM(db.table).process(message_onsuccess='Sucess!') + return dict(form=form) + + # callback function + # callback receives True or False as first arg, and a list of args. + def my_callback(status, msg): + response.flash = "Success! "+msg if status else "Errors occured" + + # after argument can be 'flash' to response.flash messages + # or a function name to use as callback or None to do nothing. + def action(): + return dict(form=SQLFORM(db.table).process(onsuccess=my_callback) - # callback function - # callback receives True or False as first arg, and a list of args. - def my_callback(status, msg): - response.flash = "Success! "+msg if status else "Errors occured" - # after argument can be 'flash' to response.flash messages - # or a function name to use as callback or None to do nothing. - def action(): - return dict(form=SQLFORM(db.table).process(onsuccess=my_callback) """ kwargs['dbio'] = kwargs.get('dbio', True) # necessary for SQLHTML forms @@ -2223,7 +2286,7 @@ class FORM(DIV): def add_button(self, value, url, _class=None): submit = self.element(_type='submit') - _class = "%s w2p-form-button" % _class if _class else "w2p-form-button" + _class = "%s w2p-form-button" % _class if _class else "w2p-form-button" submit.parent.append( TAG['button'](value, _class=_class, _onclick=url if url.startswith('javascript:') else @@ -2313,16 +2376,20 @@ class FORM(DIV): class BEAUTIFY(DIV): """ - example:: + Turns any list, dictionary, etc into decent looking html. - >>> BEAUTIFY(['a', 'b', {'hello': 'world'}]).xml() - '
a
b
hello:
world
' - - turns any list, dictionary, etc into decent looking html. Two special attributes are - :sorted: a function that takes the dict and returned sorted keys - :keyfilter: a funciton that takes a key and returns its representation - or None if the key is to be skipped. By default key[:1]=='_' is skipped. + + - sorted: a function that takes the dict and returned sorted keys + - keyfilter: a function that takes a key and returns its representation or + None if the key is to be skipped. + By default key[:1]=='_' is skipped. + + Examples: + + >>> BEAUTIFY(['a', 'b', {'hello': 'world'}]).xml() + '
a
b
hello:
world
' + """ tag = 'div' @@ -2394,16 +2461,18 @@ class MENU(DIV): """ Used to build menus - Optional arguments - _class: defaults to 'web2py-menu web2py-menu-vertical' - ul_class: defaults to 'web2py-menu-vertical' - li_class: defaults to 'web2py-menu-expand' - li_first: defaults to 'web2py-menu-first' - li_last: defaults to 'web2py-menu-last' + Args: + _class: defaults to 'web2py-menu web2py-menu-vertical' + ul_class: defaults to 'web2py-menu-vertical' + li_class: defaults to 'web2py-menu-expand' + li_first: defaults to 'web2py-menu-first' + li_last: defaults to 'web2py-menu-last' + + Use like:: - Example: menu = MENU([['name', False, URL(...), [submenu]], ...]) {{=menu}} + """ tag = 'ul' @@ -2503,9 +2572,10 @@ def embed64( """ helper to encode the provided (binary) data into base64. - :param filename: if provided, opens and reads this file in 'rb' mode - :param file: if provided, reads this file - :param data: if provided, uses the provided data + Args: + filename: if provided, opens and reads this file in 'rb' mode + file: if provided, reads this file + data: if provided, uses the provided data """ if filename and os.path.exists(file):