proforma-html-renderer 1.0.0.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79926036ed97fef2c419bbed5dfe9928bc3d015d27375365519a77d086e02046
+  data.tar.gz: 74ff658a1839b254b0ced3cdfce8e903377fdf0fd7f5cf44813d73f33f33da7e
+SHA512:
+  metadata.gz: 656f4a759082ceebeb3f0e6872db1a478b74612ea2851841c22c620b555015ec2f78256dc7e3590835d089cb99b6a98debb55e85673b69739e4f68d2bcb3b082
+  data.tar.gz: 40a291e58e3023310a9414f0238f261d479137a6e9ca092cab6fba15a4f574bdd9f6a5b916d47fcfcc89f4a5c70a9812d947737ade741ed1bb301bc29619aef5

data/.editorconfig

@@ -0,0 +1,8 @@
+# See http://editorconfig.org/
+
+[*]
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+end_of_line = lf

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+*.gem
+/tmp
+/coverage
+/pkg

data/.rubocop.yml

@@ -0,0 +1,11 @@
+Metrics/LineLength:
+  Max: 100
+
+Metrics/BlockLength:
+  ExcludedMethods: ['let', 'it', 'describe', 'context', 'specify']
+
+Metrics/MethodLength:
+  Max: 25
+
+AllCops:
+  TargetRubyVersion: 2.3

data/.ruby-version

@@ -0,0 +1 @@
+2.6.0

data/.travis.yml

@@ -0,0 +1,20 @@
+env:
+  global:
+    - CC_TEST_REPORTER_ID=90489daeea95c563237fc1b698ecc4bb2b2f421937c646ca1ee4eb1e22e03e70
+language: ruby
+rvm:
+  # Build on the latest stable of all supported Rubies (https://www.ruby-lang.org/en/downloads/):
+  - 2.3.8
+  - 2.4.5
+  - 2.5.3
+  - 2.6.0
+cache: bundler
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rubocop
+  - bundle exec rspec spec --format documentation
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 1.0.0-alpha (June 6th, 2019)
+
+Initial alpha release.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,111 @@
+PATH
+  remote: .
+  specs:
+    proforma-html-renderer (1.0.0.pre.alpha)
+      proforma (~> 1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    acts_as_hashable (1.1.0)
+    ansi (1.5.0)
+    ast (2.4.0)
+    byebug (11.0.1)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    ffi (1.9.25)
+    formatador (0.2.5)
+    guard (2.15.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    hirb (0.7.3)
+    jaro_winkler (1.5.2)
+    json (2.1.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.2)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.13.0)
+    parser (2.6.0.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    proforma (1.0.2)
+      acts_as_hashable (~> 1, >= 1.1.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-byebug (3.7.0)
+      byebug (~> 11.0)
+      pry (~> 0.10)
+    rainbow (3.0.0)
+    rake (10.5.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.63.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-console (0.4.2)
+      ansi
+      hirb
+      simplecov
+    simplecov-html (0.10.2)
+    thor (0.20.3)
+    unicode-display_width (1.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec (~> 4.7)
+  proforma-html-renderer!
+  pry (~> 0)
+  pry-byebug (~> 3)
+  rake (~> 10.0)
+  rspec (~> 3.8)
+  rubocop (~> 0.63.1)
+  simplecov (~> 0.16.1)
+  simplecov-console (~> 0.4.2)

data/Guardfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'DISABLE_SIMPLECOV=true bundle exec rspec --format=documentation' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2019 Blue Marble Payroll, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# Proforma HTML Renderer
+
+[![Gem Version](https://badge.fury.io/rb/proforma-html-renderer.svg)](https://badge.fury.io/rb/proforma-html-renderer) [![Build Status](https://travis-ci.org/bluemarblepayroll/proforma-html-renderer.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/proforma-html-renderer) [![Maintainability](https://api.codeclimate.com/v1/badges/ea2b788b45fcc7d0a183/maintainability)](https://codeclimate.com/github/bluemarblepayroll/proforma-html-renderer/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/ea2b788b45fcc7d0a183/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/proforma-html-renderer/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Proforma](https://github.com/bluemarblepayroll/proforma) ships with a basic plain-text renderer.  Luckily we can plug in different rendering engines to provide additional business value.  This library gives Proforma the ability to render HTML instead of simple plain-text.
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install proforma-html-renderer
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add proforma-html-renderer
+````
+
+Note: If you are using bundler for auto-requiring then you need to specify as:
+
+```
+gem 'proforma-html-renderer', require: 'proforma/html_renderer'
+```
+
+## Examples
+
+### Connecting to Proforma Rendering Pipeline
+
+To use this plugin within Proforma:
+
+1. Install [Proforma](https://github.com/bluemarblepayroll/proforma)
+2. Install this library
+3. Require both libraries
+4. Pass in an instance of Proforma::HtmlRenderer into the Proforma#render method
+
+````ruby
+require 'proforma'
+require 'proforma/html_renderer'
+
+data = [
+  { id: 1, name: 'Chicago Bulls' },
+  { id: 2, name: 'Indiana Pacers' },
+  { id: 3, name: 'Boston Celtics' }
+]
+
+template = {
+  title: 'nba_team_list',
+  children: [
+    { type: 'Header', value: 'NBA Teams' },
+    { type: 'Separator' },
+    {
+      type: 'DataTable',
+      columns: [
+        { header: 'Team ID #', body: '$id' },
+        { header: 'Team Name', body: '$name' },
+      ]
+    }
+  ]
+}
+
+documents = Proforma.render(data, template, renderer: Proforma::HtmlRenderer.new)
+````
+
+The `documents` attribute will now be an array with one object:
+
+```ruby
+expected_documents = [
+  {
+    contents: "...", # HTML Data
+    extension: '.html',
+    title: 'nba_team_list'
+  }
+]
+```
+
+The `contents` attribute will contain the HTML.
+
+### Customization
+
+All options are passed into Proforma::HtmlRenderer#initialize as a hash:
+
+Name                 | Default
+-------------------- | -------
+bold_weight          | bold
+font_family          | sans-serif
+header_font_size     | 18
+line_height_increase | 5
+text_font_size       | 13
+
+These options will be used during the rendering process.
+
+## Contributing
+
+### Development Environment Configuration
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check proforma-html-renderer.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/proforma-html-renderer.git)
+4. Navigate to the root folder (cd proforma)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite run:
+
+````
+bundle exec rspec spec --format documentation
+````
+
+Alternatively, you can have Guard watch for changes:
+
+````
+bundle exec guard
+````
+
+Also, do not forget to run Rubocop:
+
+````
+bundle exec rubocop
+````
+
+### Publishing
+
+Note: ensure you have proper authorization before trying to publish new versions.
+
+After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:
+
+1. Merge Pull Request into master
+2. Update `lib/proforma/html_renderer/version.rb` using [semantic versioning](https://semver.org/)
+3. Install dependencies: `bundle`
+4. Update `CHANGELOG.md` with release notes
+5. Commit & push master to remote and ensure CI builds master successfully
+6. Run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## License
+
+This project is MIT Licensed.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'proforma/html_renderer'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'pry'
+Pry.start

data/bin/render

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'bundler/setup'
+require 'pry'
+
+require_relative '../spec/rendering_helper'
+
+jobs_dir  = File.expand_path(File.join(__dir__, '..', 'tmp', 'jobs'))
+jobs      = RenderingHelper.folders(jobs_dir)
+
+if jobs.empty?
+  puts "No jobs detected in the path: #{jobs_dir}"
+  puts '-------------------------------------------------------------------'
+  puts "To use, place folders into #{jobs_dir} directory."
+  puts 'Each folder should contain a config.yml file and an images folder'
+  puts 'You can find example YAML files in: spec/fixtures/snapshot'
+  puts '-------------------------------------------------------------------'
+
+  exit
+end
+
+jobs.each do |job|
+  path = File.join(jobs_dir, job)
+  puts "Rendering: #{path}"
+  RenderingHelper.new(path).render_and_save
+end

data/bin/snapshot

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+# This script will generate the snapshot to be used for testing.
+# After modifying any internal part that changes the rendered HTML output
+# you should manually verify the output and once satisfied, use this script to
+# regenerate the snapshot.
+
+require 'bundler/setup'
+require 'pry'
+
+require_relative '../spec/rendering_helper'
+
+snapshot_dir = File.join(__dir__, '..', 'spec', 'fixtures', 'snapshot')
+
+RenderingHelper.new(snapshot_dir).render_and_save

data/lib/proforma/html_renderer/object_writer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'writer'
+
+module Proforma
+  class HtmlRenderer
+    # Each object should have its own ERB template.  This class understands the connection of
+    # objects and templates and knows how to render the template for the respective object
+    # passed in.
+    class ObjectWriter
+      attr_reader :names_by_class, :writer
+
+      def initialize(names_by_class: {}, writer: Writer.new)
+        @names_by_class = names_by_class
+        @writer         = writer
+      end
+
+      def render(object, options = {})
+        writer.render(
+          resolve_name(object),
+          object: object,
+          options: options
+        )
+      end
+
+      private
+
+      def resolve_name(object)
+        names_by_class[object.class].tap do |name|
+          raise ArgumentError, "object cannot be rendered: #{object.class}" unless name
+        end
+      end
+    end
+  end
+end

data/lib/proforma/html_renderer/proforma_writer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'object_writer'
+
+module Proforma
+  class HtmlRenderer
+    # This class connects each Proforma object to its proper template for rendering.
+    class ProformaWriter
+      extend Forwardable
+
+      # The singleton is provided as a global helper since we want to expose the same
+      # static functionality across the entire app.  The real value is the caching of the
+      # Writer's files so we are only reading each template the initial time.
+      class << self
+        extend Forwardable
+
+        def_delegators :instance, :render
+
+        def instance
+          @instance ||= new
+        end
+      end
+
+      NAMES_BY_CLASS = {
+        Modeling::Banner => 'banner.html.erb',
+        Modeling::Header => 'header.html.erb',
+        Modeling::Pane => 'pane.html.erb',
+        Modeling::Separator => 'separator.html.erb',
+        Modeling::Spacer => 'spacer.html.erb',
+        Modeling::Table => 'table.html.erb',
+        Modeling::Text => 'text.html.erb',
+        Prototype => 'prototype.html.erb'
+      }.freeze
+
+      attr_reader :object_writer
+
+      def_delegators :object_writer, :render
+
+      def initialize(object_writer: ObjectWriter.new(names_by_class: NAMES_BY_CLASS))
+        @object_writer = object_writer
+      end
+    end
+  end
+end

data/lib/proforma/html_renderer/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Proforma
+  class HtmlRenderer
+    VERSION = '1.0.0-alpha'
+  end
+end

data/lib/proforma/html_renderer/writer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Proforma
+  class HtmlRenderer
+    # This class can render ERB templates.
+    class Writer
+      # This nested class is an internal intermediate only used by the encapsulating Writer class.
+      # It is simply used to convert an OpenStruct object to a Binding object which can be used
+      # for ERB template rendering.
+      class ErbBinding < OpenStruct
+        def expose_binding
+          binding
+        end
+      end
+
+      BACK_DIR      = '..'
+      ERB_OPTIONS   = '-'
+      TEMPLATE_DIR  = 'templates'
+
+      def initialize(directory: nil, files: {})
+        @directory  = directory || default_directory
+        @files      = to_erb_hash(files)
+      end
+
+      def render(name, context = {})
+        erb_template(name).result(hash_to_binding(context))
+      end
+
+      private
+
+      attr_reader :directory, :files
+
+      def hash_to_binding(hash)
+        ErbBinding.new(hash).expose_binding
+      end
+
+      def erb_template(name)
+        files[name.to_s] ||= read(name)
+      end
+
+      def read(name)
+        text = IO.read(path(name)).chop
+        ERB.new(text, nil, ERB_OPTIONS)
+      end
+
+      def default_directory
+        File.join(
+          __dir__,
+          BACK_DIR,
+          BACK_DIR,
+          BACK_DIR,
+          TEMPLATE_DIR
+        )
+      end
+
+      def path(name)
+        File.join(directory, name.to_s)
+      end
+
+      def to_erb_hash(hash)
+        (hash || {}).map do |(name, file)|
+          [
+            name.to_s,
+            file.is_a?(ERB) ? file : ERB.new(file)
+          ]
+        end.to_h
+      end
+    end
+  end
+end

data/lib/proforma/html_renderer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'base64'
+require 'erb'
+require 'forwardable'
+require 'ostruct'
+require 'proforma'
+
+require_relative 'html_renderer/proforma_writer'
+
+module Proforma
+  # This main class to use as a Proforma renderer.
+  class HtmlRenderer
+    EXTENSION = '.html'
+
+    DEFAULT_OPTIONS = {
+      bold_weight: 'bold',
+      font_family: 'sans-serif',
+      header_font_size: 18,
+      line_height_increase: 5,
+      text_font_size: 13
+    }.freeze
+
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = OpenStruct.new(DEFAULT_OPTIONS.merge(options))
+    end
+
+    def render(prototype)
+      contents = ProformaWriter.render(prototype, options)
+
+      Proforma::Document.new(
+        contents: contents,
+        extension: EXTENSION,
+        title: prototype.title
+      )
+    end
+  end
+end