# Data Controls

The data controls module is a module intended to simplify implementation of common controls used with the [`@wordpress/data`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/data/README.md) package.

**Note:** It is assumed that the registry being used has the controls plugin enabled on it (see [more details on controls here](https://github.com/WordPress/gutenberg/tree/HEAD/packages/data#controls))

## Installation

Install the module

```bash
npm install @wordpress/data-controls --save
```

_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._

The following controls are available on the object returned by the module:

## API

<!-- START TOKEN(Autogenerated API docs) -->

### apiFetch

Dispatches a control action for triggering an api fetch call.

_Usage_

```js
import { apiFetch } from '@wordpress/data-controls';

// Action generator using apiFetch
export function* myAction() {
	const path = '/v2/my-api/items';
	const items = yield apiFetch( { path } );
	// do something with the items.
}
```

_Parameters_

-   _request_ `Object`: Arguments for the fetch request.

_Returns_

-   `Object`: The control descriptor.

### controls

The default export is what you use to register the controls with your custom store.

_Usage_

```js
// WordPress dependencies
import { controls } from '@wordpress/data-controls';
import { registerStore } from '@wordpress/data';

// Internal dependencies
import reducer from './reducer';
import * as selectors from './selectors';
import * as actions from './actions';
import * as resolvers from './resolvers';

registerStore( 'my-custom-store', {
	reducer,
	controls,
	actions,
	selectors,
	resolvers,
} );
```

_Returns_

-   `Object`: An object for registering the default controls with the store.

### dispatch

Control for dispatching an action in a registered data store. Alias for the `dispatch` control in the `@wordpress/data` package.

_Parameters_

-   _storeNameOrDescriptor_ `string | StoreDescriptor`: The store object or identifier.
-   _actionName_ `string`: The action name.
-   _args_ `any[]`: Arguments passed without change to the `@wordpress/data` control.

### select

Control for resolving a selector in a registered data store. Alias for the `resolveSelect` built-in control in the `@wordpress/data` package.

_Parameters_

-   _storeNameOrDescriptor_ `string | StoreDescriptor`: The store object or identifier.
-   _selectorName_ `string`: The selector name.
-   _args_ `any[]`: Arguments passed without change to the `@wordpress/data` control.

### syncSelect

Control for calling a selector in a registered data store. Alias for the `select` built-in control in the `@wordpress/data` package.

_Parameters_

-   _storeNameOrDescriptor_ `string | StoreDescriptor`: The store object or identifier.
-   _selectorName_ `string`: The selector name.
-   _args_ `any[]`: Arguments passed without change to the `@wordpress/data` control.

<!-- END TOKEN(Autogenerated API docs) -->

## Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>