draftjs-exporter 0.6.0

Understanding DraftJS contentState

Unlike traditional rich text editors, DraftJS stores data in a JSON representation.

There are two main parts:

• blocks - lines of data and inline style attributes (without newlines).

• entityMap – collection of Entities

For more information, this article covers the concepts in depth.

Using the exporter

pip install draftjs_exporter

The library requires you to explicity define mappings for the types of blocks and entities you wish to render. We may provide some defaults in the future.

from draftjs_exporter.html import HTML

# The Link decorator will be used to render LINK entities.
class Link:
    def render(self, props):
        return DOM.create_element('a', { 'href': data['url'] }, props['children'])

# Initialise the exporter with your configuration
exporter = HTML({
    'entity_decorators': {
        'LINK': Link()
    },
    # Define how each block should be transformed to HTML.
    'block_map': {
        'header-two': {'element': 'h2'},
        'blockquote': {'element': 'blockquote'},
        'unstyled': {'element': 'p'}
    },
    # Define how each style is rendered – either inline styles or elements.
    'style_map': {
        'ITALIC': {'fontStyle': 'italic'},
        'BOLD': {'element': 'strong'}
    }
})

# Render a Draft.js `contentState`
markup = exporter.render({
    'entityMap': {},
    'blocks': [
        {
            'key': '6mgfh',
            'text': 'User experience (UX) design',
            'type': 'header-two',
            'depth': 0,
            'inlineStyleRanges': [
                {
                    'offset': 16,
                    'length': 4,
                    'style': 'BOLD'
                }
            ],
            'entityRanges': []
        }
    ]
})

Running the example

You can run an executable example as follows:

python example.py

Feature list

This project adheres to Semantic Versioning and measures code coverage.

• Extensive configuration of the generated HTML.

• Default, extensible block & inline style maps for common HTML elements.

• Define any attribute in the block map – custom class names for elements.

• React-like API to create custom entity decorators.

• Automatic conversion of entity data to HTML attributes (int & boolean to string, className to class).

• Wrapped blocks (<li> elements go inside <ul>).

• Nested wrapped blocks (multiple list levels, arbitrary type and depth).

• Output inline styles as inline elements (<em>, <strong>, pick and choose).

• Overlapping inline style ranges.

Installation

Requirements: virtualenv, pyenv, twine

git clone git@github.com:springload/draftjs_exporter.git
cd draftjs_exporter/
virtualenv .venv
source ./.venv/bin/activate
make init
# Optionally, install the git hooks
./.githooks/deploy
# Optionally, install all tested python versions
pyenv install 2.7.11 && pyenv install 3.3.6 && pyenv install 3.4.4 && pyenv install 3.5.1
pyenv global system 2.7.11 3.3.6 3.4.4 3.5.1

Commands

make help            # See what commands are available.
make init            # Install dependencies and initialise for development.
make lint            # Lint the project.
make test            # Test the project.
make test-watch      # Restarts the tests whenever a file changes.
make test-coverage   # Run the tests while generating test coverage data.
make test-ci         # Continuous integration test suite.
make dev             # Restarts the example whenever a file changes.
make clean-pyc       # Remove Python file artifacts.
make publish         # Publishes a new version to pypi.

Debugging

• Always run the tests. npm install -g nodemon, then make test-watch.

• Use a debugger. pip install ipdb, then import ipdb; ipdb.set_trace().

Releases

• Update the changelog.

• Update the version number in draftjs_exporter/__init__.py, following semver.

• git release vx.y.z

• make publish (confirm, and enter your password)

• Go to https://pypi-hypernode.com/pypi/draftjs_exporter and check that all is well