prawn-html 0.1.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a671ae12f6a66358c10f739404ab709f3fdcaacb059b9943433a7535a539a5
-  data.tar.gz: 274afa7a2d6cbb2a75e1ca03e2b82ee38985bf279f41ecd3878166ce9eabf15a
+  metadata.gz: 998ac3f3429812cc60dfe2bdf0184a86c116b1b80c7522376f99e044f185207c
+  data.tar.gz: 1a4ce4f9055fa8dd8ed121665102698b6077d69986974c366098d69759555d80
 SHA512:
-  metadata.gz: a67e743e2c77c1b0e9caecefd9b6f1fc2d33243d0b86b37548f5bbed7e8e569ea11562d849c82fbdfd8ca7eeb5bdf2921cf789464868f0e90de4b631dcf89a10
-  data.tar.gz: dd06b9b0410cceb28eaf68ab6eaeb6007086047478f3ec1ba2ffd37a0a38de38264f56fae3232b4025a5d6f45b776fe2d79bb23eb76926a8a87139e82294e14d
+  metadata.gz: d443116a4be710f698f02da8092b19b0d83f9b319c0e7b431ae9cfe67d11c208ddea48ff5c995057bd3b28056dafcb2ff8461c1ad3be8134f9dcaa926b96ef73
+  data.tar.gz: 530a30ff700f75312a5f72b38ef433f9f03a3eab9ac9d83297a3eacc20d680df4ab1f8a4bc3c5134146b3da71be6ffa23d151bc71824dc21022fe7c5aa592758

data/README.md

@@ -1,29 +1,38 @@
 # Prawn HTML
+[![gem version](https://badge.fury.io/rb/prawn-html.svg)](https://rubygems.org/gems/prawn-html)
 [![linters](https://github.com/blocknotes/prawn-html/actions/workflows/linters.yml/badge.svg)](https://github.com/blocknotes/prawn-html/actions/workflows/linters.yml)
 [![specs](https://github.com/blocknotes/prawn-html/actions/workflows/specs.yml/badge.svg)](https://github.com/blocknotes/prawn-html/actions/workflows/specs.yml)
 
 HTML to PDF renderer using [Prawn PDF](https://github.com/prawnpdf/prawn).
 
-> Still in beta. [prawn-styled-text](https://github.com/blocknotes/prawn-styled-text) rewritten from scratch
+Features:
+- support a [good set](#supported-tags--attributes) of HTML tags and CSS properties;
+- handle [document styles](#document-styles);
+- custom [data attributes](#data-attributes) for Prawn PDF features;
+- no extra settings: it just parses an input HTML and outputs to a Prawn PDF document.
 
-**Notice**: render HTML documents properly is not an easy task, this gem support only some HTML tags and a small set of CSS attributes. If you need more rendering accuracy take a look at other projects like WickedPDF.
+**Notice**: render HTML documents properly is not an easy task, this gem support only some HTML tags and a small set of CSS attributes. If you need more rendering accuracy take a look at other projects like *WickedPDF* or *PDFKit*.
+
+> [prawn-styled-text](https://github.com/blocknotes/prawn-styled-text) rewritten from scratch, finally!
 
 Please :star: if you like it.
 
 ## Install
 
-- Add to your Gemfile: `gem 'prawn-html', git: 'https://github.com/blocknotes/prawn-html.git'` (and execute `bundle`)
-- Use the class `HtmlHandler` on a `Prawn::Document` instance
+- Add to your Gemfile: `gem 'prawn-html'` (and execute `bundle`)
+- Just call `PrawnHtml.append_html` on a `Prawn::Document` instance (see the examples)
 
 ## Examples
 
 ```rb
 require 'prawn-html'
 pdf = Prawn::Document.new(page_size: 'A4')
-PrawnHtml::HtmlHandler.new(pdf).process('<h1 style="text-align: center">Just a test</h1>')
+PrawnHtml.append_html(pdf, '<h1 style="text-align: center">Just a test</h1>')
 pdf.render_file('test.pdf')
 ```
 
+To check some examples with the PDF output see [examples](examples/) folder.
+
 ## Supported tags & attributes
 
 HTML tags:
@@ -41,34 +50,104 @@ HTML tags:
 - **img**: image
 - **li**: list item
 - **mark**: highlight
+- **ol**: ordered list
 - **p**: block element
 - **s**: strike-through
 - **small**: smaller text
 - **span**: inline element
 - **strong**: bold
 - **u**: underline
-- **ul**: list
+- **ul**: unordered list
 
 CSS attributes (dimensional units are ignored and considered in pixel):
 
-- **background**: for *mark* tag, only 3 or 6 hex digits format, ex. `style="background: #FECD08"`
-- **color**: only 3 or 6 hex digits format - ex. `style="color: #FB1"`
+- **background**: for *mark* tag (3/6 hex digits or RGB or color name), ex. `style="background: #FECD08"`
+- **break-after**: go to a new page after some elements, ex. `style="break-after: auto"`
+- **break-before**: go to a new page before some elements, ex. `style="break-before: auto"`
+- **color**: (3/6 hex digits or RGB or color name) ex. `style="color: #FB1"`
 - **font-family**: font must be registered, quotes are optional, ex. `style="font-family: Courier"`
 - **font-size**: ex. `style="font-size: 20px"`
 - **font-style**: values: *:italic*, ex. `style="font-style: italic"`
 - **font-weight**: values: *:bold*, ex. `style="font-weight: bold"`
 - **height**: for *img* tag, ex. `<img src="image.jpg" style="height: 200px"/>`
 - **href**: for *a* tag, ex. `<a href="http://www.google.com/">Google</a>`
+- **left**: see *position (absolute)*
 - **letter-spacing**: ex. `style="letter-spacing: 1.5"`
 - **line-height**: ex. `style="line-height: 10px"`
+- **list-style-type**: for *ul*, a string, ex. `style="list-style-type: '- '"`
 - **margin-bottom**: ex. `style="margin-bottom: 10px"`
 - **margin-left**: ex. `style="margin-left: 15px"`
 - **margin-top**: ex. `style="margin-top: 20px"`
+- **position**: `absolute`, ex. `style="position: absolute; left: 20px; top: 100px"`
 - **src**: for *img* tag, ex. `<img src="image.jpg"/>`
 - **text-align**: `left` | `center` | `right` | `justify`, ex. `style="text-align: center"`
 - **text-decoration**: `underline`, ex. `style="text-decoration: underline"`
+- **top**: see *position (absolute)*
 - **width**: for *img* tag, support also percentage, ex. `<img src="image.jpg" style="width: 50%; height: 200px"/>`
 
+For colors, the supported formats are:
+- 3 hex digits, ex. `color: #FB1`;
+- 6 hex digits, ex. `color: #abcdef`;
+- RGB, ex. `color: RGB(64, 0, 128)`;
+- color name, ex. `color: yellow`.
+
+## Data attributes
+
+Some custom data attributes are used to pass options:
+
+- **dash**: for *hr* tag, accepts an integer or a list of integers), ex. `data-data="2, 4, 3"`
+- **mode**: allow to specify the text mode (stroke|fill||fill_stroke), ex. `data-mode="stroke"`
+
+## Document styles
+
+[Experimental feature] You can define document CSS rules inside an _head_ tag, but with a limited support for now.
+Only single CSS selectors and basic ones are supported. Example:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>A test</title>
+  <style>
+    body { color: #abbccc }
+    .green {
+      color: #0f0;
+      font-family: Courier;
+    }
+    #test-1 { font-weight: bold }
+  </style>
+</head>
+<body>
+  <div class="green">
+    Div content
+    <span id="test-1">Span content</span>
+  </div>
+</body>
+</html>
+```
+
+## Additional notes
+
+### Rails: generate PDF on the fly
+
+Sample controller's action to create a PDF from Rails:
+
+```rb
+class SomeController < ApplicationController
+  def sample_action
+    respond_to do |format|
+      format.pdf do
+        pdf = Prawn::Document.new
+        PrawnHtml.append_html(pdf, '<h1 style="text-align: center">Just a test</h1>')
+        send_data(pdf.render, filename: 'sample.pdf', type: 'application/pdf')
+      end
+    end
+  end
+end
+```
+
+More details in this blogpost: [generate PDF from HTML](https://www.blocknot.es/2021-08-20-rails-generate-pdf-from-html/)
+
 ## Do you like it? Star it!
 
 If you use this component just star it. A developer is more motivated to improve a project when there is some interest.

data/lib/prawn-html.rb

@@ -1,17 +1,179 @@
 # frozen_string_literal: true
 
+module PrawnHtml
+  PX = 0.66 # conversion constant for pixel sixes
+
+  COLORS = {
+    'aliceblue' => 'f0f8ff',
+    'antiquewhite' => 'faebd7',
+    'aqua' => '00ffff',
+    'aquamarine' => '7fffd4',
+    'azure' => 'f0ffff',
+    'beige' => 'f5f5dc',
+    'bisque' => 'ffe4c4',
+    'black' => '000000',
+    'blanchedalmond' => 'ffebcd',
+    'blue' => '0000ff',
+    'blueviolet' => '8a2be2',
+    'brown' => 'a52a2a',
+    'burlywood' => 'deb887',
+    'cadetblue' => '5f9ea0',
+    'chartreuse' => '7fff00',
+    'chocolate' => 'd2691e',
+    'coral' => 'ff7f50',
+    'cornflowerblue' => '6495ed',
+    'cornsilk' => 'fff8dc',
+    'crimson' => 'dc143c',
+    'cyan' => '00ffff',
+    'darkblue' => '00008b',
+    'darkcyan' => '008b8b',
+    'darkgoldenrod' => 'b8860b',
+    'darkgray' => 'a9a9a9',
+    'darkgreen' => '006400',
+    'darkgrey' => 'a9a9a9',
+    'darkkhaki' => 'bdb76b',
+    'darkmagenta' => '8b008b',
+    'darkolivegreen' => '556b2f',
+    'darkorange' => 'ff8c00',
+    'darkorchid' => '9932cc',
+    'darkred' => '8b0000',
+    'darksalmon' => 'e9967a',
+    'darkseagreen' => '8fbc8f',
+    'darkslateblue' => '483d8b',
+    'darkslategray' => '2f4f4f',
+    'darkslategrey' => '2f4f4f',
+    'darkturquoise' => '00ced1',
+    'darkviolet' => '9400d3',
+    'deeppink' => 'ff1493',
+    'deepskyblue' => '00bfff',
+    'dimgray' => '696969',
+    'dimgrey' => '696969',
+    'dodgerblue' => '1e90ff',
+    'firebrick' => 'b22222',
+    'floralwhite' => 'fffaf0',
+    'forestgreen' => '228b22',
+    'fuchsia' => 'ff00ff',
+    'gainsboro' => 'dcdcdc',
+    'ghostwhite' => 'f8f8ff',
+    'gold' => 'ffd700',
+    'goldenrod' => 'daa520',
+    'gray' => '808080',
+    'green' => '008000',
+    'greenyellow' => 'adff2f',
+    'grey' => '808080',
+    'honeydew' => 'f0fff0',
+    'hotpink' => 'ff69b4',
+    'indianred' => 'cd5c5c',
+    'indigo' => '4b0082',
+    'ivory' => 'fffff0',
+    'khaki' => 'f0e68c',
+    'lavender' => 'e6e6fa',
+    'lavenderblush' => 'fff0f5',
+    'lawngreen' => '7cfc00',
+    'lemonchiffon' => 'fffacd',
+    'lightblue' => 'add8e6',
+    'lightcoral' => 'f08080',
+    'lightcyan' => 'e0ffff',
+    'lightgoldenrodyellow' => 'fafad2',
+    'lightgray' => 'd3d3d3',
+    'lightgreen' => '90ee90',
+    'lightgrey' => 'd3d3d3',
+    'lightpink' => 'ffb6c1',
+    'lightsalmon' => 'ffa07a',
+    'lightseagreen' => '20b2aa',
+    'lightskyblue' => '87cefa',
+    'lightslategray' => '778899',
+    'lightslategrey' => '778899',
+    'lightsteelblue' => 'b0c4de',
+    'lightyellow' => 'ffffe0',
+    'lime' => '00ff00',
+    'limegreen' => '32cd32',
+    'linen' => 'faf0e6',
+    'magenta' => 'ff00ff',
+    'maroon' => '800000',
+    'mediumaquamarine' => '66cdaa',
+    'mediumblue' => '0000cd',
+    'mediumorchid' => 'ba55d3',
+    'mediumpurple' => '9370db',
+    'mediumseagreen' => '3cb371',
+    'mediumslateblue' => '7b68ee',
+    'mediumspringgreen' => '00fa9a',
+    'mediumturquoise' => '48d1cc',
+    'mediumvioletred' => 'c71585',
+    'midnightblue' => '191970',
+    'mintcream' => 'f5fffa',
+    'mistyrose' => 'ffe4e1',
+    'moccasin' => 'ffe4b5',
+    'navajowhite' => 'ffdead',
+    'navy' => '000080',
+    'oldlace' => 'fdf5e6',
+    'olive' => '808000',
+    'olivedrab' => '6b8e23',
+    'orange' => 'ffa500',
+    'orangered' => 'ff4500',
+    'orchid' => 'da70d6',
+    'palegoldenrod' => 'eee8aa',
+    'palegreen' => '98fb98',
+    'paleturquoise' => 'afeeee',
+    'palevioletred' => 'db7093',
+    'papayawhip' => 'ffefd5',
+    'peachpuff' => 'ffdab9',
+    'peru' => 'cd853f',
+    'pink' => 'ffc0cb',
+    'plum' => 'dda0dd',
+    'powderblue' => 'b0e0e6',
+    'purple' => '800080',
+    'rebeccapurple' => '663399',
+    'red' => 'ff0000',
+    'rosybrown' => 'bc8f8f',
+    'royalblue' => '4169e1',
+    'saddlebrown' => '8b4513',
+    'salmon' => 'fa8072',
+    'sandybrown' => 'f4a460',
+    'seagreen' => '2e8b57',
+    'seashell' => 'fff5ee',
+    'sienna' => 'a0522d',
+    'silver' => 'c0c0c0',
+    'skyblue' => '87ceeb',
+    'slateblue' => '6a5acd',
+    'slategray' => '708090',
+    'slategrey' => '708090',
+    'snow' => 'fffafa',
+    'springgreen' => '00ff7f',
+    'steelblue' => '4682b4',
+    'tan' => 'd2b48c',
+    'teal' => '008080',
+    'thistle' => 'd8bfd8',
+    'tomato' => 'ff6347',
+    'turquoise' => '40e0d0',
+    'violet' => 'ee82ee',
+    'wheat' => 'f5deb3',
+    'white' => 'ffffff',
+    'whitesmoke' => 'f5f5f5',
+    'yellow' => 'ffff00',
+    'yellowgreen' => '9acd32'
+  }.freeze
+
+  def append_html(pdf, html)
+    pdf_wrapper = PdfWrapper.new(pdf)
+    renderer = DocumentRenderer.new(pdf_wrapper)
+    html_parser = PrawnHtml::HtmlParser.new(renderer)
+    html_parser.process(html)
+  end
+
+  module_function :append_html
+end
+
 require 'prawn'
 
-require 'prawn_html/tags/base'
-Dir["#{__dir__}/prawn_html/tags/*.rb"].sort.each { |f| require f }
+require 'prawn_html/utils'
 
+require 'prawn_html/tag'
+Dir["#{__dir__}/prawn_html/tags/*.rb"].sort.each { |f| require f }
 Dir["#{__dir__}/prawn_html/callbacks/*.rb"].sort.each { |f| require f }
 
 require 'prawn_html/attributes'
 require 'prawn_html/context'
+require 'prawn_html/pdf_wrapper'
 require 'prawn_html/document_renderer'
-require 'prawn_html/html_handler'
-
-module PrawnHtml
-  PX = 0.66 # conversion costant for pixel sixes
-end
+require 'prawn_html/html_parser'

data/lib/prawn_html/attributes.rb

@@ -3,124 +3,100 @@
 require 'ostruct'
 
 module PrawnHtml
-  class Attributes
-    attr_reader :hash, :options, :post_styles, :pre_styles, :styles
+  class Attributes < OpenStruct
+    attr_reader :styles
+
+    STYLES_APPLY = {
+      block: %i[align leading left margin_left padding_left position top],
+      tag_close: %i[margin_bottom padding_bottom break_after],
+      tag_open: %i[margin_top padding_top break_before],
+      text_node: %i[background callback character_spacing color font link list_style_type size styles]
+    }.freeze
 
     STYLES_LIST = {
-      # styles
-      'background' => { key: :background, set: :convert_color, dest: :styles },
-      'color' => { key: :color, set: :convert_color, dest: :styles },
-      'font-family' => { key: :font, set: :unquote, dest: :styles },
-      'font-size' => { key: :size, set: :convert_size, dest: :styles },
-      'font-style' => { key: :styles, set: :append_symbol, dest: :styles },
-      'font-weight' => { key: :styles, set: :append_symbol, dest: :styles },
-      'letter-spacing' => { key: :character_spacing, set: :convert_float, dest: :styles },
-      # pre styles
-      'margin-top' => { key: :margin_top, set: :convert_size, dest: :pre_styles },
-      # post styles
-      'margin-bottom' => { key: :margin_bottom, set: :convert_size, dest: :post_styles },
-      'padding-bottom' => { key: :padding_bottom, set: :convert_size, dest: :post_styles },
-      # options
-      'line-height' => { key: :leading, set: :convert_size, dest: :options },
-      'margin-left' => { key: :margin_left, set: :convert_size, dest: :options },
-      'padding-left' => { key: :padding_left, set: :convert_size, dest: :options },
-      'padding-top' => { key: :padding_top, set: :convert_size, dest: :options },
-      'text-align' => { key: :align, set: :convert_symbol, dest: :options },
-      'text-decoration' => { key: :styles, set: :append_symbol, dest: :styles }
+      # text node styles
+      'background' => { key: :background, set: :convert_color },
+      'callback' => { key: :callback, set: :copy_value },
+      'color' => { key: :color, set: :convert_color },
+      'font-family' => { key: :font, set: :unquote },
+      'font-size' => { key: :size, set: :convert_size },
+      'font-style' => { key: :styles, set: :append_symbol },
+      'font-weight' => { key: :styles, set: :append_symbol },
+      'href' => { key: :link, set: :copy_value },
+      'letter-spacing' => { key: :character_spacing, set: :convert_float },
+      'list-style-type' => { key: :list_style_type, set: :unquote },
+      'text-decoration' => { key: :styles, set: :append_symbol },
+      # tag opening styles
+      'break-before' => { key: :break_before, set: :convert_symbol },
+      'margin-top' => { key: :margin_top, set: :convert_size },
+      'padding-top' => { key: :padding_top, set: :convert_size },
+      # tag closing styles
+      'break-after' => { key: :break_after, set: :convert_symbol },
+      'margin-bottom' => { key: :margin_bottom, set: :convert_size },
+      'padding-bottom' => { key: :padding_bottom, set: :convert_size },
+      # block styles
+      'left' => { key: :left, set: :convert_size },
+      'line-height' => { key: :leading, set: :convert_size },
+      'margin-left' => { key: :margin_left, set: :convert_size },
+      'padding-left' => { key: :padding_left, set: :convert_size },
+      'position' => { key: :position, set: :convert_symbol },
+      'text-align' => { key: :align, set: :convert_symbol },
+      'top' => { key: :top, set: :convert_size }
     }.freeze
 
     STYLES_MERGE = %i[margin_left padding_left].freeze
 
     # Init the Attributes
-    #
-    # @param attributes [Hash] hash of attributes to parse
-    def initialize(attributes)
-      @hash = ::OpenStruct.new(attributes)
-      @options = {}
-      @post_styles = {}
-      @pre_styles = {}
+    def initialize(attributes = {})
+      super
       @styles = {} # result styles
-      parsed_styles = Attributes.parse_styles(hash.style)
-      process_styles(parsed_styles)
+      return unless style
+
+      styles_hash = Attributes.parse_styles(style)
+      process_styles(styles_hash)
     end
 
-    # Processes the styles attributes
+    # Processes the data attributes
     #
-    # @param attributes [Hash] hash of styles attributes
-    def process_styles(styles)
-      styles.each do |key, value|
-        rule = STYLES_LIST[key]
-        next unless rule
-
-        apply_rule(rule, value)
+    # @return [Hash] hash of data attributes with 'data-' prefix removed and stripped values
+    def data
+      to_h.each_with_object({}) do |(key, value), res|
+        data_key = key.match /\Adata-(.+)/
+        res[data_key[1]] = value.strip if data_key
       end
     end
 
-    class << self
-      # Converts a color string
-      #
-      # @param value [String] HTML string color
-      #
-      # @return [String] adjusted string color
-      def convert_color(value)
-        val = value&.downcase || +''
-        val.gsub!(/[^a-f0-9]/, '')
-        return val unless val.size == 3
-
-        a, b, c = val.chars
-        a * 2 + b * 2 + c * 2
-      end
-
-      # Converts a decimal number string
-      #
-      # @param value [String] string decimal
-      #
-      # @return [Float] converted and rounded float number
-      def convert_float(value)
-        val = value&.gsub(/[^0-9.]/, '') || ''
-        val.to_f.round(4)
-      end
-
-      # Converts a size string
-      #
-      # @param value [String] size string
-      # @param container_size [Numeric] container size
-      #
-      # @return [Float] converted and rounded size
-      def convert_size(value, container_size = nil)
-        val = value&.gsub(/[^0-9.]/, '') || ''
-        val =
-          if container_size && value.include?('%')
-            val.to_f * container_size * 0.01
-          else
-            val.to_f * PX
-          end
-        # pdf.bounds.height
-        val.round(4)
-      end
+    # Merge already parsed styles
+    #
+    # @param parsed_styles [Hash] hash of parsed styles
+    def merge_styles!(parsed_styles)
+      @styles.merge!(parsed_styles)
+    end
 
-      # Converts a string to symbol
-      #
-      # @param value [String] string
-      #
-      # @return [Symbol] symbol
-      def convert_symbol(value)
-        value.to_sym if value && !value.match?(/\A\s*\Z/)
+    # Processes the styles attributes
+    #
+    # @param styles_hash [Hash] hash of styles attributes
+    def process_styles(styles_hash)
+      styles_hash.each do |key, value|
+        apply_rule!(@styles, STYLES_LIST[key], value)
       end
+      @styles
+    end
 
+    class << self
       # Merges attributes
       #
-      # @param hash [Hash] target attributes hash
+      # @param attributes [Hash] target attributes hash
       # @param key [Symbol] key
       # @param value
       #
       # @return [Hash] the updated hash of attributes
-      def merge_attr!(hash, key, value)
+      def merge_attr!(attributes, key, value)
         return unless key
-        return (hash[key] = value) unless Attributes::STYLES_MERGE.include?(key)
+        return (attributes[key] = value) unless Attributes::STYLES_MERGE.include?(key)
 
-        hash[key] ||= 0
-        hash[key] += value
+        attributes[key] ||= 0
+        attributes[key] += value
       end
 
       # Parses a string of styles
@@ -131,26 +107,17 @@ module PrawnHtml
       def parse_styles(styles)
         (styles || '').scan(/\s*([^:;]+)\s*:\s*([^;]+)\s*/).to_h
       end
-
-      # Unquotes a string
-      #
-      # @param value [String] string
-      #
-      # @return [String] string without quotes at the beginning/ending
-      def unquote(value)
-        (value&.strip || +'').tap do |val|
-          val.gsub!(/\A['"]|["']\Z/, '')
-        end
-      end
     end
 
     private
 
-    def apply_rule(rule, value)
+    def apply_rule!(result, rule, value)
+      return unless rule
+
       if rule[:set] == :append_symbol
-        (send(rule[:dest])[rule[:key]] ||= []) << Attributes.convert_symbol(value)
+        (result[rule[:key]] ||= []) << Utils.convert_symbol(value)
       else
-        send(rule[:dest])[rule[:key]] = Attributes.send(rule[:set], value)
+        result[rule[:key]] = Utils.send(rule[:set], value)
       end
     end
   end