# JavaScript Utilities

## Introduction

The Form.io Utilities class is a part of the JavaScript SDK, but provides a number of methods that makes working with Form.io forms within your applications easier.

## Installation

To install the Utilities, you can either import them directly into your application as follows.

```
import Utils from 'formiojs/utils';
```

or they can be used as part of the Form.io renderer by including the following script in your application.

```
<script src="https://cdn.form.io/formiojs/formio.form.min.js"></script>
```

{% hint style="info" %}
Navigate to the following link for more information about the [**Form.io CDNs**](https://help.form.io/faq/faq#what-are-the-form.io-cdns)
{% endhint %}

and then you can find the Utilities methods as part of the `Utils` property on the `Formio` object.

```
Formio.Utils.eachComponent(....)
```

## Utility Functions

The following are common functions that can be used within the Form.io Utilities library.

### `eachComponent(components, fn, [includeAll])`

Calls `fn(component)` for each component in `components`, accounting for nested layout components. (Does not call for layout components themselves, unless includeAll is true).

| Parameter  | Description                                                                          |
| ---------- | ------------------------------------------------------------------------------------ |
| components | An array of JSON form components to iterate over.                                    |
| fn         | The function to call for each input component.                                       |
| includeAll | Boolean to indicate if we should include all components including layout components. |

The current data path of the element. Example: data.user.firstName

```
var utils = require('formiojs/utils');
utils.eachComponent(form.components, function(component) {
  // Do something...
})
```

### `getComponent(components, key)`

Returns the component with the given `key` or undefined if not found.

| Parameter  | Description                                          |
| ---------- | ---------------------------------------------------- |
| components | An array of JSON form components to iterate over.    |
| key        | The key of the component you would like to retrieve. |

```
var utils = require('formiojs/utils');
var component = utils.getComponent(form.components, 'myKey');
```

### `findComponents(components, query)`

Returns an array of components that match the find query criteria. This query is very similar to MongoDB where if you wish to find a nested query, you would provide the key as the path of the property using dot notation.&#x20;

| Parameter  | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| components | An array of JSON form components to iterate over.                          |
| query      | A JSON object to use as a query to find a certain component within a form. |

Here is an example.

```
// Find all textfields with a specific custom property.
var utils = require('formiojs/utils');
var comps = utils.findComponents(form.components, {
  'type': 'textfield',
  'properties.objectId': '2345'
});

// Should return all textfield components with 'properties.objectId' = '2345'.
console.log(comps);
```

### `searchComponents(components, query)`

Finds a component provided a query of properties of that component.

| Parameter  | Description                                       |
| ---------- | ------------------------------------------------- |
| components | An array of JSON form components to iterate over. |
| query      | The query to pass to `matchComponent`.            |

### `matchComponent(component, query)`

Matches if a component matches the query.

| Parameter | Description                                               |
| --------- | --------------------------------------------------------- |
| component | A component JSON you would like to match against a query. |
| query     | A JSON query to use as the match query.                   |

```
const component = {
    type: 'textfield',
    key: 'firstName',
    label: 'First Name'
};
if (utils.matchComponent(component, {
    key: 'firstName
}) {
    console.log('The component matches!!');
}
```

###

### `flattenComponents(components, includeAll)`

Returns a key-value object where the keys are the keys for each component in `components` and each key points to the corresponding component. This includes nested components as well. Pass true for includeAll if you want to include layout components.

| Parameter  | Description                                                                            |
| ---------- | -------------------------------------------------------------------------------------- |
| components | An array of JSON form components to iterate over.                                      |
| includeAll | Boolean to indicate if you wish to include all components including layout components. |

```
var utils = require('formiojs/utils');
var flattened = utils.flattenComponents(form.components);
console.log(flattened['myNestedComponent']);
```

### `isLayoutComponent(component)`

Determine if a component is a layout component.

| Parameter | Description                                                   |
| --------- | ------------------------------------------------------------- |
| component | The component JSON to determine if this is a layout component |

```
var utils = require('formiojs/utils');
var layoutComponent = utils.isLayoutComponent(form.components[0]);
console.log(layoutComponent);
```

### `getValue(submission, key)`

Get the value for a components API key, from the given submission. Recursively searches the submission for the key.

| Parameter  | Description                                                                     |
| ---------- | ------------------------------------------------------------------------------- |
| submission | The submission JSON object                                                      |
| key        | The component key you would like to fetch the value from within the submission. |

```
var utils = require('formiojs/utils');
var value = utils.getValue(submission, 'myComponent'); // The value or undefined.
```

### `parseFloat(value)`

Extension of standard [**parseFloat**](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/parseFloat) function, that also clears input string. Useful for [**Currency component**](https://help.form.io/userguide/form-components/#currency).

| Parameter | Description                        |
| --------- | ---------------------------------- |
| value     | The value you would like to parse. |

```
utils.parseFloat('12,345,678.90'); // -> 12345678.90
```

### `formatAsCurrency(value)`

Formats provided value in way how [**Currency component**](https://help.form.io/userguide/form-components/#currency) uses it.

| Parameter | Description                         |
| --------- | ----------------------------------- |
| value     | The value you would like to format. |

```
utils.formatAsCurrency(123.4); // -> '123.40'
utils.formatAsCurrency(12345678.9); // -> '12,345,678.90'
utils.formatAsCurrency(12345678.915); // -> '12,345,678.92'
utils.formatAsCurrency('12345678.915'); // -> '12,345,678.92'
```

### `escapeRegExCharacters(value)`

Escapes RegEx characters in provided String value.

| Parameter | Description                                                   |
| --------- | ------------------------------------------------------------- |
| value     | The value you would like to escape the regex characters from. |

```
utils.escapeRegExCharacters('[form.io](https://form.io/)'); // -> '\[form\.io\]\(https:\/\/form\.io\)'
```

### `boolValue(value)`

Determines the boolean value of a setting.

### `isMongoId(text)`

Check to see if an ID is a mongoID.

### `checkCondition(component, row, data, form, instance)`

Checks the conditions for a provided component and data.

| Parameter | Description                                                |
| --------- | ---------------------------------------------------------- |
| component | The component JSON                                         |
| row       | Contextual row data                                        |
| data      | Full submission data                                       |
| form      | The form JSON schema                                       |
| instance  | The component instance this method is being executed with. |

### `unescapeHTML(str)`

Unescape HTML characters like <, >, & and etc.

### `convertStringToHTMLElement(str, selector)`

Make HTML element from string

### `guid()`

Generate a GUID

### `isValidDate(date)`

Checks a date to see if it is valid.

### `formatDate(value, format, timezone, flatPickrInputFormat)`

Format a date provided a value, format, and timezone object.

### `getBrowserInfo()`

Get the browser name and version

### `isInputComponent(componentJson)`

Checks to see if a component JSON is an input component.