Skip to main content

Library to convert the Facebook Draft.js editor's raw ContentState to HTML

Project description

https://travis-ci.org/springload/draftjs_exporter.svg?branch=master https://img.shields.io/pypi/v/draftjs_exporter.svg https://coveralls.io/repos/github/springload/draftjs_exporter/badge.svg?branch=master https://codeclimate.com/github/springload/draftjs_exporter/badges/gpa.svg

draftjs_exporter 🐍

Library to convert the Facebook Draft.js editor’s raw ContentState to HTML.

This is a work in progress. It is intended to be integrated into Wagtail CMS.

Usage

Understanding DraftJS contentState

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

There are two main parts:

  • blocks - lines of data amd 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.entities.link import Link
from draftjs_exporter.html import HTML

# Configure your element mappings and entity decorators
config = {
    'entity_decorators': {
        'LINK': Link()
    },
    'block_map': {
        'header-two': {'element': 'h2'},
        'blockquote': {'element': 'blockquote'},
        'unstyled': {'element': 'p'}
    },
    'style_map': {
        'ITALIC': {'fontStyle': 'italic'},
        'BOLD': {'fontStyle': 'bold'}
    }
}

# Initialise the exporter with your configuration
exporter = HTML(config)

# Supply a draftJS `contentState`
content_state = {
    'entityMap': {},
    'blocks': [
        {
            'key': '6mgfh',
            'text': 'User experience (UX) design',
            'type': 'header-two',
            'depth': 0,
            'inlineStyleRanges': [
                {
                    'offset': 16,
                    'length': 4,
                    'style': 'BOLD'
                }
            ],
            'entityRanges': []
        }
    ]
}

# Render markup
markup = exporter.render(content_state)

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.

  • 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 belong in <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.

Development

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.

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

Documentation

See the docs/ folder

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

draftjs_exporter-0.3.2.tar.gz (17.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page