# Data & values

> Read and write form data and single values, attach server errors and track unsaved changes through NgxViewBuilderApiService.

Source: https://ngxviewbuilder.io/developers/api/data

The data of a view is one object: every element stores its value under its `name` (or its data path inside panels and repeaters). These methods read and write that object, one value or all of it, and keep track of whether the person changed anything.

| Method | Returns | In short |
| --- | --- | --- |
| [`getData(options?)`](https://ngxviewbuilder.io/developers/api/data#getdata) | `Record<string, unknown>` | The whole data object, without the library's `__` keys |
| [`setData(data)`](https://ngxviewbuilder.io/developers/api/data#setdata) | `void` | Replace all data |
| [`setElementsData(data)`](https://ngxviewbuilder.io/developers/api/data#setelementsdata) | `Promise<void>` | Merge several values |
| [`setValue(path, value)`](https://ngxviewbuilder.io/developers/api/data#setvalue) | `Promise<void>` | Set one value like a person would |
| [`setElementValue(path, value)`](https://ngxviewbuilder.io/developers/api/data#setelementvalue) | `Promise<void>` | Same as `setValue` |
| [`getElementValue(path)`](https://ngxviewbuilder.io/developers/api/data#getelementvalue) | `unknown` | Read one value |
| [`clearValue(path)`](https://ngxviewbuilder.io/developers/api/data#clearvalue) | `boolean` | Remove one key from the data |
| [`clearValues(paths)`](https://ngxviewbuilder.io/developers/api/data#clearvalues) | `number` | Remove several keys |
| [`clearElementValue(nameOrPath)`](https://ngxviewbuilder.io/developers/api/data#clearelementvalue) | `boolean` | Empty one field |
| [`resetElementValue(nameOrPath)`](https://ngxviewbuilder.io/developers/api/data#resetelementvalue) | `Promise<boolean>` | Back to the default value |
| [`clearData()`](https://ngxviewbuilder.io/developers/api/data#cleardata) | `boolean` | Empty the whole form |
| [`isDirty()`](https://ngxviewbuilder.io/developers/api/data#isdirty) | `boolean` | Did anything change since load? |
| [`markPristine()`](https://ngxviewbuilder.io/developers/api/data#markpristine) | `void` | Treat the current data as saved |
| [`setElementErrors(nameOrPath, errors)`](https://ngxviewbuilder.io/developers/api/data#setelementerrors) | `boolean` | Show server errors on a field |
| [`clearElementErrors(nameOrPath)`](https://ngxviewbuilder.io/developers/api/data#clearelementerrors) | `boolean` | Remove them |
| [`getElementErrors(nameOrPath)`](https://ngxviewbuilder.io/developers/api/data#getelementerrors) | `string[]` | Read them |

## The data object

### `getData()`

```ts
getData(options?: { includeInternal?: boolean }): Record<string, unknown>
```

A copy of the current data, ready to save. The library keeps some state of its own next to it under keys starting with `__` (variables, route, external context, the selected tab or step). Those are left out, so you can send the result to your server as it is.

```ts
const data = api.getData();
// {
//   firstName: 'Ada',
//   clientType: 'company',
//   address: { city: 'Vilnius', street: 'Gedimino pr. 1' },
//   orders: [{ sku: 'A-100', amount: 2 }]
// }

await firstValueFrom(http.put(`/api/clients/${id}`, data));
```

Pass `includeInternal: true` when you need the library's keys as well, for example to read a variable an action stored:

```ts
const all = api.getData({ includeInternal: true });
all.__variables?.picked; // 'V21'
all.__progressFlow?.checkout?.selectedStep; // 'payment'
```

Before 0.12.4 `getData()` always returned the `__` keys and you had to filter them out yourself. The filter does no harm if you keep it.

The runtime component also has `getDataSnapshot()`, which returns the same object as `getData()`.

### `setData()`

```ts
setData(data: Record<string, unknown>): void
```

Replaces all data, typically with a record loaded for editing. Fields without a key in it become empty. The result counts as the loaded state, so `isDirty()` stays `false`.

```ts
const client = await firstValueFrom(http.get<Client>(`/api/clients/${id}`));
api.setData(client);
```

### `setElementsData()`

```ts
setElementsData(data: Record<string, unknown>): Promise<void>
```

Merges values into the current data and leaves every other field alone. Each key goes through [`setValue`](https://ngxviewbuilder.io/developers/api/data#setvalue), so expressions, logic and change events run for it.

```ts
await api.setElementsData({ city: 'Kaunas', zip: 'LT-44280' });
api.getData(); // firstName, email and the rest unchanged; city and zip updated
```

## One value

### `setValue()`

```ts
setValue(dataPath: string, value: unknown): Promise<void>
```

Sets one value the way a person typing would: the field shows it, expressions that depend on it recalculate, `visibleIf` and friends re-run, `onValueChanged` fires. Paths reach into panels and repeaters.

```ts
await api.setValue('clientType', 'company');     // the company panel appears
await api.setValue('address.city', 'Vilnius');   // object panel field
await api.setValue('orders[0].amount', 3);       // first row of a repeater
await api.setValue('orders', [{ sku: 'A', amount: 1 }, { sku: 'B', amount: 2 }]); // all rows
```

The promise resolves once the value is written; dependent expressions finish a moment later.

### `setElementValue()`

```ts
setElementValue(elementDataPath: string, value: unknown): Promise<void>
```

Another name for `setValue`, for code that reads better with it.

### `getElementValue()`

```ts
getElementValue(elementDataPath: string): unknown
```

```ts
api.getElementValue('total');          // 30
api.getElementValue('orders[1].sku');  // 'B'
api.getElementValue('unknown');        // undefined
```

### `clearValue()`

```ts
clearValue(dataPath: string, options?: { clearErrors?: boolean }): boolean
```

Removes the key from the data object (it is gone from `getData()`, not set to `null`) and empties the field on screen. Errors shown on it are cleared too unless you pass `clearErrors: false`. Returns `false` when the key was not there.

```ts
api.clearValue('companyCode'); // true
```

### `clearValues()`

```ts
clearValues(dataPaths: readonly string[], options?: { clearErrors?: boolean }): number
```

Several at once; returns how many keys were removed.

```ts
api.clearValues(['companyCode', 'vatCode', 'notThere']); // 2
```

### `clearElementValue()`

```ts
clearElementValue(elementNameOrPath: string, options?: { clearErrors?: boolean }): boolean
```

Like `clearValue`, addressed by element name.

### `resetElementValue()`

```ts
resetElementValue(elementNameOrPath: string): Promise<boolean>
```

Puts the element back on its **Default value**, or empties it when it has none.

```ts
await api.setValue('quantity', 7);
await api.resetElementValue('quantity'); // true, quantity is 1 again (its default)
```

### `clearData()`

```ts
clearData(): boolean
```

Empties every field. The library's own keys stay.

## Unsaved changes

### `isDirty()`

```ts
isDirty(): boolean
```

`true` once the data differs from what was loaded or last marked as saved. Default values, expressions and load events that fill the form when it opens are part of the loaded state, so a view that was only opened is not dirty.

```ts
canDeactivate(): boolean {
  return !this.api.isDirty() || confirm('Leave without saving?');
}
```

### `markPristine()`

```ts
markPristine(): void
```

Takes the current data as the new saved state, typically right after your save succeeded. A successful Submit does this on its own.

```ts
await firstValueFrom(http.put(`/api/clients/${id}`, api.getData()));
api.markPristine();
api.isDirty(); // false
```

## Server errors

Errors you attach show under the field exactly like validator messages, and count in validation until you clear them.

### `setElementErrors()`

```ts
setElementErrors(nameOrPath: string, errors: string | readonly string[]): boolean
```

```ts
const res = await firstValueFrom(http.post('/api/clients', api.getData()), { defaultValue: null });
if (res?.errors?.email) {
  api.setElementErrors('email', ['This e-mail is already registered']);
}
```

Returns `false` when no such element exists.

### `clearElementErrors()`

```ts
clearElementErrors(nameOrPath: string): boolean
```

### `getElementErrors()`

```ts
getElementErrors(nameOrPath: string): string[]
```

```ts
api.getElementErrors('email'); // ['This e-mail is already registered']
```

The [element handle](https://ngxviewbuilder.io/developers/api/elements#element-getelementapi) has the same three as `setErrors`, `clearErrors` and `getErrors`.
