formalizer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 94b90630cb3140399143eeefbeeee946382188fe
+  data.tar.gz: df814abe6674add20dcd7a0b714e7467d86b9338
+SHA512:
+  metadata.gz: d7484667ad6f4d7a8da81e311397a336c6911e7e88c78884cecfba91daf5146d3e58205ac06c89b7573f6ed78f7f6d2f2f77f2e2dc4f32cdedcf9f9e8b126dbf
+  data.tar.gz: 6ec3c25163f40a963dc05ca2225fb203d4e756ffec4cac155191d4f0e3c578403e1a43760e5bc627a96c2c38f988932663edef25df532282344783c5b72a5901

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Tal Yaniv
+
+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.rdoc

@@ -0,0 +1,207 @@
+= Formalizer
+
+{<img src="https://badge.fury.io/gh/talyaniv%2Fformalizer.svg" alt="GitHub version" />}[https://badge.fury.io/gh/talyaniv%2Fformalizer]
+
+{<img src="https://raw.githubusercontent.com/talyaniv/formalizer/master/test/dummy/app/assets/images/formalizer.png" alt="Formalizer flow scheme" />}[https://raw.githubusercontent.com/talyaniv/formalizer/master/test/dummy/app/assets/images/formalizer.png]
+
+== About
+
+
+Formalizer is an open-source gem for simplifying HTML-form filling and exporting:
+
+* Store blank contracts, agreements, disclosure sheets etc. as HTML templates.
+* In form templates, wrap blank data with <formalizer> tags:
+  * *before:* <code>name: ________</code>
+  * *after:* <code>name: <formalizer id="name">________</formalizer></code>
+* Get user data from any source, or simply let Formalizer generate user-input forms for you.
+* Formalizer will replace the template <formalizer> tags with user data:
+    name: <formalizer id="name">John D.</formalizer>
+* Filled forms can be exported to PDF using {Wicked PDF gem}[https://github.com/mileszs/wicked_pdf], or to raw html, for additional styling.
+ 
+== Install
+  gem install 'formalizer'
+or add to your Gemfile:
+  gem 'formalizer'
+
+== Demo
+
+Clone this repo, edit the root Gemfile and uncomment the last two lines:
+  gem 'wicked_pdf'
+  gem 'wkhtmltopdf-binary'
+
+Start the demo:
+  $ cd test/dummy
+  $ bundle install
+  $ rails server
+  $ open http://localhost:3000
+
+== Usage
+
+=== Configuration
+
+Formalizer looks for +formalizer.yml+ YAML file in config directory. If exists, it will load the configuration, otherwise, it can be configured programatically.
+
+=== Very basic example
+
+  # config/formalizer.yml
+  form_fields:
+    name:
+      name: Your full name 
+    gender:
+      name: Your gender 
+      field_type: enum
+      enumeration:
+        - Male
+        - Female
+        - Irellevant
+      default_value: 2
+  forms:
+    simple_form_example:
+      path: 'An HTML template that requires a name:<formalizer id="name" required>_____ (required)</formalizer>, and an optional gender:<formalizer id="gender">[male, female, irrelevant] (optional)</formalizer>'
+
+To fill the (only) form template, we need user input for name and gender. Here is a quick flow from user data to filled PDF file:
+
+  formalizer = Formalizer.new # will load YAML configuration
+
+  # Filling fields with values, regardless to the template form, so they can be reusable to another template form. Since we configured gender to be enum (zero based), a Female value is 1 (0 - Male, 1 - Female, 2 - Irrelevant):
+  formalizer.fill_fields({name: 'Michelle Markus', gender: 1})
+
+  # Exporting to PDF:
+  pdf_file = formalizer.export_form_to_pdf(:simple_form_example)
+
+  # Inside a controller, you can push the result to user:
+  send_data pdf_file, {filename: 'simple_form_example.pdf', disposition: 'attachment'}
+
+
+== Under the hood
+=== Forms, Form Fields and tags
+Let's say we have three different form templates:
+1. Cover Page
+2. NDA
+3. Purchase Agreement
+
+All three forms require personal user input: Full name and address. NDA and Purchase agreement also require recipient's full name and address. We end up with four fields:
+1. Full name
+2. Address
+3. Recipient's Full name
+4. Recipient's Address
+
+By having user input for all four fields, we can fill the three templates altogether and export as filled PDF or HTML files.
+
+Since Cover Page doesn't require recipient fields, we can group our forms and fields in tags:
+* *with_recipient:* forms 2 and 3, fields 3 and 4
+* *without_recipient:* form 1, fields 1 and 2
+Now, if we only fill the cover page, we don't need to pass all the fields:
+  pdf_file = formalizer.export_form_to_pdf(:cover_page, 'without_recipient')
+This will make the call more efficient, as it will pass only 'without_recipient' fields.
+
+=== Form Fields
+In YAML configuration:
+  form_fields:
+    [field_unique_id]:
+      name: (required) Text that will be displayed to user when generating an input form.
+      field_type: (optional) One of the following: text, boolean, number, enum or multiple. Default - text
+      tags: (optional) one or more tag that this field belongs to, e.g. 'without_recipient'
+      default_value: (optional) default value for filling templates without user input. Boolean field_type: true/false. Enum field_type: the selected value, zero-based.
+      enumeration: (required if field_type is enum) a list of at least two options
+
+   forms:
+     [form_unique_id]:
+       path: (required) a file path to the form, or actual form html. The file path can be absolute or relative to config directory.
+       tags: (optional) one or more tags that this form belongs to, e.g. 'without_recipient'
+
+Localization:
+form_field name and enumeration can have localized version. If not stated, Formalizer will use Application's locale (+I18n.locale+). Otherwise, use this syntax:
+  form_fields
+    gender:
+      name:
+        en: gender
+        es: género
+      field_type: enum
+      enumeration:
+        en:
+          - Male
+          - Female
+          - Irrelevant
+        es:
+          - Masculino
+          - Feminino
+          - Irrelevante
+
+== Generating user details form
+
+In the above example, we had four fields to be filled with user data. We can generate an html form for receiving input data:
+  # Creating a Formalizer instance
+  formalizer = Formalizer.new
+
+  # Formalizer::generate_fields_form locale = I18n.locale, form_action = '', tag = nil
+  simple_form = formalizer.generate_fields_form
+  # this will create a <form> with all four fields
+
+  # more specific versions:
+  localized_form = formalizer.generate_fields_form(:es)
+  form_with_action = formalizer.generate_fields_form(I18n.locale, 'post_fields')
+  partial_form = formalizer.generate_fields_form(I18n.locale, '', 'without_recipient')
+
+
+== HTML images and styles
+
+Binding happens at the server, so we need absolute file paths to images and css files. See the demo for specific code examples. Basically your html can look like this:
+  <!DOCTYPE html>
+  <html>
+  <head>
+    <title>Cover Page</title>
+        <link rel="stylesheet" type="text/css" href="/assets/form.css">
+        <meta charset="UTF-8" />
+  </head>
+  <body>
+    <div>
+      <img src='/assets/acme_logo.jpg' />
+      <img src='https://raw.githubusercontent.com/talyaniv/formalizer/master/test/dummy/app/assets/images/acme_logo.jpg' />
+      <h1>Cover Page</h1>
+      Name: <formalizer id="recipient" required>______________________________</formalizer>
+    </div>
+  </body>
+  </html>
+
+Formalizer will know how to use external URLs or find files (css and images) inside your app's assets directory. If your files reside elsewhere, you will need to give an absolute file:// link. Formalizer <b>does not</b> convert style/css url()s in the current version.
+
+== Advanced: Using Formalizer programatically
+
+So you want to skip the config file and DIY:
+
+  # Creating a Formalizer instance
+  formalizer = Formalizer.new
+  
+  # adding a form from a file, located in config directory
+  # Formalizer::add_form (symbol) id, (hash) details
+  formalizer.add_form(:form1, {path: 'form1.html'})
+
+  # creating a field
+  # Formalizer::add_form_field (hash) details
+  formalizer.add_form_field({id: :field1, name: 'email'})
+
+  # filling the template with user input
+  # Formalizer::field_field (Symbol) field_id, field_value
+  formalizer.fill_field :field1, 'john@doe.com'
+
+  # Exporting
+  formalizer.export_form_to_pdf(:form1)
+
+== Contributing to Formazlizer
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. Tests are important for future stability! Run tests before pushing.
+* If you uncommented the root Gemfile, remember to comment it again.
+* Feel free to email and report issues!
+
+== TODO:
+* Parse style/css url() directives
+* Sign documents with external API, e.g. Docusign
+
+== Copyright
+
+Copyright (c) 2015 Tal Yaniv. See MIT-LICENSE for further details.

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Formalizer'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/formalizer/errors.rb

@@ -0,0 +1,15 @@
+class Formalizer
+  class FormFieldParamMissing < StandardError; end
+  class NotUniqueId < StandardError; end
+  class WrongValueClass < StandardError; end
+  class WrongValue < StandardError; end
+  class FileNotFound < StandardError; end
+  class WrongFileContent < StandardError; end
+  class WrongFormTemplate < StandardError; end
+  class FormFillError < StandardError; end
+  class RequiredField < StandardError; end
+  class FormTemplateError < StandardError; end
+  class ConfigError < StandardError; end
+  class PathOrHtmlRequired < StandardError; end
+  class FieldNotFound < StandardError; end
+end

data/lib/formalizer/form.rb

@@ -0,0 +1,127 @@
+class Formalizer
+
+
+  # Holds a single form template and its binding
+
+  class Form
+
+    # Constructor
+    # * +id+ - Unique textal identifier for the form
+    # * +path_or_html+ - Either a path to a template html file, or a raw html
+
+    def initialize id, path_or_html
+      validate id, path_or_html
+      parse(path_or_html)
+      validate_template
+      @id = id
+    end
+
+
+    # Binds fields to a template
+    # * +fields+ - Hash of id => FormField object. Fields that do not exist in the form will be ignored.
+    # * Raises an error if a required field is not present in the fields param,
+    #   or if it is present but doesn't have a value.
+
+    def fill fields
+      raise TypeError unless fields.is_a?(Hash)
+
+      @html_template.css('formalizer').each do |html_field|
+        field_id = html_field.attributes['id'].value
+        form_field = fields[field_id.to_sym]
+
+        # raising error if field is required but not found in fields param, otherwise skipping this field
+        if form_field.nil?
+          required_attribute = html_field.attributes['required']
+          field_required = !required_attribute.nil? && (required_attribute.value == '' || required_attribute.value == 'true')
+          raise RequiredField, "field #{field_id} is required" if field_required
+          next
+        end
+
+        # field found in field params, so we don't care if it's required or not
+        html_field.content = form_field.value
+
+      end
+    end
+
+
+    # Exports the filled form into a PDF file uwing Wicked PDF gem
+
+    def export_to_pdf filename = 'pdf'
+      # replacing html image tags with wicked_pdf tags
+      html = @html_template.to_s
+      @html_template.css('img').each do |image_tag|
+        html.gsub!(image_tag.to_s, replace_tag(image_tag, 'src'))
+      end
+      @html_template.css('link').each do |rel_tag|
+        html.gsub!(rel_tag.to_s, replace_tag(rel_tag, 'href'))
+      end
+      WickedPdf.new.pdf_from_string(html)
+    end
+
+
+    # Exports the filled form into a raw html string
+
+    def export_to_html
+      @html_template.to_s
+    end
+
+
+    # Private methods
+
+    private
+
+
+    # Validates initializer.
+    # Raises errors if cannot initialize form from path or raw html
+    # * +id+ - Unique textal identifier for the form
+    # * +path_or_html+ - Either a path to a template html file, or a raw html
+
+    def validate id, path_or_html
+      unless (id.is_a?String) || (id.is_a?Symbol)
+        raise WrongValueClass, 'form id should be a String or Symbol'
+      end
+      raise WrongValueClass, 'path/html should be a String' unless path_or_html.is_a?String
+    end
+
+
+    # Parses the path/html into a final html template,
+    # Creates and fills @html_template variable for further binding.
+    # * +path_or_html+ - Either a path to a template html file, or a raw html
+
+    def parse path_or_html
+      # trying HTML first
+      @html_template = Nokogiri::HTML(path_or_html)
+      return if @html_template.css('formalizer').length > 0 # html indeed, parsed.
+
+      # not html, trying path
+      error_message = 'not a file and not valid html with <formalizer> tag/s'
+      html_file_content = Utils::find_file(path_or_html)
+      @html_template = Nokogiri::HTML(html_file_content)
+      return if @html_template.css('formalizer').length > 0 # file opened, parsed.
+
+      raise WrongFormTemplate, error_message
+    end
+
+
+    # Validates that the html template is usable
+    # Raises errors if <formalizer> tags don't contain id attribute
+
+    def validate_template
+      @html_template.css('formalizer').each do |html_field|
+        raise FormTemplateError if html_field.attributes['id'].nil?
+      end
+    end
+
+
+    # replacing html references/assets references with absolute file paths for PDF export
+
+    def replace_tag tag, attribute
+      final_path = Utils::final_path(tag[attribute])
+      return '' if final_path.empty?
+      tag[attribute] = final_path
+      return tag.to_s
+    end
+
+  end
+
+end