Nicer Package Manager

    cerebral-module-ui-driver

    0.10.2 • Public • Published

    cerebral-module-ui-driver

    cerebral-module-ui-driver is the glue that connects your cerebral immutable data to any jsx style UI library including react, snabbdom and others. It automates signals, type casting and async validation to simplify and reduce boilerplate code in your UI components and keep your UI layer pure.

    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 because 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.

    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 typing to do. What if instead of manually hooking up the properties and events we could just do the following:

    <Select {...bind.select('name', { options })}/>

    This is cerebreal-module-ui-driver. All background event handling is built-in as well as type casting, field and form level validation.

    Install

    npm install cerebral-module-ui-driver
    

    Usage

    The ui-driver assumes that each form in your application will be placed in its own module. This is not a bad assumption as this will encourage modular and well structured cerebral applications.

    From your main.js

    // your cerebral controller
    import controller from './controller'
     
    import driver from 'cerebral-module-ui-driver/module'
    import auth from './modules/auth'
     
    // configure modules
    controller.addModules({
      driver: driver({
        // driver options go here
      }, {
        // optional props maps here
      }),
      auth
    })

    In your form module you need to define your form fields and specify optional validation. All validation methods are async and need to call done([errorMessageString]) when complete. ui-driver will debounce validation calls by default, but will ensure that the final validation check goes through before allowing the form to be submitted.

    import signinSubmitted from './chains/signinSubmitted'
     
    export default (module) => {
      module.addState({
        username: '',
        password: ''
      })
     
      // register module signals
      module.addSignals({
        signinSubmitted
      })
     
      // define the form
      const form = {
        fields: {
          username: {
            type: 'string', // supported types are string, int, float, date and time
            validate ({ value, done }) { //optional
              // called if type casting is successful
              done(value.length > 0 ? '' : 'username is required')
            }
          },
          password: {
            type: 'string',
            validate ({ value, done }) { // optional
              // called if type casting is successful
              done(value.length > 0 ? '' : 'password is required')
            }
          }
        },
        validate (values, done) { // optional
          // called if all individual fields are valid
          done()
        },
        onAfterValidate (args) { // optional
          // args are the same as any sync action method (state is writeable) with the
          // following additions: fields, isValid, isFormValidation, isFieldValidation
          //
          // Since validation functions are async and do not have access to set state,
          // this method can be used to update interdependent fields when their values
          // change
        }
      }
     
      // return the module meta
      return { form }
    }

    In your form ui component

    import { Component } from 'cerebral-view-snabbdom'
    import { Input, Form } from 'snabbdom-material'
    import driver from 'cerebral-module-ui-driver'
     
    export default Component({
      driver: driver.state({ // the state computes to get driver and form data
        driver: 'driver',    // optional driver module name, can be omitted it's called 'driver'
        form: 'form'         // form module name, for nested modules use dot notation
      })
    }, ({
      state,
      modules,
      signals
    }) => {
     
      // setup the ui driver bindings
      const bind = driver.bind({ modules, state: state.driver })
     
      return (
        <Form {...bind.form(signals.auth.signinSubmitted)}>
          <Input {...bind.input('username', { label: 'Username' })}/>
          <Input {...bind.input('password', { label: 'Password', type: 'password' })}/>
          <button type='submit'>Signin</button>
        </Form>
      )
    })

    The ui-driver also provides actions that you can use in your signal chains to validate submitted forms and to clear the driver data after the form editing has completed.

    import signin from '../actions/signin'
    import showErrorMessage from '../actions/showErrorMessage'
    import validate from 'cerebral-module-ui-driver/chains/validate'
    import reset from 'cerebral-module-ui-driver/actions/reset'
     
    export default [
      ...validate, { // validate the auth form
        success: [
          [signin, {
            success: [
              reset // reset the driver state for the auth form
            ],
            error: [
              showErrorMessage
            ]
          }]
        ],
        error: [
          showErrorMessage
        ]
      }
    ]

    Supported Bindings

    ui-driver supports the following bindings (props are optional for all bindings):

    Checkbox

    Field value must be a bool

    <input {..bind.checkbox('fieldName', props)/>

    Form

    The form binding will prepare all the necessary data required for form level validation and pass it to the given formSubmittedSignal. This signal must apply the provided validateForm chain (see the example above).

    <form {...bind.form(formSubmittedSignal, props)}></form>

    Input

    Field value will be cast according to the type defined in the module

    <input {...bind.input('fieldName', props)}/>

    Menu

    Menu consists of two bindings, one for the element that will open the menu (eg button) and one for the menu element itself.

    <button {..bind.menuOpen('menuName', props)}>Open Menu</button>
    <Menu {...bind.menu('menuName', props)}></Menu>

    Select

    Field can be of any type but the selected value in the options collection must === the field value.

    <Select {...bind.select('fieldName', props)}/>

    Configuration

    Prop maps

    ui driver uses prop maps to allow each binding type to output different props depending on the ui library being used.

    These are the default settings: base applies to all unless overridden.

    const propsMaps = {
      base: { // applies to all bindings unless overridden.
        value: 'value',
        onChange: 'onChange',
        isValidating: 'isValidating',
        isError: 'isError',
        message: 'message',
        type: 'type',
        isOpen: 'isOpen',
        onOpen: 'onOpen',
        onClose: 'onClose',
        isFocused: 'isFocused',
        onFocus: 'onFocus',
        onBlur: 'onBlur'
      },
      form: { // additional props only used by form
        onSubmit: 'onSubmit'
      },
      menuOpen: { // remap onOpen to onClick for menuOpen binding
        onOpen: 'onClick'
      }
    }
     
    const modules = {
      driver: driver({
        // other driver options go here
      }, propsMaps),
      auth
    }

    General settings

    Here you can see the general configuration options with their default values:

    const modules = {
      driver: driver({
        dateFormat: 'L', // see moment.js
        timeFormat: 'H:mm', // see moment.js
        invalidDateMessage: 'invalid date',
        invalidNumberMessage: 'invalid number',
        invalidTimeMessage: 'invalid time',
        invalidMessage: 'form has validation errors'
      }),
      auth
    }

    Contribute

    Fork repo

    • npm install
    • npm start runs dev mode which watches for changes and auto lints, tests and builds
    • npm test runs the tests
    • npm run lint lints the code
    • npm run build compiles es6 to es5

    Install

    npm i cerebral-module-ui-driver

    DownloadsWeekly Downloads

    6

    Version

    0.10.2

    License

    MIT

    Last publish

    Collaborators

    • garthw