npm package: @heridux/form
Description: Manage your forms easily with heridux-form
Author: Yannick Bochatay
Latest version: 0.0.1

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

-   [HeriduxForm][1]
    -   [Parameters][2]
    -   [Examples][3]
    -   [defineForm][4]
        -   [Parameters][5]
        -   [Examples][6]
    -   [initFormValues][7]
        -   [Parameters][8]
        -   [Examples][9]
    -   [initFormValuesIn][10]
        -   [Parameters][11]
        -   [Examples][12]
    -   [checkForm][13]
        -   [Parameters][14]
    -   [cancelFormValues][15]
    -   [cancelFormValuesIn][16]
        -   [Parameters][17]
    -   [resetFormValues][18]
    -   [resetFormValuesIn][19]
        -   [Parameters][20]
    -   [addFields][21]
        -   [Parameters][22]
    -   [removeFields][23]
        -   [Parameters][24]
    -   [setFieldValue][25]
        -   [Parameters][26]
    -   [initFieldValue][27]
        -   [Parameters][28]
    -   [cancelFieldValue][29]
        -   [Parameters][30]
    -   [setFieldWarning][31]
        -   [Parameters][32]
    -   [setFieldError][33]
        -   [Parameters][34]
    -   [setGlobalError][35]
        -   [Parameters][36]
    -   [isFormTouched][37]
        -   [Parameters][38]
    -   [isFormValid][39]
        -   [Parameters][40]
    -   [getFormErrors][41]
        -   [Parameters][42]
    -   [setFormValues][43]
        -   [Parameters][44]
    -   [setFormValuesIn][45]
        -   [Parameters][46]
    -   [getFormValues][47]
        -   [Parameters][48]
    -   [getFormValuesIn][49]
        -   [Parameters][50]
    -   [getFieldValue][51]
        -   [Parameters][52]
    -   [getFieldWarning][53]
        -   [Parameters][54]
    -   [getFieldError][55]
        -   [Parameters][56]
    -   [isFieldTouched][57]
        -   [Parameters][58]
    -   [destroyForm][59]
    -   [validateForm][60]
        -   [Examples][61]
    -   [isField][62]
        -   [Parameters][63]

## HeriduxForm

**Extends Heridux**

Form store constructor

### Parameters

-   `STATE_PROPERTY` **[String][64]?** string name for this store (if you plan to use it with redux)

### Examples

```javascript
import HeriduxForm from "@heridux/form"
import Rules from "@heridux/rules"

const store = new HeriduxForm("myForm")

store.defineForm({
  name : Rules.string.isRequired,
  age : Rules.number,
  address : {
    street : Rules.string,
    city : Rules.string,
    zipCode : Rules.number
  }
})

// register store in redux store (see @heridux/core for more details)
store.register()

store.initFormValues({
  name : "Roger",
  age : 56
})

store.setFieldValue(["address", "city"], "Paris")

store.getFieldValue("age") // 56
```

Returns **[undefined][65]** 

### defineForm

Defines structure of the form

#### Parameters

-   `fields` **[Object][66]** object describing the form (field name in key, Rules object in value)

#### Examples

```javascript
import HeriduxForm from "@heridux/form"
import Rules from "@heridux/rules"

const store = new HeriduxForm("myForm")

store.defineForm({
  name : Rules.string.isRequired,
  age : Rules.number,
  address : {
    street : Rules.string,
    city : Rules.string,
    zipCode : Rules.number
  }
})

// register store in redux store (see @heridux/core for more details)
store.register()
```

Returns **[undefined][65]** 

### initFormValues

Initialization of the form. Undeclared fields will be ignored.

#### Parameters

-   `values` **[Object][66]** initialization values

#### Examples

```javascript
import HeriduxForm from "@heridux/form"
import Rules from "@heridux/rules"

const store = new HeriduxForm("myForm")

store.defineForm({
  name : Rules.string.isRequired,
  age : Rules.number
})

store.register()

store.initFormValues({
  name : "Roger",
  age : 56,
  address : "Paris"
})

// initFormValues won't consider form has been touched
store.get("touched") // false

// unknown keys are ignored
store.getFieldValue("address") // null
```

Returns **[undefined][65]** 

### initFormValuesIn

Initialization of part of the form. Undeclared fields will be ignored.

#### Parameters

-   `path` **[Array][67]** entry point
-   `values` **[Object][66]** initialization values

#### Examples

```javascript
import HeriduxForm from "@heridux/form"
import Rules from "@heridux/rules"

const store = new HeriduxForm("myForm")

store.defineForm({
  name : Rules.string.isRequired,
  age : Rules.number,
  address : {
    street : Rules.string,
    city : Rules.string,
    zipCode : Rules.number
}
})

store.register()

store.initFormValuesIn(["address"], {
  street : "Victor Hugo",
  city : "Toulouse",
  zipCode : 31000
})

// initFormValuesIn won't consider form has been touched
store.get("touched") // false

store.getFormValues()
// {
//   name : null,
//   age : null,
//   address : {
//     street : "Victor Hugo",
//     city : "Toulouse",
//     zipCode : 31000
//   }
//}
```

Returns **[undefined][65]** 

### checkForm

Check validity of the form

#### Parameters

-   `_formValues` **[Object][66]?** values to check if they are not those of the store (optional, default `null`)

Returns **[Boolean][68]** true if all fields are valid, false otherwise

### cancelFormValues

Cancel modifications (return to the initial values defined by the initFormValues method)

Returns **[undefined][65]** 

### cancelFormValuesIn

Cancel modifications to part of form (return to the initial values defined by the initFormValues method)

#### Parameters

-   `path` **[Array][67]** entry point

Returns **[undefined][65]** 

### resetFormValues

Réinitialisation des valeurs du formulaires (toutes fixées à null)

Returns **[undefined][65]** 

### resetFormValuesIn

Réinitialisation d'une partie des valeurs du formulaires (toutes fixées à null)

#### Parameters

-   `path` **[Array][67]** point d'entrée

Returns **[undefined][65]** 

### addFields

Ajout dynamique de champs dans le formulaire (postérieur à la méthode defineForm)

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin où insérer les nouveaux champs
-   `fields` **[Object][66]** objet dont les clés sont les noms des champs et les valeurs les règles
    de validation

Returns **[undefined][65]** 

### removeFields

Suppression dynamique de champs de formulaire

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin ou supprimer les champs

Returns **[undefined][65]** 

### setFieldValue

Attribution d'une valeur à un champ

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin du champ
-   `value` **any** valeur du champ

Returns **[undefined][65]** 

### initFieldValue

Initialisation d'un champ

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin du champ
-   `value` **any** valeur du champ

Returns **[undefined][65]** 

### cancelFieldValue

Annulation des modifications d'un champ (retour à la valeur initiale)

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin du champ

Returns **[undefined][65]** 

### setFieldWarning

Définition d'un message d'avetissement

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin du champ
-   `message` **[String][64]** contenu du message
-   `properties` **[Object][66]** propriétés supplémentaires liées à l'erreur

Returns **[undefined][65]** 

### setFieldError

Définition d'un message d'erreur

#### Parameters

-   `path` **([Array][67] \| [String][64])** chemin du champ
-   `message` **[String][64]** contenu du message
-   `properties` **[Object][66]** propriétés supplémentaires liées à l'erreur

Returns **[undefined][65]** 

### setGlobalError

Définition d'une erreur globale sur le formulaire

#### Parameters

-   `error` **[String][64]** contenu de l'erreur

Returns **[undefined][65]** 

### isFormTouched

Teste si le formulaire a été modifié

#### Parameters

-   `state` **Immutable.Map** optionnel état du store si on l'a sous la main

Returns **[Boolean][68]** true si le formulaire a été modifié, false sinon

### isFormValid

Teste si le formulaire contient des erreurs. Attention, il ne lance pas les validations
mais se contente de vérifier si des erreurs ont été levées.

#### Parameters

-   `state` **Immutable.Map** optionnel état du store si on l'a sous la main

Returns **[Boolean][68]** true si le formulaire contient des erreurs, false sinon

### getFormErrors

Récupère l'ensemble des erreurs du formulaire sous forme de tableau

#### Parameters

-   `state` **Immutable.Map** optionnel état du store si on l'a sous la main

Returns **[Array][67]** tableau des erreurs

### setFormValues

Attribue les valeurs au formulaire. Attention, les validations ne sont pas
lancées car certaines peuvent être interdépendantes (si besoin exécuter la
méthode checkForm ensuite)

#### Parameters

-   `values` **[Object][66]** objet contenant les valeurs

Returns **[undefined][65]** 

### setFormValuesIn

Attribue des valeurs au formulaire. Attention, les validations ne sont pas
lancées car certaines peuvent être interdépendantes (si besoin exécuter la
méthode checkForm ensuite)

#### Parameters

-   `path` **[Array][67]** optionnel, point d'entrée si on ne veut affecter qu'une partie du formulaire
-   `values` **[Object][66]** objet contenant les valeurs

Returns **[undefined][65]** 

### getFormValues

Retrieves form values

#### Parameters

-   `_state` **Immutable.Map?** state of the store if available

Returns **[Object][66]** object describing values

### getFormValuesIn

Retrieves values of a form part

#### Parameters

-   `path` **([Array][67] \| [String][64])** key path to form part
-   `_state` **Immutable.Map?** state of the store if available

Returns **[Object][66]** object describing values

### getFieldValue

Retrieves field value

#### Parameters

-   `path` **([Array][67] \| [String][64])** key path to the field
-   `_state` **Immutable.Map?** state of the store if available

Returns **any** field value

### getFieldWarning

Retrieves the warning message of a field

#### Parameters

-   `path` **([Array][67] \| [String][64])** key path to the field
-   `_state` **Immutable.Map?** state of the store if available

Returns **[String][64]** warning message

### getFieldError

Retrieves the error message of a field

#### Parameters

-   `path` **([Array][67] \| [String][64])** key path to the field
-   `_state` **Immutable.Map?** state of the store if available

Returns **[String][64]** error message

### isFieldTouched

Tests if a field has been modified

#### Parameters

-   `path` **([Array][67] \| [String][64])** key path to the field
-   `_state` **Immutable.Map?** state of the store if available

Returns **[Boolean][68]** true if the field has been modified

### destroyForm

Completely reset the form structure

Returns **[undefined][65]** 

### validateForm

Set current values as initial values. Form will be considered unmodified.
Warning : field rules won't be check (use checkForm if needed)

#### Examples

```javascript
import HeriduxForm from "@heridux/form"
import Rules from "@heridux/rules"

const store = new HeriduxForm("myForm")

store.defineForm({
  name : Rules.string.isRequired,
  age : Rules.number
})

store.register()

store.setFieldValue("name", "Roger")
store.setFieldValue("age", "56")

store.get("touched") // true

store.validateForm()

store.get("touched") // false
store.cancelFormValues() // no effect since values are now considered as initial values
```

Returns **[undefined][65]** 

### isField

Checks if a field is registered at path passed as argument

#### Parameters

-   `path` **[Array][67]** key path

Returns **Bool** true if a field is registered

[1]: #heriduxform

[2]: #parameters

[3]: #examples

[4]: #defineform

[5]: #parameters-1

[6]: #examples-1

[7]: #initformvalues

[8]: #parameters-2

[9]: #examples-2

[10]: #initformvaluesin

[11]: #parameters-3

[12]: #examples-3

[13]: #checkform

[14]: #parameters-4

[15]: #cancelformvalues

[16]: #cancelformvaluesin

[17]: #parameters-5

[18]: #resetformvalues

[19]: #resetformvaluesin

[20]: #parameters-6

[21]: #addfields

[22]: #parameters-7

[23]: #removefields

[24]: #parameters-8

[25]: #setfieldvalue

[26]: #parameters-9

[27]: #initfieldvalue

[28]: #parameters-10

[29]: #cancelfieldvalue

[30]: #parameters-11

[31]: #setfieldwarning

[32]: #parameters-12

[33]: #setfielderror

[34]: #parameters-13

[35]: #setglobalerror

[36]: #parameters-14

[37]: #isformtouched

[38]: #parameters-15

[39]: #isformvalid

[40]: #parameters-16

[41]: #getformerrors

[42]: #parameters-17

[43]: #setformvalues

[44]: #parameters-18

[45]: #setformvaluesin

[46]: #parameters-19

[47]: #getformvalues

[48]: #parameters-20

[49]: #getformvaluesin

[50]: #parameters-21

[51]: #getfieldvalue

[52]: #parameters-22

[53]: #getfieldwarning

[54]: #parameters-23

[55]: #getfielderror

[56]: #parameters-24

[57]: #isfieldtouched

[58]: #parameters-25

[59]: #destroyform

[60]: #validateform

[61]: #examples-4

[62]: #isfield

[63]: #parameters-26

[64]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[65]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined

[66]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[67]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[68]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean