v0.10 API migration

The Draft.js v0.10 release contains changes to the API used to manage the DraftEntity data; the global "DraftEntity" module will be deprecated and the DraftEntity instance will manage the ContentState as part of it. This means that the previously accessed method DraftEntity is now moved to the ContentState record.

This API improvement opens the way for many of the benefits that will be provided in v0.11:

DraftEntity instances and stores will be immutable.
DraftEntity will no longer be globally accessible.
Any changes to the entity data trigger a re rendering.

Quick Overview

Here is a quick list of what has changed and how to update the application:

Create an entity

Old grammar

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

New syntax

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

Get entity

Old grammar

const entityInstance = Entity.get(entityKey);
// entityKey is a string key associated with that entity when it was created

New syntax

const entityInstance = contentState.getEntity(entityKey);
// entityKey is a string key associated with that entity when it was created

The change of decorator's strategic argument

Old grammar

const compositeDecorator = new CompositeDecorator([
  {
    strategy: (contentBlock, callback) => exampleFindTextRange(contentBlock, callback),
    component: ExampleTokenComponent,
  },
]);

New syntax

const compositeDecorator = new CompositeDecorator([
  {
    strategy: (
      contentBlock,
      callback,
      contentState
    ) => exampleFindTextRange(contentBlock, callback, contentState),
    component: ExampleTokenComponent,
  },
]);

Note that the ExampleTokenComponent will receive the contentState as a prop.

Why is' content state 'now passed into the decorator strategy? Because if our strategy is to find some entities in contentBlock, we may need it:

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,
  );
};

Decoration strategy, find entity

Old grammar

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

New syntax

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

More information

For more information, see Updated example.