Wondering what’s next for npm?Check out our public roadmap! »

    form-elements

    2.3.3 • Public • Published

    form-elements

    CircleCI

    A collection of form elements.

    Usage

    const els = require('form-elements')
    const html = require('nanohtml')
     
    const scratch = {
      test: '',
      test2: '',
      pushed: 0
    }
     
    const errOpts = {
      classes: ['error-note'],
      animate: true,
      hiddenState: {
        height: function () {
          let height = this.$errorContainer.clientHeight
          if (this.$errorContainer.children.length === 0) {
            height = '0'
          }
          return `${height}px`
        },
        overflow: 'hidden',
        transition: 'height 0.8s'
      },
      visibleState: {
        height: function () {
          let height = this.$errorContainer.clientHeight
          if (this.$errorContainer.children.length === 0) {
            height = '0'
          }
          return `${height}px`
        }
      }
    }
     
    function main (state, emit) {
      const formErrors = els.error(errOpts)
     
      const inputOpts = {
        classes: [],
        validate: true,
        errorDisplay: formErrors
      }
     
      const input2Opts = {
        classes: [],
        required: true,
        validate: true,
        errorDisplay: formErrors
      }
     
      const $input = els.labeledInput('test email', 'email', oninput, scratch.test, inputOpts)
      const $input2 = els.labeledInput('test required', 'text', oninput2, scratch.test2, input2Opts)
     
      return html`<div class="">
        <div class="">
          ${formErrors.render()}<br>
          <b>Button pushed:</b> ${scratch.pushed}<br>
          <b>Input value:</b> ${scratch.test}<br>
          ${$input}<br>
          ${$input2}<br>
          ${els.button('i am a button', (evt) => ++scratch.pushed && emit('render'))}
        </div>
      </div>`
     
      function oninput (evt) {
        scratch.test = evt.currentTarget.value
      }
     
      function oninput2 (evt) {
        scratch.test2 = evt.currentTarget.value
      }
    }

    Results in:

    <form>
      <div></div>
      <label>Email<br><input type="email" value=""></label>
      <button>submit!</button>
    </form>

    In this example, the <input type='email'> field will be validated using the built-in browser's validation framework for email addresses. When the user blurs from the field, it'll attempt to validate the data inside, and if it isn't valid, it'll display the error in the <div> located at the top of the form.

    Options

    elementOptions:object(key:string,value:any)

    All the elements accept an elementOptions hash as the final argument which controls any additional element attributes you may wish to set, in addition to the following:

    • classes:array(string) - an array of class names to apply, in addition to the default ones.
    • style:string - a string containing inline style information

    If you wish to override all the classes attached to the input, you can do so by providing the class key on this options list.

    Event handlers should be provided using the on[event] key, e.g. oninput or onblur.

    Each element type will have specific attributes that can be set in addition to the default attributes provided by the DOM spec.

    errorOptions:object(key:string,value:any)

    This is a superset of elementOptions containing the following extra values:

    • animate:boolean: whether or not it should attach style information for CSS animations to show/hide the error element
    • visibleState:object(key:string,value:string|function): what styles to apply to the object when it's visible
    • hiddenState:object(key:string,value:string|function): what styles to apply to the object when it's visible

    The valid keys for visibleState and hiddenState are all valid HTML Style rules. You can either set them to a string or a function which returns a sting and runs in the context of the Error element.

    {
      animate: true,
      hiddenState: {
        opacity: 0,
        transition: 'opacity 0.8s ease-in'
      },
      visibleState: {
        opacity: 1,
        height: function () {
          const height = this.$el.clientHeight + 15
          return `${height}px`
        }
      }
    }

    The initial state of the object is hiddenState -- these rules will supercede any styles or classes on the object. When errors are presented to the user, it will apply the styles found in visibleState. These will be applyed everytime a new error is presented, allowing you to grow/shrink or otherwise alter the box. When all of the errors are gone, it will apply the hiddenState styles again.

    API

    error(opts:errorOptions):ErrorDisplay

    Create a new error display object

    ErrorDisplay:

    • #render():HTMLDivElement - return a <div> element, using the opts provided by the constructor
    • #displayError(key:string, text:string):undefined - Add a new error to the display
    • #removeError(key:string):undefined - Remove an error from the display
    • #clear():undefined - Remove all errors

    Elements

    input(label:string, type:string, inputHandler:function(evt:HTMLInputEvent, value:(string|number), opts:elementOptions):HTMLInputElement

    Create a form input with various options. opts accepts any of the HTMLInputElement attributes, the usual default attributes, in addition to several custom fields:

    • validate:boolean - should validation be attempted when the blur event has been fired
    • validator:function($el:HTMLInputElement):boolean - a custom validation method that returns true/false. If you need to set a custom error message, you should use $el.setCustomValidity, but don't forget to set to an empty string when the error has been resolved!
    • errorDisplay:ErrorElement - the error element that validation errors should be placed into. Must match the API provided by the included error object
    <input type=[type] value=[value] oninput=[inputHandler]>

    button(text:string, clickHandler:function(evt:HTMLClickEvent), opts:elementOptions):HTMLButtonElement

    Create a button with a click handler.

    <button onclick=[clickHandler]>[text]</button>

    label(text:string, opts:elementOptions):HTMLLabellement

    Create a label

    <label>[text]</label>

    labeledInput(label:string, type:string, inputHandler:function(evt:HTMLInputEvent, value:(string|number), labelOpts:elementOptions, inputOpts:elementOptions)

    Create a form input element wrapped by a label

    <label>[text]<br><input type=[type] value=[value] oninput=[inputHandler]></label>

    License

    Copyright © 2018 Scripto, LLC. Licensed under Apache-2.0

    Install

    npm i form-elements

    DownloadsWeekly Downloads

    40

    Version

    2.3.3

    License

    Apache-2.0

    Unpacked Size

    30.1 kB

    Total Files

    23

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar