aca-form-generator

aca-form-generator

You can find a succint storybook detailing main components props and events :
https://aca-form-generator.netlify.com/storybook/

FormGenerator

What is it

FormGenerator is a component used to display a form, without styling.

What it does

It takes a JSON object describing the form and data. It handles user inputs. It returns validation errors.

What it doesn't do

It doesn't handle sending to the form to any backend. It doesn't handle step navigation.

Installation

npm install aca-form-generator

Usage

import { FormGenerator } from 'aca-form-generator'

<script>
export default {
    components: {
        FormGenerator,
    },

    data() {
        return {
            errors: {},
            visibleErrors: {},
            schema: {},
            model: {},
        }
    }
}
</script>
<template>
    <FormGenerator
        :schema="schema"
        :model="model"
        :errors="errors"
        :visibleErrors="visibleErrors"
        @fieldChange="({ field, value }) => this.model = Object.assign({}, this.model, { [field.model]: value })"
        @errorsChange="({ errors }) => (this.errors = errors)"
    >
    </FormGenerator>
</template>

Props

schema : required
Literal object describing the form.

{
    fields: [
        {
            type: 'input',
            model: 'username'
        }, 
        // ...
    ]
}

You can find more example of common fields in this file :
https://github.com/Acadomia/aca-form-generator/blob/master/src/stepsSkeletonExample.js

model
Literal object representing the data displayed in the different fields :

{
    username: 'my-username'
}

errors
Literal object representing the errors :

{
    username: ['this field is required.']
}

visibleErrors
Literal object representing the errors displayed :

{
    username: true
}

Events

fieldChange
Emitted when the user is typing in an input for example.
Parent component is responsible for updating the model prop accordingly :

<FormGenerator
    :model="this.model"
    @fieldChange="({ field, value }) => this.model = Object.assign({}, this.model, { [field.model]: value })"
    <!-- ... -->

errorsChange
Emitted when a field validations messages change.
Parent component can listen to the event to disabled "submit" button for example :

<FormGenerator
    @errorsChange="({ errors }) => this.errors = errors"
    <!-- ... -->

<button 
    :disabled="errors.length" 
    <!-- ... -->

fieldFocus
Emitted when a field gains focus.

<FormGenerator
    @fieldFocus="({ field }) => ..."
    <!-- ... -->

fieldBlur
Emitted when a field loses focus.
Useful to manipulate visibleErrors.

<FormGenerator
    @fieldBlur="({ field }) => ..."
    <!-- ... -->

Accepted fields

For the moment FormGenerator can only render these fields:

• checklist
• select
• checkbox
• radio
• input
• numeric-input
• textarea
• zipcode
• upload
• html

New fields can easily be added to FormGenerator.vue
Every field must have at least a field props, describing the field,
And a value prop describing its value.
It must emit an event valueChange when the value changes.

Custom fields

Each field is wrapped in a slot.
So you can easily create a custom field, or change an existing field behaviour.

<FormGenerator
    :schema="{ field: [ { type: 'myCustomField', ... }, ... ] }"
    ...
>
    <template #myCustomField="{ field, value }">
        <!-- create your field here using {{ field }} and {{ value }} variables-->
    </template>
</FormGenerator>

Validation

Validation is done when the model changes by calling the validators functions defined in each schema.fields[].validators

Validators

Validators are defined in this file :
https://github.com/Acadomia/aca-form-generator/blob/master/src/fieldValidators.js Each validator is a function retuning undefined when the field value is valid.
Or an array of error messages when something is invalid.
The validator function takes 3 arguments:

• field the field whe want to validate
• model all the values for the given form
• messages a facultative object with the translated error messages.

Usage

import { fieldValidators } from 'aca-form-generator'

A minimal validator could look like this :

checked(field, model) {
    if (!model[field.model]) {
        return ['This checkbox must be checked']
    }
},

A more complete example would be:

checked(field, model, messages) {
    if (!model[field.model]) {
        return [messages.mustBeChecked]
    }
},

You can transate or customize the error messages using the function withMessages.

fieldValidators.checked.withMessages({
    mustBeChecked: 'Ce champ doit être coché.'
})

Custom error

Using the scopped slot errors you can customize validation errors.

<FormGenerator
    ...
>
    <template #errors="{ field, errors }">
        <!-- Display errors here, the way you want. -->
    </template>
</FormGenerator>

Steps

Just like validators, to keep the code reusable, step logic is not coupled to the component FormGenerator

The mixin stepMixin.js is here to help you handle multi step forms.
You can find an example of how to use all these elements together to make a multistep form generated with a JSON comming from an API here :
https://github.com/Acadomia/aca-form-generator/blob/master/src/screens/ExampleScreen.vue

You can also find the code of the mixin here :
https://github.com/Acadomia/aca-form-generator/blob/master/src/stepsMixin.js

Usage

import { stepsMixin } from 'aca-form-generator'