Skip to main content

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

Project description

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

draftjs_exporter 🐍
===================

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

It is intended to be used with `Draftail`_ and 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 and inline style attributes (without
newlines).
- entityMap – collection of `Entities`_

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

Using the exporter
~~~~~~~~~~~~~~~~~~

.. code:: sh

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.

.. code:: python

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:

.. code:: sh

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.

Development
-----------

Installation
~~~~~~~~~~~~

Requirements: ``virtualenv``, ``pyenv``, ``twine``

.. code:: sh

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
~~~~~~~~

.. code:: sh

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.python.org/pypi/draftjs_exporter and check that
all is well

Documentation
-------------

See the `docs/`_ folder

.. _Dratail: https://github.com/springload/draftail/
.. _Wagtail CMS: https://wagtail.io
.. _Entities: https://facebook.github.io/draft-js/docs/advanced-topics-entities.html#content
.. _this article: https://medium.com/@rajaraodv/how-draft-js-represents-rich-text-data-eeabb5f25cf2
.. _Semantic Versioning: http://semver.org/spec/v2.0.0.html
.. _measures code coverage: https://coveralls.io/github/springload/draftjs_exporter?branch=master
.. _changelog: https://github.com/springload/draftjs_exporter/CHANGELOG.md
.. _docs/: https://github.com/springload/draftjs_exporter/docs/

Download files

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

Files for draftjs-exporter, version 0.5.0
Filename, size File type Python version Upload date Hashes
Filename, size draftjs_exporter-0.5.0.tar.gz (20.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page