formalizer 1.0.0

data/lib/formalizer/form_field.rb

@@ -0,0 +1,322 @@
+class String
+  def to_bool
+    return true   if self == true   || self =~ (/(true|t|yes|y|1)$/i)
+    return false  if self == false  || self.blank? || self =~ (/(false|f|no|n|0)$/i)
+    raise ArgumentError.new("invalid value for Boolean: \"#{self}\"")
+  end
+end
+
+class Formalizer
+
+  # Holds attributes for a single field in a form.
+  #
+  # === Attributes
+  #
+  # * +id+ - Unique textal identifier for the field. See generate_id
+  # * +field_type+ - One of possible options described in TYPES constant
+  # * +name+ - field name in current locale. For custom locale use method: name(locale)
+  # * +enumeration+ - if field_type is :enum or :multiple, list of options for enumeration in current locale
+  #                   for custom locale use method: enumeration(locale)
+  # * +validation+ - a hash with validation rules, TBD
+  # * +default_value+ - the default value in current locale. for custom locale use method: defaut_value(locale)
+
+  class FormField
+    attr_reader :id, :field_type, :name, :enumeration, :validation, :default_value, :value
+
+    TYPES = {
+      boolean: 1,
+      number: 2,
+      text: 3,
+      enum: 4,
+      multiple: 5
+    }
+
+    # Prefixes that can be localized in constructor params. See initialze and examples below
+
+    LOCALIZED_TYPES = [
+      :name,
+      :enumeration,
+      :default_value
+    ]
+
+
+
+    # see usage examples at the end:
+
+    def initialize params
+      validate_params params
+
+      # populating properties
+
+      @field_type = params[:field_type].nil? ? TYPES[:text] : TYPES[params[:field_type].to_sym]
+      localize params
+      @validation = params[:validation] || {}
+      @id = params[:id] || generate_id
+      @default_value = params[:default_value] unless params[:default_value].nil?
+      @value = nil
+    end
+
+
+    # getters
+
+    def name locale = I18n.locale
+      @localized[:name][locale] || ''
+    end
+
+    def enumeration locale = I18n.locale
+      @localized[:enumeration][locale] || []
+    end
+
+    def default_value locale = I18n.locale
+      return @localized[:default_value][locale]
+    end
+
+    def value locale = I18n.locale
+      return '' if @value.nil?
+      return send("#{TYPES.key(@field_type)}_value", locale)
+    end
+
+
+    # setters
+
+    # Since we deal with html, value must be a String
+
+    def value= new_value
+      validated = send("validate_#{TYPES.key(@field_type)}_value", new_value)
+      @value = validated
+    end
+
+
+    # Renders the field as HTML control
+    # * +parent_node+ - the HTML parent under which to render (needed by Nokogiri)
+    # * +locale+ - localized input. Relevant if field_type is enum or multiple
+
+    def render_html parent_node, locale = I18n.locale
+      inp = send("render_html_#{TYPES.key(@field_type)}", parent_node, locale)
+      inp['id'] = @id
+      inp['name'] = @id
+      return inp
+    end
+
+
+    private
+
+    # generates a text id to use inside forms
+    # strips non alpfanumeric characters from name, lowercases the result
+    # and replaces whitespaces with '_'
+    # adds a unique hash at the end
+    # e.g. 'First Name (required)' -> 'first_name_required_f5f6f0ae0717937a039488c5b6163d6f'
+
+    def generate_id
+      base_name = @localized[:name][:en] || @localized[:name].values.first || ''
+      underscored_name = base_name.gsub(/[^0-9a-z ]/i, '').downcase.gsub(/\s+/, '_') << '_'
+      underscored_name += Digest::MD5.new.update(Time.now.to_i.to_s).hexdigest
+    end
+
+
+
+
+    # creates localized hash from initializer params with default locale
+    # example: initializer params { name: 'Gender' ....}
+    # result: {name: {en: 'Gender'}}
+    # example: initializer params { name: {en: 'Gender', es: es: 'Género'} ... }
+    # result: {name: {en: 'Gender', es: 'Género'}}
+
+    def localize params
+      @localized = {}
+      LOCALIZED_TYPES.each do |localized_type|
+        if params[localized_type].class == Hash
+          # params are already localized per locale
+          @localized[localized_type] = params[localized_type]
+        else
+          @localized[localized_type] = {I18n.locale => params[localized_type]}
+        end
+      end
+    end
+
+
+    # validate initializer params and raises exceptions unless validation passes
+
+    def validate_params params
+
+      raise FormFieldParamMissing, 'params must be a hash' unless params.class == Hash
+
+      # validating that at least one name_{locale} exists
+      raise FormFieldParamMissing, 'name is requireed' if params[:name].nil?
+
+      # validate that names are non-empty strings
+      names = params[:name].class == Hash ? params[:name].values : [params[:name]]
+      names.each do |name_value|
+        raise WrongValueClass, 'name should be a String' unless (name_value.is_a?String)
+        raise FormFieldParamMissing, 'name cannot be empty' if name_value.empty?
+      end
+
+      # validating that enumeration exists if field_type is enum or multiple
+      if [:enum, :multiple].include?(params[:field_type])
+        error_message = "enumeration array of >1 items requireed if field_type is enum/multiple"
+        enumerations = params[:enumeration].class == Hash ? params[:enumeration].values : [params[:enumeration]]
+        raise FormFieldParamMissing, error_message if enumerations.length == 0
+        enumerations.each do |enumeration|
+          if (!enumeration.is_a?Array) || (enumeration.length < 2)
+            raise FormFieldParamMissing, error_message
+          end
+        end
+      end
+
+      # validates param types
+
+    end
+
+
+
+    # Value validators
+
+    def validate_boolean_value new_value
+      new_value = new_value.to_bool if new_value.is_a?String
+      is_boolean = (!!(new_value) == new_value)
+      raise WrongValueClass, 'value should be boolean' unless is_boolean
+      return new_value
+    end
+
+    def validate_number_value new_value
+      if new_value.is_a?String
+        new_value = (new_value.include?'.') ? new_value.to_f : new_value.to_i
+      end
+      is_number = ((new_value.is_a?Fixnum) || (new_value.is_a?Float))
+      raise WrongValueClass, 'value should be a number' unless is_number
+      return new_value
+    end
+
+    def validate_text_value new_value
+      raise WrongValueClass, 'value whould be a string' unless new_value.is_a?String
+      return new_value
+    end
+
+    def validate_enum_value new_value
+      new_value = new_value.to_i if new_value.is_a?String
+      raise WrongValueClass, 'value should be a fixnum' unless new_value.is_a?Fixnum
+      raise WrongValueClass, 'value should be >= 0' if new_value < 0
+      min_enumeration_length = @localized[:enumeration].values.map{|enumeration| enumeration.length}.min
+      raise WrongValue, 'value should be within enumeration range' if new_value >= min_enumeration_length
+      return new_value
+    end
+
+    def validate_multiple_value new_value
+      new_value = new_value.to_i if new_value.is_a?String
+      raise WrongValueClass, 'value should be an array' unless new_value.is_a?Array
+      min_enumeration_length = @localized[:enumeration].values.map{|enumeration| enumeration.length}.min
+      raise WrongValueClass, 'array values should be >= 0' if new_value.min < 0
+      raise WrongValue, 'values should be within enumeration range' if new_value.max >= min_enumeration_length
+      return new_value
+    end
+
+
+
+
+    # value parsers: return type dependent value
+
+    def boolean_value locale
+      @value ? '&#10004;' : '-' # TODO: render as checkbox?
+    end
+
+    def number_value locale
+      @value ? @value.to_s : ''
+    end
+
+    def text_value locale
+      @value || ''
+    end
+
+    def enum_value locale
+      @value.nil? ? '' : @localized[:enumeration][locale][@value].to_s
+    end
+
+    def multiple_value locale
+      @value.nil? ? '' : @value.map{|val| @localized[:enumeration][locale][val].to_s}
+    end
+
+
+    # HTML renderers
+
+
+    def render_html_boolean parent_node, locale = I18n.locale
+      inp = Nokogiri::XML::Node.new('input', parent_node)
+      inp['type'] = 'checkbox'
+      inp['checked'] = 'true' if @default_value == true
+      return inp
+    end
+
+    def render_html_number parent_node, locale = I18n.locale
+      inp = Nokogiri::XML::Node.new('input', parent_node)
+      inp['type'] = 'number'
+      inp['value'] = @default_value if @default_value
+      return inp
+    end
+
+    def render_html_text parent_node, locale = I18n.locale
+      inp = Nokogiri::XML::Node.new('input', parent_node)
+      inp['type'] = 'text'
+      inp['value'] = self.default_value(locale)
+      return inp
+    end
+
+    def render_html_enum parent_node, locale = I18n.locale
+      return select_with_options(parent_node, locale)
+    end
+
+    def render_html_multiple parent_node, locale = I18n.locale
+      select_tag = select_with_options(parent_node, locale)
+      select_tag['multiple'] = 'true'
+      return select_tag
+    end
+
+    def select_with_options parent_node, locale = I18n.locale
+      inp = Nokogiri::XML::Node.new('select', parent_node)
+      enumeration(locale).each_with_index do |enum, index|
+        enum_option = Nokogiri::XML::Node.new('option', inp)
+        enum_option['value'] = index.to_s
+        enum_option.content = enum
+        enum_option['selected'] = 'true' if default_value == index
+        enum_option.parent = inp
+      end
+      return inp
+    end
+
+
+
+    # usage example 1 - enumerated, default locale:
+    # Formalizer::FormField.new({
+    #                            id: 'gender',
+    #                            name: 'Gender',
+    #                            field_type: :enum,
+    #                            enumeration: ['male', 'female', 'irrelevant'],
+    #                            default_value: 2})
+    # usage example 2 - enumerated, localized:
+    # Formalizer::FormField.new({
+    #                            id: 'gender',
+    #                            name: {
+    #                              en: 'Gender',
+    #                              es: 'Género'
+    #                            },
+    #                            field_type: :enum,
+    #                            enumeration: {
+    #                              en: ['male', 'female', 'irrelevant'],
+    #                              es: ['masculino', 'femenino', 'irrelevante']
+    #                            },
+    #                            default_value: 2})
+    # usage example 2 - text, localized:
+    # Formalizer::FormField.new({
+    #                            id: 'first_name',
+    #                            name: {
+    #                              en: 'First Name',
+    #                              es: 'Nombre de pila'
+    #                            },
+    #                            field_type: :text,
+    #                            default_value: {
+    #                              en: John,
+    #                              es: Juan
+    #                            }})
+
+  end
+end
+

data/lib/formalizer/formalizer.rb

@@ -0,0 +1,253 @@
+class Formalizer
+
+  # This is the main Formalizer object you use to create, fill and export html documents from user-input.
+  # The user input fields can be preset in a config/formalizer.yml file
+  # or programatically, by calling add_form_field
+
+  # EMPTY_CONFIG constant used to initialize config if not given from YAML file
+
+  EMPTY_CONFIG = {
+    form_fields: {},
+    forms: {}
+  }
+
+  attr_reader :form_sources, :forms, :form_fields, :tags
+
+
+
+  # Constructor
+  # Tries loading configuration from YAML file, falling back to an empty config
+  # Caching form fields and form targets (a target can be a path or actual html)
+
+  def initialize config_file = 'formalizer.yml'
+    load_config config_file
+
+    @form_fields = {}
+    @form_sources = {}
+    @forms = {}
+    @tags = {form_fields: {}, forms: {}}
+    @config[:form_fields].each do |key, value|
+      add_form_field value.merge(id: key)
+    end
+
+    @config[:forms].each do |key, value|
+      add_form key, value
+    end
+  end
+
+
+  # Adds a FormField object to the hash
+  # Aalidates that the id is unique
+  # * +form_field_hash+ - a hash describing the form field.
+  #                       See examples at the end of formalizer/form_field.rb
+
+  def add_form_field form_field_hash
+    # unique id validation
+    raise NotUniqueId unless @form_fields[form_field_hash[:id]].nil?
+
+    # adding to hash
+    @form_fields[form_field_hash[:id]] = FormField.new(form_field_hash)
+
+    # handling tags
+    add_tags :form_fields, form_field_hash
+  end
+
+
+  # Adds a form source (path or html) to the forms hash
+  # Validates that the id is unique
+  # * +form_id+ - a unique id to the form
+  # * +form_hash+ - a hash containing form path/html and tags
+
+  def add_form form_id, form_hash
+    # unique id validation
+    raise NotUniqueId unless @form_sources[form_id].nil?
+    raise TypeError, 'form_hash should be Hash' unless (form_hash.is_a?Hash)
+    raise Formalizer::PathOrHtmlRequired, 'form_hash[:path] required' if form_hash[:path].nil?
+
+    # adding to hash
+    @form_sources[form_id] = form_hash[:path]
+
+    # handling tags
+    add_tags :forms, form_hash
+
+    true
+  end
+
+
+  # Fills one form field with content
+  # * +field_id+ - the field id
+  # * +field_value+ - value to fill the field
+
+  def fill_field field_id, field_value
+    raise FieldNotFound, "field #{field_id} not found" if @form_fields[field_id].nil?
+    @form_fields[field_id].value = field_value
+  end
+
+
+  # Fills multiple form fields with content
+  # * +field_params+ - Hash of field_id: field_value objects to fill multuple fields
+
+  def fill_fields field_params
+    raise TypeError, 'field_params should be a Hash' unless (field_params.is_a?Hash)
+    field_params.each do |field_id, field_value|
+      fill_field(field_id, field_value)
+    end
+  end
+
+
+  # Exports a form to pdf
+  # * +form_id+ - the form id to export
+  # * +tag+ - narrows down the passed fields list to fields under the specified tag.
+  #           If nil - all fields will be passed to form
+
+  def export_form_to_pdf form_id, tag = nil
+    form = bind_form_fields(form_id, tag)
+    return form.export_to_pdf
+  end
+
+
+
+  # Exports a form to html
+  # * +form_id+ - the form id to export
+  # * +tag+ - narrows down the passed fields list to fields under the specified tag.
+  #           If nil - all fields will be passed to form
+
+  def export_form_to_html form_id, tag = nil
+    form = bind_form_fields(form_id, tag)
+    return form.export_to_html
+  end
+
+
+  # Loads config from YAML file
+  # * +config_file+ - path to the config file, absolute or relative to app's 'config' path
+  # Raises an error if YAML file is ill-formatted
+  # Puts a warning if not YAML file not found
+
+  def load_config config_file
+    # searching in paths
+    @config = nil
+    begin
+      config_file_content = Utils::find_file(config_file) # will raise an exception if not found
+      @config ||= YAML.load(config_file_content)
+    rescue FileNotFound
+      # ok, no config... not a disaster
+      puts "YAML Not found in #{File.expand_path(config_file)}"
+    rescue Psych::SyntaxError
+      # config found but ill-formatted YAML
+      raise "YAML Syntax Error in #{file_path}"
+    end
+
+    # Fallback to an empty config
+    @config ||= EMPTY_CONFIG
+
+    validate_config
+
+    # YAML is translated to quoted keys, FormField expects symbols:
+    @config.deep_symbolize_keys!
+
+  end
+
+
+
+  # Generates an HTML form with fields to fill.
+  # * +locale+ - relevant with enum/multiple type fields, defaults to default app locale
+  # * +form_action+ - generated form can have an action. Defaults to ''
+  # * +tag+ - narrows down thefields list to those under the specified tag. Defaults to all fields
+
+  def generate_fields_form locale = I18n.locale, form_action = '', tag = nil
+    fields = fields_by_tag(tag)
+    action = form_action.empty? ? '' : " action=\"#{form_action}\""
+    html = Nokogiri::HTML("<body><form#{action} method='POST'><fieldset></fieldset></form></body>")
+    fields.each do |key, field|
+      wrapper = Nokogiri::XML::Node.new('div', html)
+      label = Nokogiri::XML::Node.new('label', wrapper)
+      label['for'] = field.id
+      label.content = "#{field.name(locale)}:"
+      rendered_field = field.render_html(wrapper, locale)
+      label.parent = wrapper
+      rendered_field.parent = wrapper
+      wrapper.parent = html.at_css('fieldset')
+    end
+    submit_container = Nokogiri::XML::Node.new('div', html)
+    submit_types = %w(HTML PDF)
+    %w(reset submit submit).each_with_index do |control_type, index|
+      reset_submit = Nokogiri::XML::Node.new('input', submit_container)
+      reset_submit['type'] = control_type
+      if control_type == 'submit'
+        reset_submit['name'] = "export_#{submit_types[index - 1]}"
+        reset_submit['value'] = "Export as #{submit_types[index - 1]}"
+      end
+      reset_submit.parent = submit_container
+    end
+    submit_container.parent = html.at_css('fieldset')
+    html.to_s
+  end
+
+  # Private methods
+
+  private
+
+
+  # Validates that the config file has the necessary ingredients
+
+  def validate_config
+    # checking that all field ids are unique
+    [:form_fields, :forms].each do |config_item|
+      raise ConfigError, "config should be a keys-values structure" unless @config.is_a?Hash
+      if (@config[config_item].nil?) && (@config[config_item.to_s].nil?)
+        raise ConfigError, "missing key in config: #{config_item}"
+      end
+      ids = @config[config_item] ? @config[config_item].keys : @config[config_item.to_s].keys
+      raise ConfigError, "Config form_fields - keys must be unique" if ids.uniq.length != ids.length
+    end
+  end
+
+
+  # Gets a form instance
+  # Returning cached instance or caching one and returning it
+  # * +form_id+ - the id of the form to get
+
+  def get_form form_id
+    form = @forms[form_id] || lambda{@forms[form_id] = Form.new(form_id, @form_sources[form_id])}.call
+  end
+
+
+
+  # Handles form_field and form tags
+  # * +tag_type+ - :form_fields or :forms
+  # * +object_hash+ - A hash with :tags key. The value for :tags key can an Array or String.
+  #                   if Array: ['tag1', 'tag2'] ...
+  #                   if String: will be converted to an array ['tag1']
+
+  def add_tags tag_type, object_hash
+    unless object_hash[:tags].nil?
+      tags = (object_hash[:tags].is_a?Array) ? object_hash[:tags] : [object_hash[:tags]]
+      tags.each do |tag_name|
+        @tags[tag_type][tag_name] ||= []
+        @tags[tag_type][tag_name] << object_hash[:id]
+      end
+    end
+  end
+
+
+  # binds form fields with data
+  # * +form_id+ - the form id to bind
+  # * +tag+ - narrows down the fields list to fields under the specified tag.
+  #           or all fields if tag is nil
+
+  def bind_form_fields form_id, tag = nil
+    form = get_form(form_id)
+    form.fill(fields_by_tag(tag))
+    return form
+  end
+
+
+  # return fields list by tag, or all fields if tag is nil
+  # * +tag+ - narrows down the fields list to fields under the specified tag.
+  #           or all fields if tag is nil
+
+  def fields_by_tag tag = nil
+    tag.nil? ? @form_fields : @form_fields.select{|key, ff| @tags[:form_fields][tag].include?(ff.id)}
+  end
+
+end

data/lib/formalizer/utils.rb

@@ -0,0 +1,61 @@
+class Formalizer
+
+  class Utils
+
+    # SEARCH_PATHS constant
+    # Usually formalizer.yml is in root config directory
+    # Gem's testing directory is test/dummy/config
+
+    SEARCH_PATHS = %w(config test/dummy/config test/dummy)
+
+
+    def self.find_file file_path, read = true, search_paths = SEARCH_PATHS
+
+      if file_path[0] == '/'
+        # probably absolute path
+        # raise exception if file not found
+        raise FileNotFound, 'file not exists' unless File.exists?file_path
+        return read ? File.read(file_path) : fild_path
+      else
+        # probably relative path, searching in SEARCH_PATHS
+        search_paths.each do |path|
+          absolute_file_path = "#{File.expand_path(path)}/#{file_path}"
+          begin
+            return (read ? File.read(absolute_file_path) : absolute_file_path) if File.exists?(absolute_file_path)
+          rescue Errno::EISDIR
+            raise FileNotFound, 'path is a directory, not a file'
+          end
+        end
+      end
+
+      # not found anywhere
+      raise FileNotFound, 'file not exists' unless File.exists?file_path
+    end
+
+
+    # tries getting the full local path to a relative/absolute path
+    # (image src attribute, stylesheet rel attribute)
+    # * +path+ - the original relative/absolute path
+
+    def self.final_path path
+      if path.start_with?'http'
+        # external path, nothing to do, return path as is
+        return path
+      elsif path[0..6].include?'assets'
+        # path is probably an asset, searching in assets
+        final_path = self.find_file(Pathname.new(path).basename.to_s, false, Rails.application.config.assets.paths)
+      else
+        # path is a relative path
+        begin
+          final_path = self.find_file(path, false)
+        rescue Formalizer::FileNotFound
+          # path not found
+          return ''
+        end
+      end
+      return "file:///#{final_path}"
+    end
+
+  end
+
+end

data/lib/formalizer/version.rb

@@ -0,0 +1,3 @@
+class Formalizer
+  VERSION = "1.0.0"
+end

data/lib/formalizer.rb

@@ -0,0 +1,5 @@
+require 'formalizer/errors'
+require 'formalizer/utils'
+require 'formalizer/form_field'
+require 'formalizer/form'
+require 'formalizer/formalizer'

data/lib/tasks/formalizer_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :formalizer do
+#   # Task goes here
+# end

data/test/dummy/Gemfile

@@ -0,0 +1,5 @@
+ruby '2.2.2'
+source 'https://rubygems.org'
+
+gem 'wicked_pdf'
+gem 'wkhtmltopdf-binary'

data/test/dummy/Gemfile.lock

@@ -0,0 +1,12 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    wicked_pdf (1.0.0)
+    wkhtmltopdf-binary (0.9.9.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  wicked_pdf
+  wkhtmltopdf-binary

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.