portable_text

Ruby Portable Text

A ruby library to render Portable text

This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.

You can:

• easily render default PortableText blocks in html without any configuration
• create custom block types, mark_defs. Add them or replace existing ones.
• create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
• customize each HTML node with custom attributes
• create a new serializer

This is a very early release so please open issues if something doesn't work as intended.

Installation

gem install portable_text

Usage

See Rails usage for usage in rails

PortableText::Serializer takes 2 parameters:

• content: , the portable text Array
• to: , the rendering format. It defaults to: :html

You can also use the :plain rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.

PortableText accepts 2 methods, render and convert!.

• render renders the content to the specified format defined in the to parameter. See How to render html ? for more information.
• convert! converts the content to be used by the library.
  • It is useful for debugging purposes.
  • It transforms the keys to ruby format.
  • It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.

How to render html?

Under the hood, the html renderer uses Phlex, a templating language which allows to create html in plain ruby.

content = [
  {
      "_key": "12345ffxx",
      "_type": "block",
      "children": [{ 
        "_key": "78910xxyy", 
        "_type": "span", 
        "marks": [],
        "text": "Hello world!" 
      }],
      "markDefs": [],
      "style": "h1"
    }
]

portable_text = PortableText::Serializer.new(content: content, to: :html)

# Since the HTML renderer uses Phlex, you can either include the rendering module 
# and use the render method...
include PortableText::Html::Rendering
render portable_text.render
# => <h1>Hello world!</h1>

# ... Or you can directly call the Phlex template
portable_text.render.call
# => <h1>Hello world!</h1>

Rails usage

To use the PortableText HTML serializer in rails, you need to add phlex-rails to the Gemfile.

You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.

gem 'portable_text'
gem 'phlex-rails'

Then run bundle install

Then, in a controller or a view, just use render as usual.

portable_text = PortableText::Serializer.new(content: content, to: :html)
render portable_text.render

Configuration

This library is highly customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.

Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.

So, in order to use a block type or a mark definition, one has to:

• register it in the PortableText configuration, so it can be passed as an object to the serializer
• create the template in the serializer (see HTML configuration)

Registering block types

content = [
  { 
    "_key": "12345ffxx", 
    "_type": "myType", 
    ...,
    "url": "https://www.github.com",
    "image_url": "https://www.myimage.com/my_image.jpg",
    "children": [{ 
        "_key": "78910xxyy", 
        "_type": "span", 
        "marks": [],
        "text": "Github" 
      }]
  }
]

# Under the hood, this library uses dry-initializer.
# You can use the option method to configure it easily
class MyBlock < PortableText::BlockTypes::Base
  option :url, default: proc { "" }
  option :image_url, default: proc { "" }
  # children is an inherited option so it does not need to be added here
end

# Or use plain old ruby. It needs to have attr_readers!
class MyBlock < PortableText::BlockTypes::Base
  attr_reader :url, :image_url
  
  def initialize(url: "", image_url:, **)
    super
    @url = url
    @image_url = image_url
  end
end

# PortableText transforms keys to ruby format so use conventional ruby!
# myType becomes my_type.
PortableText.config.block.types.merge! { my_block: MyBlock }

Default block types

It’s probably a good idea to leave the list block type untouched. Change at your own risk.

{ 
  block: BlockTypes::Block,
  image: BlockTypes::Image,
  list: BlockTypes::List,
  span: BlockTypes::Span
}

Registering mark definitions

It’s very similar to registering blocks. In case of doubt, refer to the block documentation.

content = [
  { 
    "_key": "12345ffxx", 
    "_type": "block", 
    ...,
    "markDefs": [{ "_key" => "456", "_type" => "newMarkDef" }],
  }
]

class NewMarkDef < PortableText::MarkDefs::Base
  option :label, default: proc { "" }
end

PortableText.config.block.mark_defs.merge! { new_mark_def: NewMarkDef }

Html Serializer configuration

After registering your block type or mark definition, you need to create its template.

Each template takes one argument, a block.

Block Type Template

# Let's use the block defined earlier in Registering block types

class Html::MyBlock < PortableText::Html::BaseComponent
  # You can include PortableText::Html::Configured 
  # to get access to the html serializer configuration helpers
  # The #config method allows you to access config values  
  # The #block_type(:key) method is a shortcut to the relevant block_type
  include PortableText::Html::Configured
  
  # This library uses dry-initializer 
  # so you can use `param` to create a simple parameter
  
  # There is no attribute_reader so `param :my_block` generates `@my_block`
  # This is recommended because some common HTML method names could conflict with
  # Phlex methods, like `title`. 
  param :my_block
 
  def view_template
    div do
      img(src: @my_block.image_url)
      link
    end
  end

  private

  def link
    a(href: @my_block.url) do 
      @my_block.children.each do |child|
        render block_type(:span).new(child, mark_defs: nil)
      end
    end
  end
end

# It needs to have the same key as the one registered before.
PortableText::Html.config.block.types.merge! { my_block: Html::MyBlock }

Mark Definition template

Each mark definition takes one argument, a mark definition registered in the configuration.

# Let's use the mark definition defined earlier in Registering mark definition

class Html::NewMarkDef < PortableText::Html::BaseComponent
  param :mark_def

  # &block is mandatory because mark definitions always contain other nodes
  def view_template(&block)
    a(href: @mark_def.url) { block.call }
  end
end

# It needs to have the same key as the one registered before.
PortableText::Html.config.block.mark_defs.merge! { new_mark_def: Html::NewMarkDef }

Customizing html nodes

Every HTML node is customizable through config and looks this way:

h1: { node: :h1 }

You can add HTML attributes by appending them. For example:

h1: { node: :h1, class: "header" }

Configuring marks

You can configure marks by updating the marks setting.

PortableText::Html.config.span.marks.merge! { strong: { node: :b,  }}

# Defaults
{ 
  strong: { node: :strong },
  em: { node: :em }
}

Configuring styles

PortableText::Html.config.block.styles.merge! { h1: { node: :h3, class: "header" }}


# Defaults
{
  h1: { node: :h1 },
  h2: { node: :h2 },
  h3: { node: :h3 },
  h4: { node: :h4 },
  h5: { node: :h5 },
  h6: { node: :h6 },
  blockquote: { node: :blockquote },
  normal: { node: :p },
  li: { node: :li }
}

Configuring list types

PortableText::Html.config.block.list_types.merge! { bullet: { node: :div }}

# Defaults
{
  bullet: { node: :ul },
  numeric: { node: :ol }
}

Adding a new serializer

You can add a new serializer by creating a new class. You then need to add it the the config.

The serializer needs to have a content method and takes a list of blocks as only parameter.

class MySerializer
  def initialize(blocks)
    @blocks = blocks
  end

  def content(**options)
    blocks.map |block|
      block.type + " - " + block.key + " - " + options[:context]
    end.join(" ")
  end
end

PortableText.config.serializers.merge! { my_serializer: MySerializer }

content = [{ "_key": "12345ffxx", "_type": "block", ... }]
serializer = PortableText::Serializer.new(content: content, to: :my_serializer)

# render forwards any keyword argument to the content method in the serializer
serializer.render(context: "readme")
# => block - 12345ffxx - readme

Acknowledgments

Thanks to Joel Drapper and Will Cosgrove for their help in building the HTML serializer!