Skip to content
This repository has been archived by the owner on Feb 6, 2023. It is now read-only.

Prettify docs files #2275

Closed
wants to merge 4 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 37 additions & 56 deletions docs/APIReference-APIMigration.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ to the `ContentState` record.

This API improvement unlocks the path for many benefits that will be available in v0.11:

* DraftEntity instances and storage will be immutable.
* DraftEntity will no longer be globally accessible.
* Any changes to entity data will trigger a re-render.
- DraftEntity instances and storage will be immutable.
- DraftEntity will no longer be globally accessible.
- Any changes to entity data will trigger a re-render.

## Quick Overview

Expand All @@ -24,21 +24,15 @@ Here is a quick list of what has been changed and how to update your application
**Old Syntax**

```js
const entityKey = Entity.create(
urlType,
'IMMUTABLE',
{src: urlValue},
);
const entityKey = Entity.create(urlType, 'IMMUTABLE', {src: urlValue});
```

**New Syntax**

```js
const contentStateWithEntity = contentState.createEntity(
urlType,
'IMMUTABLE',
{src: urlValue},
);
const contentStateWithEntity = contentState.createEntity(urlType, 'IMMUTABLE', {
src: urlValue,
});
const entityKey = contentStateWithEntity.getLastCreatedEntityKey();
```

Expand All @@ -65,7 +59,8 @@ const entityInstance = contentState.getEntity(entityKey);
```js
const compositeDecorator = new CompositeDecorator([
{
strategy: (contentBlock, callback) => exampleFindTextRange(contentBlock, callback),
strategy: (contentBlock, callback) =>
exampleFindTextRange(contentBlock, callback),
component: ExampleTokenComponent,
},
]);
Expand All @@ -76,36 +71,31 @@ const compositeDecorator = new CompositeDecorator([
```js
const compositeDecorator = new CompositeDecorator([
{
strategy: (
contentBlock,
callback,
contentState
) => exampleFindTextRange(contentBlock, callback, contentState),
strategy: (contentBlock, callback, contentState) => (
contentBlock, callback, contentState
),
component: ExampleTokenComponent,
},
]);
```

Note that ExampleTokenComponent will receive contentState as a prop.

Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to find certain entities in the contentBlock:
Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to find certain entities in the contentBlock:

```js
const mutableEntityStrategy = function(contentBlock, callback, contentState) {
contentBlock.findEntityRanges(
(character) => {
const entityKey = character.getEntity();
if (entityKey === null) {
return false;
}
// To look for certain types of entities,
// or entities with a certain mutability,
// you may need to get the entity from contentState.
// In this example we get only mutable entities.
return contentState.getEntity(entityKey).getMutability() === 'MUTABLE';
},
callback,
);
contentBlock.findEntityRanges(character => {
const entityKey = character.getEntity();
if (entityKey === null) {
return false;
}
// To look for certain types of entities,
// or entities with a certain mutability,
// you may need to get the entity from contentState.
// In this example we get only mutable entities.
return contentState.getEntity(entityKey).getMutability() === 'MUTABLE';
}, callback);
};
```

Expand All @@ -115,34 +105,25 @@ const mutableEntityStrategy = function(contentBlock, callback, contentState) {

```js
function findLinkEntities(contentBlock, callback) {
contentBlock.findEntityRanges(
(character) => {
const entityKey = character.getEntity();
return (
entityKey !== null &&
Entity.get(entityKey).getType() === 'LINK'
);
},
callback,
);
};
contentBlock.findEntityRanges(character => {
const entityKey = character.getEntity();
return entityKey !== null && Entity.get(entityKey).getType() === 'LINK';
}, callback);
}
```

**New Syntax**

```js
function findLinkEntities(contentBlock, callback, contentState) {
contentBlock.findEntityRanges(
(character) => {
const entityKey = character.getEntity();
return (
entityKey !== null &&
contentState.getEntity(entityKey).getType() === 'LINK'
);
},
callback,
);
};
contentBlock.findEntityRanges(character => {
const entityKey = character.getEntity();
return (
entityKey !== null &&
contentState.getEntity(entityKey).getType() === 'LINK'
);
}, callback);
}
```

## More Information
Expand Down
4 changes: 2 additions & 2 deletions docs/APIReference-CharacterMetadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ for information on how `CharacterMetadata` is used within `ContentBlock`.

## Overview

*Static Methods*
_Static Methods_

<ul class="apiIndex">
<li>
Expand All @@ -51,7 +51,7 @@ for information on how `CharacterMetadata` is used within `ContentBlock`.
</li>
</ul>

*Methods*
_Methods_

<ul class="apiIndex">
<li>
Expand Down
40 changes: 22 additions & 18 deletions docs/APIReference-ContentBlock.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,29 +7,29 @@ title: ContentBlock
[Record](http://facebook.github.io/immutable-js/docs/#/Record/Record) that
represents the full state of a single block of editor content, including:

- Plain text contents of the block
- Type, e.g. paragraph, header, list item
- Entity, inline style, and depth information
- Plain text contents of the block
- Type, e.g. paragraph, header, list item
- Entity, inline style, and depth information

A `ContentState` object contains an `OrderedMap` of these `ContentBlock` objects,
which together comprise the full contents of the editor.

`ContentBlock` objects are largely analogous to block-level HTML elements like
paragraphs and list items. The available types are:

- unstyled
- paragraph
- header-one
- header-two
- header-three
- header-four
- header-five
- header-six
- unordered-list-item
- ordered-list-item
- blockquote
- code-block
- atomic
- unstyled
- paragraph
- header-one
- header-two
- header-three
- header-four
- header-five
- header-six
- unordered-list-item
- ordered-list-item
- blockquote
- code-block
- atomic

New `ContentBlock` objects may be created directly using the constructor.
Expected Record values are detailed below.
Expand All @@ -54,7 +54,7 @@ supplied text.

## Overview

*Methods*
_Methods_

<ul class="apiIndex">
<li>
Expand Down Expand Up @@ -114,7 +114,7 @@ supplied text.
</li>
</ul>

*Properties*
_Properties_

> Note
>
Expand Down Expand Up @@ -161,13 +161,15 @@ supplied text.
```js
getKey(): string
```

Returns the string key for this `ContentBlock`. Block keys are alphanumeric string. It is recommended to use `generateRandomKey` to generate block keys.

### `getType()`

```js
getType(): DraftBlockType
```

Returns the type for this `ContentBlock`. Type values are largely analogous to
block-level HTML elements.

Expand All @@ -176,6 +178,7 @@ block-level HTML elements.
```js
getText(): string
```

Returns the full plaintext for this `ContentBlock`. This value does not contain
any styling, decoration, or HTML information.

Expand Down Expand Up @@ -204,6 +207,7 @@ This value uses the standard JavaScript `length` property for the string, and is
```js
getDepth(): number
```

Returns the depth value for this block, if any. This is currently used only for list items.

### `getInlineStyleAt()`
Expand Down
13 changes: 8 additions & 5 deletions docs/APIReference-ContentState.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ objects.

## Overview

*Static Methods*
_Static Methods_

<ul class="apiIndex">
<li>
Expand All @@ -33,7 +33,7 @@ objects.
</li>
</ul>

*Methods*
_Methods_

<ul class="apiIndex">
<li>
Expand Down Expand Up @@ -138,7 +138,7 @@ objects.
</li>
</ul>

*Properties*
_Properties_

> Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Map) to
> set properties.
Expand All @@ -148,7 +148,10 @@ objects.
> ```js
> const editorState = EditorState.createEmpty();
> const contentState = editorState.getCurrentContent();
> const contentStateWithSelectionBefore = contentState.set('selectionBefore', SelectionState.createEmpty(contentState.getBlockForKey('1pu4d')));
> const contentStateWithSelectionBefore = contentState.set(
> 'selectionBefore',
> SelectionState.createEmpty(contentState.getBlockForKey('1pu4d')),
> );
> ```

<ul class="apiIndex">
Expand Down Expand Up @@ -205,7 +208,7 @@ getEntityMap(): EntityMap
```

Returns an object store containing all `DraftEntity` records that have been
created. In upcoming v0.11.0 the map returned will be an Immutable ordered map
created. In upcoming v0.11.0 the map returned will be an Immutable ordered map
of `DraftEntity` records.

In most cases, you should be able to use the convenience methods below to target
Expand Down
3 changes: 1 addition & 2 deletions docs/APIReference-Data-Conversion.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,6 @@ Given a `ContentState` object, convert it to a raw JS structure. This is useful
when saving an editor state for storage, conversion to other formats, or
other usage within an application.


### `convertFromHTML()`

```js
Expand All @@ -52,7 +51,7 @@ const sampleMarkup =
const blocksFromHTML = convertFromHTML(sampleMarkup);
const state = ContentState.createFromBlockArray(
blocksFromHTML.contentBlocks,
blocksFromHTML.entityMap
blocksFromHTML.entityMap,
);

this.state = {
Expand Down
5 changes: 3 additions & 2 deletions docs/APIReference-Editor.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ See [API Basics](/docs/quickstart-api-basics) for an introduction.
### `editorState`

```js
editorState: EditorState
editorState: EditorState;
```

The `EditorState` object to be rendered by the `Editor`.
Expand Down Expand Up @@ -84,6 +84,7 @@ Optionally set a function to define custom block rendering. See [Advanced Topics
```js
blockRendererMap?: DraftBlockRenderMap
```

Provide a map of block rendering configurations. Each block type maps to element tag and an optional react element wrapper. This configuration is used for both rendering and paste processing. See
[Advanced Topics: Custom Block Rendering](/docs/advanced-topics-custom-block-render-map) for details on usage.

Expand Down Expand Up @@ -248,7 +249,7 @@ handleBeforeInput?: (
Handle the characters to be inserted from a `beforeInput` event. Returning `'handled'`
causes the default behavior of the `beforeInput` event to be prevented (i.e. it is
the same as calling the `preventDefault` method on the event).
Example usage: After a user has typed `- ` at the start of a new block, you might
Example usage: After a user has typed `-` at the start of a new block, you might
convert that `ContentBlock` into an `unordered-list-item`.

At Facebook, we also use this to convert typed ASCII quotes into "smart" quotes,
Expand Down
Loading