Getting input from a user¶
User input is a tricky thing. Users always provide input as strings, but programs work in terms of objects such as integers, boolean values, dates, etc. Part of dealing with user input thus means translating (or marshalling) such a string to the actual Python object it represents. That’s not all though – user input also need to be validated, and appropriate error messages given to guide a user as to what the program considers valid input.
These are considerable tasks for a framework to deal with.
User input in Reahl¶
In order to get input from a user, Reahl uses special
Widgets, called
Inputs. The responsibility of an
Input is to show a user the value of some item
in your program, and allow the user to change that value. There are
different kinds of Inputs representing
different ways of dealing with the visual and behavioural aspects of
this task.
Another player, the Field, has
the job of checking whether a string sent by a user is valid, to turn
that string into Python object, and to finally set such a Python
object as the value of an attribute of one of your model objects
One thing about Inputs: they differ from
other Widgets in that they have to live as
children of a Form.
Here is a what we need in the address book application:
A TextInput linked to the email_address attribute of an Address, via an EmailField
Reahl models use makeup¶
The first step towards allowing a user to input anything, is to
augment the model with Fields that represent each attribute accessible from the user interface of
the application. In our example, the name and email_address attributes of
an Address are exposed to the user.
To augment our Address class with Fields, create a special method fields() on the class, and annotate it with the @exposed decorator. Such a method should take one argument: fields on which you can set each Field needed. Take care though – each Field you create will eventually manipulate an attribute of the same name on instances of your class:
class Address(Base):
__tablename__ = 'addressbook2_address'
id = Column(Integer, primary_key=True)
email_address = Column(UnicodeText)
name = Column(UnicodeText)
@exposed
def fields(self, fields):
fields.name = Field(label='Name', required=True)
fields.email_address = EmailField(label='Email', required=True)
The @exposed decorator turns your fields() method into a property named fields on instances of this class. The property is special only in that it is initialised by the method you provide.
The .fields attribute of an Address instance now contains a
Field for each corresponding
attribute on that Address which can be accessed via a user
interface. We will need it in a moment when we start creating
Inputs.
Note
Fields vs Fields
One thing that may be confusing is that Elixir Fields are added to
Address, but Reahl Fields are added as well.
You have to keep in mind that Elixir has the job of persisting data in a database. The Elixir Field for email_address specifies that the email_address attribute of an Address object will be saved to a database column that can deal with unicode text.
The Reahl Field added for email_address is not concerned with
persistence at all. It specifies several bits of useful
metainformation about the email_address attribute of an Address
object – information that can be used to govern interaction with
users.
Reahl Fields could happily describe an attribute which does not get
persisted at all. Similarly, an Elixir Field could happily
describe an attribute that is not exposed to a user interface.
Fields provide information about attributes¶
The extra information provided by Fields is useful in other
contexts. Take the label that is specified everywhere, for
example. This is what a user may call the Field in natural
language – quite a useful bit of information when you want to create a
user interface referring to the Field.
The required=True keyword argument can be passed to a Field to say
that this information normally has to be provided as part of input.
(What good is an Address with only a name, or only an
email_address?)
Notice also that email_address is an EmailField. A valid email
address has a specific form. The string ‘john’ is not a valid email
address, but 'johndoe@world.org‘ is. Because email_address was
specified as an EmailField, user input to email_address can now be
validated automatically to make sure only valid input ever makes it into the model.
Adding the actual Widgets¶
You should have gathered by now that we are going to have to add a
Form so that we can also add
TextInputs for each of the
Fields we are
exposing. That’s not the entire story though: we want it to look nice
too – with a label next to each TextInput, and
successive labels and TextInputs neatly
aligned underneath each other. It would also be visually pleasing if
we add a heading to this section of our page.
Two elements come to our aid in this regard: An
InputGroup is a Widget
that groups such a section together, and give the section a heading.
A LabelledBlockInput is a
Widget that wraps around another
Input (such as a
TextInput), and provides it with a
label. Successive LabelledBlockInputs will
arrange themselves neatly below each other.
What’s needed thus, is to create a Form,
containing an InputGroup, to which is added two
LabelledBlockInputs, each wrapped around a
TextInput that is linked to the appropriate
Field:
class AddressBookPanel(Panel):
def __init__(self, view):
super(AddressBookPanel, self).__init__(view)
self.add_child(H(view, 1, text='Addresses'))
for address in Session.query(Address).all():
self.add_child(AddressBox(view, address))
self.add_child(AddAddressForm(view))
class AddAddressForm(Form):
def __init__(self, view):
super(AddAddressForm, self).__init__(view, 'add_form')
new_address = Address()
grouped_inputs = self.add_child(InputGroup(view, label_text='Add an address'))
grouped_inputs.add_child( LabelledBlockInput(TextInput(self, new_address.fields.name)) )
grouped_inputs.add_child( LabelledBlockInput(TextInput(self, new_address.fields.email_address)) )
Let’s finish the example in the next section.