@v4fire/client

# form/b-form This module provides a component to create a form to group other form components and submit to a data provider. The component is based on a native `<form>` element and realizes the same behavior as the native API does. ## Synopsis * The component extends [[iData]]. * The component implements the [[iVisible]] trait. * The component is used as functional if there is no provided the `dataProvider` prop. * By default, the root tag of the component is `<form>`. ## Modifiers | Name | Description | Values | Default | |---------|------------------------------------------------------|-----------|---------| | `valid` | All associated components have passed the validation | `boolean` | - | Also, you can see the [[iVisible]] trait and the [[iData]] component. ## Events | Name | Description | Payload description | Payload | |---------------------|------------------------------------------------------------------------------------------------------------|------------------------------------------|-------------------------------------------------| | `clear` | All associated components have been cleared via `clear` | - | - | | `reset` | All associated components have been reset via `reset` | - | - | | `validationStart` | Validation of the associated components has been started | - | - | | `validationSuccess` | Validation of the associated components has been successfully finished, i.e., all components are valid | - | - | | `validationFail` | Validation of the associated components hasn't been successfully finished, i.e, some component isn't valid | Failed validation | `ValidationError<this['FormValue']>` | | `validationEnd` | Validation of the associated components has been ended | Validation result \[, Failed validation] | `boolean`, `ValidationError<this['FormValue']>` | | `submitStart` | The component started to submit data | Data to submit, Submit context | `SubmitBody`, `SubmitCtx` | | `submitSuccess` | Submission of the form has been successfully finished | Operation response, Submit context | `unknown`, `ValidationError<this['FormValue']>` | | `submitFail` | Submission of the form hasn't been successfully finished | Error object, Submit context | `Error │ RequestError`, `SubmitCtx` | | `submitEnd` | Submission of the form has been ended | Operation result, Submit context | `SubmitResult`, `SubmitCtx` | Also, you can see the [[iVisible]] trait and the [[iData]] component. ## Why another component? * The native form API is based on simple URL-s and HTTP methods, but it's a low-level approach. Opposite, `bForm` uses data providers to submit data. * `<form>` works with tags; `bForm` works with `iInput/bButton` components. * To validate data, `iInput` components don't use the native API of form validation, so the simple `<form>` element can't work with it. * `bForm` provides a bunch of events and modifiers to manage the submit process more efficiently. ## Usage ### Simple usage ``` /// The form data is provided to the `User` data provider via the `add` method < b-form :dataProvider = 'User' | :method = 'add' < b-input :name = 'fname' | :validators = ['required'] < b-input :name = 'lname' < b-input :name = 'bd' | :type = 'date' < b-button :type = 'submit' /// Association of the form and components by id < b-form :dataProvider = 'User' | :method = 'upd' | :id = 'upd-user-form' < b-input :name = 'fname' | :form = 'upd-user-form' < b-button :type = 'submit' | :form = 'upd-user-form' ``` ### Providing an action URL ``` /// This kind of API is closer to the native. /// The form data is provided to the common data provider by the specified URL and via the `add` method. < b-form :action = '/create-user' | :method = 'add' < b-input :name = 'fname' | :validators = ['required'] < b-input :name = 'lname' < b-input :name = 'bd' | :type = 'date' < b-button :type = 'submit' ``` ### Providing additional request parameters ``` < b-form :action = '/create-user' | :method = 'add' | :params = {headers: {'x-foo': 'bla'}} < b-input :name = 'fname' | :validators = ['required'] < b-input :name = 'lname' < b-input :name = 'bd' | :type = 'date' < b-button :type = 'submit' ``` ### Providing an action function ``` /// We are delegate the submission of data to another function < b-form :action = createUser < b-input :name = 'fname' | :validators = ['required'] < b-input :name = 'lname' < b-input :name = 'bd' | :type = 'date' < b-button :type = 'submit' ``` ## Slots The component supports the `default` slot to provide associated components. ``` < b-form :dataProvider = 'User' < b-input :name = 'fname' < b-button :type = 'submit' ``` ## API Also, you can see the implemented traits or the parent component. ### Props #### [id] A form identifier. You can use it to connect the form with components that lay "outside" from the form body (by using the `form` attribute). ``` < b-form :id = 'bla' < b-input :form = 'bla' ``` #### [name] A form name. You can use it to find the form element via `document.forms`. ``` < b-form :name = 'bla' ``` ```js console.log(document.forms['bla']); ``` #### [action] A form action URL (the URL where the data will be sent) or a function to create action. If the value is not specified, the component will use the default URL-s from the data provider. ``` < b-form :action = '/create-user' < b-form :action = createUser ``` #### [method = `'post'`] A data provider method which is invoked on the form submit. ``` < b-form :dataProvider = 'User' | :method = 'upd' ``` #### [paramsProp] Additional form request parameters. ``` < b-form :params = {headers: {'x-foo': 'bla'}} ``` #### [cache = `false`] If true, then form elements is cached. The caching is mean that if some component value does not change since the last sending of the form, it won't be sent again. ``` < b-form :dataProvider = 'User' | :method = 'upd' | :cache = true < b-input :name = 'fname' < b-input :name = 'lname' < b-input :name = 'bd' | :cache = false < b-button :type = 'submit' ``` ### Fields #### params Additional form request parameters. ### Getters #### elements A list of components that are associated with the form. #### submits A list of components to submit that are associated with the form. ### Methods #### clear Clears all values of associated components. #### reset Resets values to defaults of all associated components. #### validate Validates all values of associated components and returns: 1. `ValidationError` - if the validation is failed; 2. List of components to send - if the validation is successful. #### submit Submits the form. ### Validation `bForm` automatically validates all associated components before each submission. ``` < b-form :dataProvider = 'User' | :method = 'add' < b-input :name = 'fname' | :validators = ['required', 'name'] < b-input :name = 'lname' < b-input :name = 'bd' | :type = 'date' | :validators = ['required'] < b-button :type = 'submit' ``` ### Converting of data to submit If a component associated with `bForm` provides the `formConverter` prop, it will be used by `bForm` to transform the associated component's group value before submission. ``` < b-form :dataProvider = 'User' | :method = 'add' < b-input :name = 'fname' | :formConverter = getRandomName < b-input :name = 'fname' < b-button :type = 'submit' ```