ui-driver
The ui-driver is helper that simplifies the connecting of material-components (React form components) or snabbdom-material (snabbdom form components) to cerebral. It automates signals, validation, i18n and more to simplify and reduce repetative code in React and snabbdom form components.
Overview
When the user interface is pure and all app state is managed centrally, hooking up all data and events between the user interface components and controller can be a tedious task. Take the example of a pure select component that renders labels and error messages.
<Select label="Options" value=selectedValue options=options isError=isError message="Please select" isOpen=isSelectOpen onOpen=setOpenState onChange=optionSelected onClose=setClosedState/>
Whist not complicated, we need to hookup the selected value, list items and onChange events. But becuase this Select control does a little more we also need to hookup the label, error status and message. Finally, since this is a pure component, we also need to pass the isOpen state and handle the onOpen and onClose events which toggle the isOpen state.
What you also don't see is the work that each event handler must do, which can ammount to 2 or 3 times as much code again. And for some controlls where we need to do validation, such as email inputs or password complixity checks, this can add up to much more.
Imagine now that we have a form with 10 or even 20 of these components. Together with other markup and event handling we have a lot of repetative typing to do. What if instead of manually hooking up the properties and events we could just do the following:
<Select ...bindings/>
This is the ui-driver. All background event handling is built-in as well as field and form level validation.
Example
Let's take the example of a sign-in form.
// signin component ;;;;; // create an instance of the form driver that is bound to the /signin object// in the state treeconst formDriver = driver; // the form driver will generate the neccessary cerebral properties that it// needs@ { const locale signals } = thisprops; // This is an optional translation library, without this the field labels // and error messages can be defined directly on each binding. // We use messageformat (https://github.com/SlexAxton/messageformat.js), but // any object t that has function properties that return a string should // work (eg t.emailLabel() => 'Email') const t = ; // create the bindings by passing the current state, signals and optional t // to the form driver const bindings = formDriver; // create the form, notice the formDriver.getValidationData() that is // passed to the onSubmit signal, this will gather all form data and pass // it to the ui-driver actions for validaton purposes return <Form style= marginTop: '30px' onSubmit= signals > <Input ...bindings/> <Input ...bindings/> <Button type="submit">t</Button> </Form> ; }
The ui-driver also provides two actions that you can use in your signals to validate submitted forms and to clear the driver data after the form editing has completed.
// signin signal ;;;;; controller;
Setup
one time
The ui-driver has some internal signals that must be registered with your cerebral controller.
;; ;
per form
// static for the formconst formDriver = driver;
The state path passed to form is where all form field values will be stored by name.
// component definition (react)@ // ... // component definition (snabbdom)formDriver state signals // ...;
// at the start of the form renderconst bindings = formDriver;
Supported Bindings
ui-driver currently supports the following bindings:
Checkbox
Field value must be a bool
Date
Field must be a date
Field must be a string
Equals
Field must be a string, field must === comparisonValue to validate
Input
Field must be a string
Int
Field must be an int
Menu
Menu consists of two bindings, one for the element that will open the menu (eg button) and one for the menu element itself.
Password
Field must be a string
Select
Field can be of any type but the selected value in the options collection must === the field value
options = value: 1 label: t'oneLabel' ;
Time
Field must be an int which represents minutes from start of day
Side Effects
Sometimes changing one form field has side effects on other parts of the form. With ui-driver this can be handled by SideEffects.
// register a side affects handler for a specific form and field; driver;
Contribute
Fork repo
npm install
npm run dev
runs dev mode which watches for changes and auto lints, tests and buildsnpm test
runs the testsnpm run lint
lints the codenpm run build
compiles es6 to es5