v2.1.4

Changed

• Attempt to fix project description formatting on PyPI, broken in the last release (#103).

v2.1.3

Changed

• Increase lower bound of optional lxml dependency to v4.2.0 to guarantee Python 3.7 support (#88).

v2.1.2

Changed

• Use io.open with utf-8 encoding in setup.py. Fix #98 (#99)

v2.1.1

Changed

• Add upper bound to lxml dependency, now defined as lxml>=3.6.0,<5 (#75).
• Update html5lib upper bound, now defined as html5lib>=0.999,<=1.0.1.

v2.1.0

Added

• Give block rendering components access to the current block, when the component is rendered for a block, and the blocks list (#90).
• Give text decorators renderers access to the current block and blocks list (#90).
• Give style rendering components access to the current block, blocks list, and current style type as inline_style_range.style (#87, #90).

Changed

• Performance improvements for text-only (no inline styles, no entities) blocks (#89).

v2.0.0

This release contains breaking changes that will require updating the exporter's configurations. Be sure to check out the "how to upgrade" section below.

Changed

• Change default DOM engine to DOMString (#79, #85).
• Add extra install for html5lib (#79, #85).
• Remove support for class-based decorators (#73, #84).
• Switch composite decorators to dict format like that of Draft.js, with strategy and component attributes.
• Use dotted-path loading for custom engines (#64, #81).
• Use dotted-path loading for built-in engines.
• Raise ImportError when loading an engine fails, not ConfigException.

Removed

• Calls to DOM.use must use a valid engine, there is no default value anymore.
• Stop supporting passing an engine class directly in the engine option, or to DOM.use.
• Stop including tests in published package.

Fixed

• Stop loading html5lib engine on every use, even if unused (#80).

How to upgrade

New default engine

The specificities of the new engine are described in the documentation. To start using the new default,

1. Remove the engine property from the exporter configuration, or do 'engine': DOM.STRING,.
2. You can also remove the html5lib and beautifulsoup4 dependencies from your project if they aren't used anywhere else.

To keep using the previous default, html5lib:

1. Set the engine property to 'engine': DOM.HTML5LIB,.
2. Make sure you install the exporter with pip install draftjs_exporter[html5lib].

Decorator component definitions

Decorator components now require the function syntax (see the relevant documentation).

# Before:
class OrderedList:
    def render(self, props):
        depth = props['block']['depth']

        return DOM.create_element('ol', {
            'class': 'list--depth-{0}'.format(depth)
        }, props['children'])
# After:
def ordered_list(props):
    depth = props['block']['depth']

    return DOM.create_element('ol', {
        'class': 'list--depth-{0}'.format(depth)
    }, props['children'])

If you were relying on the configuration capabilities of the class API, switch to composing components instead:

# Before:
class Link:
    def __init__(self, use_new_window=False):
        self.use_new_window = use_new_window

    def render(self, props):
        link_props = {
            'href': props['url'],
        }

        if self.use_new_window:
            link_props['target'] = '_blank'
            link_props['rel'] = 'noreferrer noopener'

        return DOM.create_element('a', link_props, props['children'])

# In the config:
    ENTITY_TYPES.LINK: Link(use_new_window=True)

# After:
def link(props):
    return DOM.create_element('a', props, props['children'])

def same_window_link(props):
    return DOM.create_element(link, {
        'href': props['url'],
    }, props['children'])
})

def new_window_link(props):
    return DOM.create_element(link, {
        'href': props['url'],
        'target': '_blank',
        'rel': 'noreferrer noopener',
    }, props['children'])
})

The composite decorators API now looks closer to that of other decorators, and to Draft.js:

# Before:
class BR:
    SEARCH_RE = re.compile(r'\n')

    def render(self, props):
        if props['block']['type'] == BLOCK_TYPES.CODE:
            return props['children']

        return DOM.create_element('br')


'composite_decorators': [
    BR,
]
# After:

def br(props):
    if props['block']['type'] == BLOCK_TYPES.CODE:
        return props['children']

    return DOM.create_element('br')

# In the config:
'composite_decorators': [
    {
        'strategy': re.compile(r'\n'),
        'component': br,
    },
],

Engine configuration

# The `engine` field in the exporter config now has to be a dotted path string pointing to a valid engine.
- 'engine': 'html5lib',
+ 'engine': 'draftjs_exporter.engines.html5lib.DOM_HTML5LIB',
# Or, using the shorthand.
+ 'engine': DOM.HTML5LIB,

# It's not possible either to directly provide an engine implementation - use a dotted path instead.
- DOM.use(DOMTestImpl)
+ DOM.use('tests.test_dom.DOMTestImpl')

v1.1.1

Fixed

• Fix string engine incorrectly skipping identical elements at the same depth level (#83).

v1.1.0

Added

• Add new string-based dependency-free DOM backing engine, with much better performance, thanks to the expertise of @BertrandBordage (#77).

Changed

• Pre-compile regexes in html5lib engine for performance improvements (#76).

How to upgrade

There is no need to make any changes to keep using the previous engines (html5lib, lxml). To switch to the new string engine, opt-in via the config:

exporter = HTML({
+    # Specify which DOM backing engine to use.
+    'engine': 'string',
})

v1.0.0

This release is functionally identical to the previous one, v0.9.0.

The project has reached a high-enough level of stability to be used in production, and breaking changes will now be reflected via major version changes.

v0.9.0

Added

• Add configuration options to determine handling of missing blocks #52.
• Add configuration options to determine handling of missing styles.
• Add configuration options to determine handling of missing entities.
• Block components now have access to the block type via props['block']['type'].
• Entity components now have access to the entity type via props['entity']['type'].
• Composite decorators now have access to the current block depth and data via props['block']['depth'], props['block']['data'].
• Allow discarding component children by returning None in render.
• Add support for lxml as a DOM backing engine, with pip install draftjs_exporter[lxml] pip extra.
• Add support for custom DOM backing engines.
• Add support for None content state in HTML.render #67.

Changed

• For composite decorators, the block type has moved from props['block_type'] to props['block']['type'].
• Move ConfigException to draftjs_exporter.error.

Removed

• Remove DOM.get_children method.
• Remove DOM.pretty_print method.
• Remove automatic conversion from className prop to class.

Fixed

• Stop rendering decorators when there is no text to decorate.
• Remove extra HTML serialisation steps.

How to upgrade

# Change composite decorators block type access
- props['block_type']
+ props['block']['type']
# Stop using DOM.get_children directly.
- DOM.get_children()
# Stop using DOM.pretty_print directly.
- DOM.pretty_print()
# Move `ConfigException` to `draftjs_exporter.error`.
- from draftjs_exporter.options import ConfigException
+ from draftjs_exporter.error import ConfigException
# Remove automatic conversion from `className` prop to `class` attribute.
- BLOCK_TYPES.BLOCKQUOTE: ['blockquote', {'className': 'c-pullquote'}]
+ BLOCK_TYPES.BLOCKQUOTE: ['blockquote', {'class': 'c-pullquote'}]