DraftjsHtml

If the direct mapping from :inline_style_mapping isn't enough, you can supply a custom function for rendering a style range. This function, when provided, will be called with all applicable styles for a range, and the relevant content/text for that range. It bears stressing that this #call-able will be called with all defined styles for the content/character range. This means that by declaring this function, you take responsibility for handling all styles for that range. However, if you "return" nil (or false-y) from the proc, it will fallback to the standard "mapping" fucntionality.

DraftjsHtml.to_html(raw_draftjs, options: {
  inline_style_renderer: ->(style_names, content) {
    next if style_names != ['CUSTOM']
    Nokogiri::XML::Node.new('pre', document).tap do |node|
      node.content = content
    end
  },
})

# This would use the default inline style rendering UNLESS the *only* applied style for this range was "CUSTOM"

Working with user-generated content can be a dangerous thing. While it allows for a lot of flexibility, it also creates some potential attack vectors that you need to be aware of. We try to take a "safe by default" stance with this library, and not generate HTML that could be dangerous when we know better.

To facilitate this, we require a little work from you, dear programmer. Namely, when specifying special algorithms for generating entities or inline styles, you need to help us keep you safe. You can do this by returning a Nokogiri::XML::Node or DraftjsHtml::Node from any functions you provide that generate HTML. This is similar to Ruby on Rails' #to_html method, but rather than a monkeypatch, we chose to provide a "marker class" (classes) that we know are safe. These classes will handle escaping, encoding, and otherwise "safe generation" for you. If you, on the other hand, return a bare String from one of the custom render functions, we assume it's unsafe and encode it.

That is, a function like this:

->(entity, content, document) do
  "<p>hi!</p>"
end
# will become an HTML-entity escaped string (e.g. "&lt;p&gt;hi!&lt;/p&gt;")

Where, a function like this:

->(entity, content, document) do
  DraftjsHtml::Node.new('p', {}, 'hi!')
end
# will nest HTML nodes as you probably want (e.g. "<p>hi!</p>")

As an experiment, this gem is providing the ability to convert from HTML to raw DraftJS JSON. You can explore this behavior with the following snippet:

DraftjsHtml.from_html("<p>Hello!</p>") # => { "blocks" => [{ "text": "Hello!", "type" => "unstyled" } ] }

There are some known limitations with this approach, but, if you're just trying to get started, it may be good enough for you. Contributions and issue reports are welcome and encouraged.

This FromHtml option allows the user to specify how a particular node is converted to a DraftJS entity. By default, the library converts img and a tags to IMAGE and LINK entities, respectively. If you specify this option, you override the existing behavior and must define those conversions yourself.

The option expects a callable (proc, lambda, etc) that receives 3 arguments:

• tagname (e.g. a) - always downcased
• content - the text content inside the tag
• HTML attributes - any HTML attributes on the tag as a Hash (string keys)

The callable should return a Hash with symbol keys. The supported values are:

• type (required)
  • the entity "type" or name
• mutability (optional, default 'IMMUTABLE')
  • either 'MUTABLE', 'IMMUTABLE', or 'SEGMENTED'
• atomic (optional, default false)
  • when true, creates a new "atomic" block for this entity rather than apply the entity to the current range
• data (optional, default {})
  • an arbitrary data-bag (Hash) of entity data

If you want to directly manipulate the structure of the Draftjs, you can use the DraftjsHtml::Draftjs.parse(raw_draftjs) directly. This method assumes that the raw_draftjs hash is well-formed & valid, containing the "blocks" and "entityMap" keys.

If you’re dealing with unknown input, you can use .safe_parse instead to return a guaranteed, benign object. See DraftjsHtml::Draftjs::NullContent for its implementation – the API matches that of DraftjsHtml::Draftjs::Content.

Note: Neither of the parse methods parse JSON strings, they expect Ruby hash objects.

These parsed objects support rudimentary validation. Note that the DraftjsHtml::Draftjs::NullContent version always presents as invalid.

To make it easier to test our own code, we've developed a few RSpec matchers that make normalization and comparison of raw DraftJS use the RawBuilder DSL. To take advantage of this, you can (for RSpec only, currently) include the following in your spec_helper, or equivalent.

require 'draftjs_html/spec_support/rspec'

RSpec.configure do |config|
  config.include DraftjsHtml::SpecSupport::RSpecMatchers
end

Then, later in your tests, you can assert on raw DraftJS "json" like this:

my_raw_draftjs_hash = { blocks: [{ key: 'a-random-uuid', text: 'Hi!' }], entityMap: {} }

expect(my_raw_draftjs_hash).to eq_raw_draftjs {
  text_block 'Hi!'
}

This will normalize the key values and other IDs to make actual differences easier to spot.

There's also a matcher called eq_raw_draftjs_ignoring_keys that takes an explicit raw DraftJS hash on both sides.

my_raw_draftjs_hash = { blocks: [{ key: 'a-random-uuid', text: 'Hi!' }], entityMap: {} }
my_other_draftjs_hash = { blocks: [{ key: 'a-different-random-uuid', text: 'Hi!' }], entityMap: {} }

expect(my_raw_draftjs_hash).to eq_raw_draftjs_ignoring_keys my_other_draftjs_hash

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/dugancathal/draftjs_html. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the DraftjsHtml project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.