<commit_before># Widget API Reference

This document describes the API that a custom widget can use to
communicate with the Contentful Management App.

### Table of Contents
* [Inclusion into your project](#inclusion-into-your-project)
* [Initialization](#initialization)
* [`widget.field`](#widgetfield)
* [`widget.entry`](#widgetentry)
  * [`entry.fields[name]`](#entryfieldsname-field)
* [`widget.space`](#widgetspace)
  * [Content Types](#content-types)
  * [Entries](#entries)
  * [Assets](#assets)
* [`widget.locales`](#widgetlocales)
* [`widget.window`](#widgetwindow)

## Inclusion into your project

You will need to include the `contentful-widget-api` library in your HTML5 app like
so:
~~~html
<script src="https://contentful.github.io/widget-sdk/cf-widget-api.js"></script>
~~~

The Contentful Widget SDK including the JavaScript API is also distributed as an
[NPM package][package].

~~~bash
npm install --save contentful-widget-sdk
~~~

[package]: https://www.npmjs.com/package/contentful-widget-sdk

## Initialization

The `widget-api` library exposes the `contentfulWidget.init()` method.
This is the main entry point for all widget related code. If you require the
script from the web without any module system the entry point is available as

~~~js
window.contentfulWidget.init(function (widget) {
  var value = widget.field.getValue()
  widget.field.setValue("Hello world!")
})
~~~

If you use a CommonJS packager for the browser (e.g. [Browserify][]) you need
to require the Widget API.

~~~js
var contentfulWidget = require('contentful-widget-sdk')
contentfulWidget.init(function (api) {
  /* ... */
})
~~~

[Browserify]: http://browserify.org/

## `widget.field`

This API gives you access to the value and metadata of the field the widget is
attached to.

If you use localization, a widget instance will be rendered for each locale.
This means you can only change the value for the given locale. See the
[`entry.fields` API](#entryfieldsname-field) on how to change values for different
locales.

Suppose an entry returned by the Contentful Management API looks like this
~~~js
{
  sys: { ... },
  fields: {
    title: {
      "en_US": "My Post"
    },
    ...
  }
}
~~~
and the widget is attached to the `title` field and the `en_US` locale.


##### `widget.field.getValue(): mixed`
Gets the current value of the field and locale. In the example this would yield `"My Post"`.

##### `widget.field.setValue(value): Promise<void>`
Sets the value for the field and locale. The promise is resolved when the change
has been acknowledged. The type of the value must match the expected field type.
For example, if the widget is attached to a “Symbol” field you must pass a
string.

##### `widget.field.onValueChanged(cb): function`
Calls the callback every time the value of the field is changed by some external
event (e.g. when multiple editors are working on the same entry). It will not be
called after `setValue()` is called.

The method returns a function that can be called to stop listening to changes.

##### `widget.field.id: string`
The ID of a field is defined in an entry’s content type. Yields `"title"` in the
example.

##### `widget.field.locale: string`
The current locale of a field the widget is attached to. Yields `"en_US"` in the
example.


## `widget.entry`

This object allows you to read and update the value of any field of the current
entry and to get the entry's metadata.

##### `entry.getSys(): object`
Returns metadata for an entry. The value coincides with the `sys` value of an
entry returned by the [Contentful Management API](https://github.com/contentful/contentful-management.js#entry-properties)

##### `entry.onSysChanged(cb): function`
Calls the callback with metadata every time that metadata changes. The returned
function can be called to stop listening to changes.

### `entry.fields[name]: Field`

In addition to [`widget.field`](#widgetfield), a widget can also control the
values of all other fields in the current entry in a similar way. The main
difference here is that all operations on an `entry.fields` field accept an
optional `locale` argument which falls back to the space's default locale (see
[`widget.locales`](#widgetlocales)). Providing an unknown locale throws an
exception.

* `field.id: string`<commit_msg>Clarify that entry fields are referenced by their ID<commit_after># Widget API Reference

This document describes the API that a custom widget can use to
communicate with the Contentful Management App.

### Table of Contents
* [Inclusion into your project](#inclusion-into-your-project)
* [Initialization](#initialization)
* [`widget.field`](#widgetfield)
* [`widget.entry`](#widgetentry)
  * [`entry.fields[name]`](#entryfieldsname-field)
* [`widget.space`](#widgetspace)
  * [Content Types](#content-types)
  * [Entries](#entries)
  * [Assets](#assets)
* [`widget.locales`](#widgetlocales)
* [`widget.window`](#widgetwindow)

## Inclusion into your project

You will need to include the `contentful-widget-api` library in your HTML5 app like
so:
~~~html
<script src="https://contentful.github.io/widget-sdk/cf-widget-api.js"></script>
~~~

The Contentful Widget SDK including the JavaScript API is also distributed as an
[NPM package][package].

~~~bash
npm install --save contentful-widget-sdk
~~~

[package]: https://www.npmjs.com/package/contentful-widget-sdk

## Initialization

The `widget-api` library exposes the `contentfulWidget.init()` method.
This is the main entry point for all widget related code. If you require the
script from the web without any module system the entry point is available as

~~~js
window.contentfulWidget.init(function (widget) {
  var value = widget.field.getValue()
  widget.field.setValue("Hello world!")
})
~~~

If you use a CommonJS packager for the browser (e.g. [Browserify][]) you need
to require the Widget API.

~~~js
var contentfulWidget = require('contentful-widget-sdk')
contentfulWidget.init(function (api) {
  /* ... */
})
~~~

[Browserify]: http://browserify.org/

## `widget.field`

This API gives you access to the value and metadata of the field the widget is
attached to.

If you use localization, a widget instance will be rendered for each locale.
This means you can only change the value for the given locale. See the
[`entry.fields` API](#entryfieldsname-field) on how to change values for different
locales.

Suppose an entry returned by the Contentful Management API looks like this
~~~js
{
  sys: { ... },
  fields: {
    title: {
      "en_US": "My Post"
    },
    ...
  }
}
~~~
and the widget is attached to the `title` field and the `en_US` locale.


##### `widget.field.getValue(): mixed`
Gets the current value of the field and locale. In the example this would yield `"My Post"`.

##### `widget.field.setValue(value): Promise<void>`
Sets the value for the field and locale. The promise is resolved when the change
has been acknowledged. The type of the value must match the expected field type.
For example, if the widget is attached to a “Symbol” field you must pass a
string.

##### `widget.field.onValueChanged(cb): function`
Calls the callback every time the value of the field is changed by some external
event (e.g. when multiple editors are working on the same entry). It will not be
called after `setValue()` is called.

The method returns a function that can be called to stop listening to changes.

##### `widget.field.id: string`
The ID of a field is defined in an entry’s content type. Yields `"title"` in the
example.

##### `widget.field.locale: string`
The current locale of a field the widget is attached to. Yields `"en_US"` in the
example.


## `widget.entry`

This object allows you to read and update the value of any field of the current
entry and to get the entry's metadata.

##### `entry.getSys(): object`
Returns metadata for an entry. The value coincides with the `sys` value of an
entry returned by the [Contentful Management API](https://github.com/contentful/contentful-management.js#entry-properties)

##### `entry.onSysChanged(cb): function`
Calls the callback with metadata every time that metadata changes. The returned
function can be called to stop listening to changes.

### `entry.fields[id]: Field`

In addition to [`widget.field`](#widgetfield), a widget can also control the
values of all other fields in the current entry. Fields are referenced by their ID.

The `Field` API methods provide a similar interface to `widget.field`. In
addition, the methods accept an optional locale to change the value for a
specific locale. It defaults to the space the space’s default locale (see
[`widget.locales`](#widgetlocales)). Providing an unknown locale throws an
exception.

* `field.id: string`
{'fraction_non_alphanumeric': 0.11075293575869215, 'fraction_numerical': 0.00023025558369790466, 'mean_word_length': 4.550798722044728, 'pattern_counts': {'":': 2, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2197173', 'n_tokens_mistral': 2489, 'n_tokens_neox': 2398, 'n_words': 1073}