Input fields for Flutter standalone or within a form

flutter input fields

this package provides input widgets (fields) to manipulate data. the data to manipulate is either a single variable or an entry in a map. the map can even be nested. parameter path defines the key to access the entry in the map. to access an entry in a nested map, the keys must be separated by a single slash (/) character.

all input widgets share a common set of parameters and methods. a list of validators can be attached to each input widget.

each input widget can be used standalone. if it finds a inputform ancestor then it will automatically register itself to the form. the form provides methods to enable(), reset(), save() or validate() all fields at once.

input widgets

the following input widgets are available.
see section development below for building your own input widget.

• inputcheckbox – checkbox for data type bool
• inputcountry – dropdown to select a country (shows flags)
• inputdate – calendar based selection for data type datetime (date part only)
• inputdatepicker – a highly customizable date picker with week of year and multiple swipe actions
• inputdatetime – wheels for data type datetime can be customized for date only, time only or both
• inputdropdown<t> – dropdown button for data type t
• inputfavorite – a favorite button with selectable icon for data type bool
• inputkeyboard – text input for data type string, int or double
• inputlanguage – dropdown to select a language (locale)
• inputpassword – text field with a switch to make obscured input visible (string)
• inputradio<t> – radio button to select one value of type t
• inputrating – rating widget with selectable icons and a range slider for data type int
• inputslider – slider for data type double between a minimum and maximum value
• inputspinner – spinner with buttons for data type double to decrease or increase a value
  between a minimum and maximum
• inputswitch – switch for data type bool

common parameters

all input widgets share a common set of parameters.
all parameters are named and optional.

• key key – identifier for the field
• bool autosave = true – automatically saves any changed value.
  if autovalidate is true then the value will only be changed
  when there are no validation failures.
• bool autovalidate = false – automatically validates changed values
• inputdecoration decoration – e.g. for a label (see example)
• bool enabled – to enable or disable user input.
  if not set then uses setting from inputform
  or defaults to true (if there is no form).
• t initialvalue – sets the fields initial value.
  overrides using the value from map.
• valuesetter<t> onchanged – invoked on every change
  of the input field value
• valuesetter<t> onsaved – invoked by save() which
  will be automatically called by inputform.save().
• string path – to access the value in map
• list<inputvalidator> validators – list of validators

validators

the following validators can be given to parameter validators
of an input widget. each validator accepts the optional parameter
message to set an individual error message if the validation fails.

• after(datetime date) – validates that the field value
  is after date
• before(datetime date) – validates that the field value
  is before date
• future – validates that the datetime field value
  lies in the future
• max(num maxval) – validates that the num field value
  is not larger than maxval
• maxlen(num maxlen) – validates that the length of the string
  field value is not longer than maxlen
• min(num minval) – validates that the num field value
  is not smaller than minval
• minlen(num minlen) – validates that the length of the string
  field value is not shorter than minlen
• notnull – validates the the field value is not empty
• past – validates that the datetime field value
  lies in the past

usage

each input widget will automatically register itself if it
finds an inputform ancestor.
otherwise it will just run standalone.
it will use initialvalue for its value to display.
if initialvalue is null then it will use the value from
map[path] if both are set.
if map is not set, then the field will use map from
an inputform ancestor (if there is any).

saving a modified value will happen

• on any change if autosave = true (which is the default)
• when save() is called
• when save() is called on the inputformstate

the changed value will be written to the map at path
if both were supplied. also method onsave() will be invoked
with the changed value.

demo

for a complete example see example/main.dart.

inputdatepicker

the highly customizable inputdatepicker allows you to choose a date
from a calendar page which also shows the week of the year.
it provides spinners, swipes and a dropdown to select the month.
the year can even be entered as text.
all parts can be customized by datepickerstyles.

development

to create a new input field for data type t follow these steps:

1. copy one of the included class files.
2. rename the class widget and its state to your new one.
3. replace t with the value type of your new input field.
4. adapt parameters and leave the call to super() with
   all the common parameters.
5. adapt method build( buildcontext context) in the state class.
   it must end with return super.buildinputfield( context, ... where
   ... is the code to display your new field widget.

utilities

this package also contains some utilities.

• inpututils.converttotype() converts a value to a given target type.
• inpututils.readfromjson() reads a value from a nested map.
• inpututils.writetojson() writes a value into a nested map.
• see date_helper.dart for extensions on datetime
  for weekofyear, julianday and more.

to do

• [x] create a customizable calendar picker with week numbers
• [x] create a text input field for int and double
• [ ] create an input widget for a calendar with events
• [ ] create an input widget to select multiple choices like a
  multi-select list
• [ ] add some images to this documentation
• [x] internationalize the whole package
• [x] create an input widget to change the language within the app