FastFormward: forms.py

"""
Cherry Forms - FastFormward

History:
0,3  @ 2005/05/07:
    Remco:
    - Support for fieldsets
    - support for compound fields (proof is there)
    - DateField implementation (look at how simple it is!)
    - Changed a line or two in inline docs and samples
0,2  @ 2005/05/07:
    Remco:
    - Added submit button as SubmitField.
    - Better support for submit buttons: they will not be displayed
      when validating. Beware, if your submit button is part of your data entry
      you might want to take good care of this :)
    - Added support for form logic error msg: invalidForm should return
      and error msg if the fields are not filled correctly. replaces validateForm
    - the onExit function will no longer be called with the form data, but with
      a dictionary where the key is the form name, and the value the pyValue(kwp)
      for that field, with the value of kwp being extracted from the session
      to avoid the entering new values hack. 
           
0.1  @ 2005/05/07:
    Remco:
    - gone public, still alfa, see wiki:
      http://www.cherrypy.org/wiki/CherryForms

<not public>
    Remco: first attempt at solving the problem
    as described on the wiki page


Copyright (c) 2004, CherryPy Team (team@cherrypy.org)
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, 
are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, 
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice, 
      this list of conditions and the following disclaimer in the documentation 
      and/or other materials provided with the distribution.
    * Neither the name of the CherryPy Team nor the names of its contributors 
      may be used to endorse or promote products derived from this software 
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
"""


__version__ = "0.1"
__authors__ = ['Remco Boerma: remco.boerma@gmail.com']
from cherrypy import cpg


######################################################################
## 
## ToSession and FromSession
## from http://www.cherrypy.org/wiki/FromAndToSession
## 
######################################################################

def toSession(**kwp):
    """Stores the keyword parameters in the cpg.request.sessionMap.
    like:
       toSession(bla=bla) will store the variable bla as 'bla'
    @returns: nothing.    
    """
    for k,v in kwp.items():
        cpg.request.sessionMap[k] = v

def fromSession(*names):
    """retreives the names from the cpg.request.sessionMap.
    like:
       bla,pir = fromSession('bla','pir') will load bla and pir
    @returns: the values for the keys named in 'names'
    @raises: nothing, None as value for a key that can't be found
    """
    values = []
    for name in names:
        try:
            values.append(cpg.request.sessionMap.get(name,None))
        except AttributeError:
            values.append(None)
    if len(values) ==1:
            ## allow for easy element retreival
            return values[0]
    else:
            return values



######################################################################
## 
## Fields
## 
######################################################################

import new
class Field(object):
    def __init__(self,
                 type,          # type of input ('compound' for custom compound inputs)
                 name,          # name of the input (or a list of names)
                 label=None,    # the label to precede the input
                 html=None,     # direct html entry
                 id=None,       # the dom ID
                 tip=None,      # tooltip, rendered probabely as title attribute
                 style=None,    # any direct style input
                 cssclass=None, # the CSS class 
                 helpmsg=None,  # any default help msg if input fails.
                 validate=None, # specific validation method (made an instancemethod using module new)
                 value=None,    # value if already known, can be anything, to support compound fields
                 **extraAttrs): # support for unknown tags
        """
        Base Field type. Use derivatives.. 
         type,          # type of input ('compound' for custom compound inputs)
         name,          # name of the input (or a list of names)
         label=None,    # the label to precede the input
         html=None,     # direct html entry
         id=None,       # the dom ID
         tip=None,      # tooltip, rendered probabely as title attribute
         style=None,    # any direct style input
         cssclass=None, # the CSS class 
         helpmsg=None,  # any default help msg if input fails.
         validate=None, # specific validation method (made an instancemethod using module new)
         value=None,    # value if already known, can be anything, to support compound fields
         **extraAttrs): # support for unknown tags
        """        
        assert type != None, 'Every input should be of _some_ type...'
        if type != 'submit':
            assert name != None, 'Every input should have _some_ name...'
        self.type = type
        self.name = name
        if label:
            self.label = label
        if html:
            self.html = html
        if id:
            self.id = id
        else:
            if name:
                self.id = "input."+name
        if tip:
            self.tip = tip
        if style:
            self.style = style
        if cssclass:
            self.cssclass = cssclass
        if helpmsg:
            self.helpmsg = helpmsg
        if validate:
            self.validate = new.instancemethod(validate,self)
        if value:
            self.value = value
        self.extraAttrs = extraAttrs

    def validate(self,form):
        """
        This means, that the Field will have to do it's own checking if there is a value
        for it in the form.
        Design decision: why not pass the corresponding value?
            - well, that is an option. But when using multiple values using a compund
              field, this can best be left to the specific Field.. """
        return True
        

    def errorMsg(self,form):
        "Override this: so you can write specific error msgs based on the data in form."
        return self.helpmsg 

    def build(self,form,readonly=False):
        """Called to build the html for this field, for the specified form.
        Should return a string.
        If readonly: the html should be rendered as readonly on the client side"""
        if hasattr(self,'_html'):
            return self._html
        if form == None:
            raise ValueError, 'Form cannot be None if no ._html was given for %r' % self
        def attr(name,varname):
            if not hasattr(self,varname):
                return ''
            else:
                # test if the value is None,
                # if so, it's not shown
                value = getattr(self,varname)
                if value == None:
                    return ''
                else:
                    return '%s="%s"' % (name,value)
        result = [] 
        if hasattr(self,'label'):
            result.append('<label %s >%s</label>' % (attr('for','id'), self.label))
        result.append("<input %s %s %s %s %s %s " % (attr('type','type'),
                                        attr('name','name'),
                                        attr('id','id'),
                                        attr('class','cssclass'),
                                        attr('title','tip'),
                                        attr('style','style')))
        if form.keys() and not self.validate(form):
            # if the input is invalid
            # add the erroreous attribute
            # so CSS can make it show a bit different
            result.append(' erroreous ')
            # an error msg could be put in the value... 
            result.append('value="%s:%s"' % (self.errorMsg(form),form.get(self.name,'')))
        else:
            result.append('value="%s"' % (form.get(self.name,'')))
        # add extra key="value" pairs
        result.extend(['%s="%s" ' % (pair) for pair in self.extraAttrs.items() if pair[1] != None])
        # add extra key fields (like multiple etc.)
        result.extend(['%s ' % key for key, value in self.extraAttrs.items() if value == None])
        if readonly:
            result.append(' readonly ')
        result.append('>')
        return "".join(result)
            
    def getHtml(self,form={}):
        "Property get method for html. the form parameter is the dictionary with form parameters"
        return self.build(form)

    def _setHtml(self,html):
        self._html = html

    def _delHtml(self):
        if hasattr(self,'_html'):
            del self._html 

    html = property(getHtml,_setHtml,_delHtml,doc="Generated or static html for input..")
    def pyValue(self,form):
        "Override this: return the python variant of this input based on the form dictionary."
        return None


class SubmitField(Field):
    def __init__(self,name=None,label=None,value='Submit',**kwp):
        "Create an integer entry"
        super(SubmitField,self).__init__('submit',name,label,value=value,**kwp)

    def validate(self,form):
        return True
    def build(self,kwp,readonly=False):
        html = super(SubmitField,self).build(kwp,readonly)
        # replace the value attribute, as it needs to be filled. .
        # but as the self.name is not a key in the kwp, the Field.build
        # method will not fill the value.. 
        return html.replace('value=""','value="%s"' % self.value)

    def pyValue(self,form):
        "returns true if this button was used.."
        keyAvailable = form.has_key(self.name)
        if not keyAvailable:
            return False
        if getattr(self,'value',None):
            return form[self.name] == self.value
        else:
            return keyAvailable 

class IntField(Field):
    def __init__(self,name,label,**kwp):
        "Create an integer entry"
        if 'helpmsg' not in kwp:
            kwp['helpmsg'] = 'Enter digits only'
        super(IntField,self).__init__('text',name,label,**kwp)

    def validate(self,form):
        value = form.get(self.name,'').strip()
        return bool(len(value) and value.isdigit())

    def pyValue(self,form):
        if self.validate(form):
            return int(form[self.name])
        else:
            return None

class SelectField(Field):
    # UNTESTED, in progress
    def __init__(self,name,label,multiple=False,tip=None,style=None,cssclass=None, values = None, **extraAttrs):
        "Create a select (drop) list field. Values is a list of (value,label) pairs"
        self.multiple = multiple
        if multiple:
            extraAttrs['multiple']=None
        super(Select,self).__init__('text',name,label,
                                      tip,style,cssclass
                                      **extraAttrs
                                      )
        self.options = value

    def build(self,form,readonly=False):
        # get the value from there
        val = super(SelectField,self).build(form,readonly)
        val.replace('<input','<select') # make it a select
        # add options
        val += "".join(['<option label="%s">%s</option>' % (label,value) for value, label in self.options])
        # add closing /select
        val +='</select>'
        


class RadioField(Field):
    def __init__(self,name,label,value='',**extraAttrs):
        "Create a field. "
        super(RadioField,self).__init__('radio',name,label,
                                      **extraAttrs)
        self.value = value

    def build(self,form,readonly=False):
        # get the value from there
        val = super(RadioField,self).build({},readonly)
        if form.get(self.name,None)==self.value:
            checked = 'CHECKED'
        else:
            checked = ''
        return val.replace('value=""','value="%s" %s' % (self.value, checked))

    def pyValue(self,form):
        return form.get(self.name,None)


class CheckField(Field):
    def __init__(self,name,label,value='',**extraAttrs):
        "Create a check field. "
        super(CheckField,self).__init__('checkbox',name,label,
                                      **extraAttrs)
        self.value = value

    def build(self,form,readonly=False):
        # get the value from there
        val = super(CheckField,self).build({},readonly)
        if form.get(self.name,None)==self.value:
            checked = 'CHECKED'
        else:
            checked = ''
        return val.replace('value=""','value="%s" %s' % (self.value, checked))

    def pyValue(self,form):
        vals = form.get(self.name,None)
        if type(vals) == type([]):
            return self.value in vals
        if type(vals) == type(""):
            return vals == self.value
        else:
            return False

######################################################################
## 
## FieldSet
## 
######################################################################

class FieldSet(Field):
    """Although a fieldset is not the same as a field,
    it's an easy grouping of functions. Easiest to use
    would be if you could use a fieldset as a field.
    Fieldset should be quite easily converted to a comound field
    structure though.
    """
    def __init__(self,name,fields, label=None):
        "Enter a name, a list of fields, and an optional label."
        # for a compound field, you should initialise the
        # Field.__init__of course..
        self.name = name
        self.fields = fields
        self.label = label

    def validate(self,form):
        for field in self.fields:
            if not field.validate(form):
                return False
        return True

    def build(self,kwp,readonly=False):
        yield '<fieldset>'
        if self.label:
            yield '<legend>%s</legend>' % self.label
        if kwp and not self.validate(kwp):
            yield self.errorMsg(kwp)
        for field in self.fields:
            yield field.build(kwp,readonly)
        yield '</fieldset>'

    def pyValue(self,form):
        "returns a dictionary, like given to a form.onExit method..."
        return dict([(field.name[len(self.name)+1:], # strip the compundname. part
                      field.pyValue(form)) 
                     for field in self.fields])

    def errorMsg(self,form):
        # a fieldset can't have an error.. fields will have that..
        return ''

######################################################################
## 
## CompoundField Base
## 
######################################################################
class CompoundField(FieldSet):
    """Although a fieldset is not the same as a field,
    it's an easy grouping of functions. Easiest to use
    would be if you could use a fieldset as a field.
    Fieldset should be quite easily converted to a comound field
    structure though.
    """
    def __init__(self,name,fields, label=None):
        "Enter a name, a list of fields, and an optional label."
        super(CompoundField,self).__init__(name,fields,label)
        # for a compound field, you should initialise the
        # Field.__init__of course..
        self.name = name
        self.fields = fields
        self.label = label
        # make the fields children of this compund
        for field in fields:
            field.name= name+'.'+field.name
            if hasattr(field,'id'):
                field.id= name+'.'+field.id
            else:
                field.id = 'input'+name+'.'+field.name

class DateField(CompoundField):
    def __init__(self,name, label=None):
        "Enter a name, a list of fields, and an optional label."
        self.day = IntField("day",'Day')
        self.month = IntField("month",'Month')
        self.year = IntField("year",'Year')
        super(DateField,self).__init__(name,[self.day, self.month, self.year],label)

    def validate(self,kwp):
        "validates the date, using time module"
        try:
            self.pyValue(kwp)
        except:
            return False
        return True

    def errorMsg(self,kwp):
        try:
            self.pyValue(kwp)
        except Exception, e:
            return str(e)
        return ''
    
    def pyValue(self,kwp):
        vals = super(DateField,self).pyValue(kwp)
        import datetime
        return datetime.date(**vals)
        
        
######################################################################
## 
## Form Base class
## 
######################################################################

class Form(object):
    """A form is a cherrypy page...
    it has the following states:
        X. ...nothingness...
        A. New Entry
        B. Users Enters Data
        C. Validate Entered Data
        D. Getting Confirmation From User
        E. ReEntry Filled With Entered Values
        F. ReEntry Filled With Entered Values and error message
        G. Entry Completed
    Transitions: (obvious activity between () )

        X --> A : born (form is setup, run only once!!)

        A --> B : (html is brewn) show form on screen

        B --> C : users posts results 

        C --> D : input is valid, but a user confirmation was set to be asked, 
                  (brew confirmation html)

        C --> G : input is valid, but no user confirmation was set to be asked,

        C --> F : input is not valid
                  (brew html with data and error msgs)

        F --> B : user posts new results 

        E --> B : user posts new results 

        G --> X : (fire another (external) method to build new screen)

    The form entry should all be done using 1 url, and preferable no hidden
    form inputs to differentiate the states.. Otherwise it would be to easy
    to hack those values.. So keeping the state purely serverside (and there-
    for also not using different urls for the different states) allows for
    less hackable data entry.

    The concept used to solve this, is to change the check the session for
    the state for this form, and switch to the right function accordingly.
    """

    def __init__(self,
                 name,    # form name
                 onExit,  # onExit method, will be called with a dictionary
                          # where key,value = key of the fields, pyValue of the
                          # form fields.
                 fields,  # list of fields (order, _is_ important)
                 confirm, # user should confirm after good entry, field type
                          # with the question
                 submit = None, # optional submit input type (can be a combined)
                          # will be left out in readonly data 
                 invalidForm = None, # specify to overwrite self.invalidForm
                 encoding = 'application/x-www-form-urlencoded' # form encoding,
                          # to support files etc...
                          # see http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.3
                 ):
        """
         name,    # form name
         onExit,  # onExit method, will be called with a dictionary
                  # where key,value = key of the fields, pyValue of the
                  # form fields.
         fields,  # list of fields (order, _is_ important)
         confirm, # user should confirm after good entry, field type
                  # with the question
         submit = None, # optional submit input type (can be a combined)
     &