opal-ferro 0.10.0 → 0.10.1

data/opal/opal-ferro/ferro_document.js.rb

@@ -1,36 +1,60 @@
-class FerroDocument
-
-  include FerroElementary
-
-  def initialize
-    @children = {}
-    creation
-    # router.navigated
-  end
-
-  def parent
-    self
-  end
-
-  def element
-    @factory.body
-  end
-
-  def factory
-    @factory ||= FerroFactory.new
+# Module Ferro contains all Ferro functionality.
+module Ferro
+  # This is the entry point for any Ferro application.
+  # It represents the top level object of the
+  # Master Object Model (MOM).
+  # There should be only one class that inhertits
+  # from FerroDocument in an application.
+  # This class attaches itself to the DOM
+  # `document.body` object.
+  # Any existing child nodes of `document.body` are removed.
+  class Document
+
+    include Elementary
+
+    # Create the document and start the creation
+    # process (casading).
+    def initialize
+      @children = {}
+      creation
+    end
+
+    # The document doesn't have a parent so returns itself.
+    def parent
+      self
+    end
+
+    # Returns the DOM element.
+    def element
+      factory.body
+    end
+
+    # Returns the one and only instance of the factory.
+    def factory
+      @factory ||= Factory.new
+    end
+
+    # The document class is the root element.
+    def root
+      self
+    end
+
+    # The document class is a component.
+    def component
+      self
+    end
+
+    # Returns the one and only instance of the router.
+    def router
+      @router ||= Router.new(method(:page404))
+    end
+
+    # Callback for the router when no matching routes
+    # can be found. Override this method to add custom
+    # behavior.
+    #
+    # @param [String] pathname The route that was not matched
+    #                          by the router
+    def page404(pathname);end
   end
-
-  def root
-    self
-  end
-
-  def component
-    self
-  end
-
-  def router
-    @router ||= FerroRouter.new(method(:page404))
-  end
-
-  def page404(pathname);end
-end
+end

data/opal/opal-ferro/ferro_elementary.js.rb

@@ -1,79 +1,115 @@
-module FerroElementary
-
-  RESERVED_NAMES = %i[
-    initialize factory root router page404
-    creation _before_create before_create create _after_create
-    after_create style _stylize cascade
-    add_child forget_children remove_child method_missing destroy
-    value set_text html parent children element domtype options
-    add_states add_state update_state toggle_state state_active
-  ]
-
-  def creation
-    _before_create
-    before_create
-    create
-    _after_create
-    after_create
-    _stylize
-    cascade
-  end
-  
-  def _before_create;end
-  def before_create;end
+module Ferro
+  # Module defines element creation methods and child management.
+  # Note that there are no private methods in Opal. Methods that
+  # should be private are marked in the docs with 'Internal method'.
+  module Elementary
 
-  def create
-    @element = factory.create_element(self, @domtype, @parent, @options) if @domtype 
-  end
+    # Array of reseved names, child element should not have a name
+    # that is included in this list
+    RESERVED_NAMES = %i[
+      initialize factory root router page404
+      creation _before_create before_create create _after_create
+      after_create style _stylize cascade
+      add_child forget_children remove_child method_missing destroy
+      value set_text html parent children element domtype options
+      add_states add_state update_state toggle_state state_active
+    ]
 
-  def _after_create;end
-  def after_create;end
+    # Create DOM element and children elements.
+    # Calls before- and after create hooks.
+    def creation
+      _before_create
+      before_create
+      create
+      _after_create
+      after_create
+      _stylize
+      cascade
+    end
 
-  def style;end
+    # Internal method.
+    def _before_create;end
 
-  def _stylize
-    styles = style
+    # Internal method.
+    def before_create;end
 
-    if styles.class == Hash
-      set_attribute(
-        'style',
-        styles.map { |k, v| "#{k}:#{v};" }.join
-      )
+    # Calls the factory to create the DOM element.
+    def create
+      @element = factory.create_element(self, @domtype, @parent, @options) if @domtype 
     end
-  end
 
-  def cascade;end
+    # Internal method.
+    def _after_create;end
 
-  def add_child(name, element_class, options = {})
-    sym = symbolize(name)
-    raise "Child '#{sym}' already defined" if @children.has_key?(sym)
-    raise "Illegal name (#{sym})" if RESERVED_NAMES.include?(sym)
-    @children[sym] = element_class.new(self, sym, options)
-  end
+    # Internal method.
+    def after_create;end
 
-  def symbolize(name)
-    name.downcase.to_sym
-  end
+    # Override this method to return a Hash of styles.
+    # Hash-key is the CSS style name, hash-value is the CSS style value.
+    def style;end
 
-  def forget_children
-    children = {}
-  end
+    # Internal method.
+    def _stylize
+      styles = style
 
-  def remove_child(sym)
-    @children.delete(sym)
-  end
+      if styles.class == Hash
+        set_attribute(
+          'style',
+          styles.map { |k, v| "#{k}:#{v};" }.join
+        )
+      end
+    end
 
-  def destroy
-    `#{parent.element}.removeChild(#{element})`
-    parent.remove_child(@sym)
-  end
+    # Override this method to continue the MOM creation process.
+    def cascade;end
+
+    # Add a child element.
+    #
+    # @param [String] name A unique name for the element that is not
+    #   in RESERVED_NAMES
+    # @param [String] element_class Ruby class name for the new element
+    # @param [Hash] options Options to pass to the element. Any option key
+    #   that is not recognized is set as an attribute on the DOM element.
+    #   Recognized keys are:
+    #     prepend Prepend the new element before this DOM element
+    #     content Add the value of content as a textnode to the DOM element
+    def add_child(name, element_class, options = {})
+      sym = symbolize(name)
+      raise "Child '#{sym}' already defined" if @children.has_key?(sym)
+      raise "Illegal name (#{sym})" if RESERVED_NAMES.include?(sym)
+      @children[sym] = element_class.new(self, sym, options)
+    end
+
+    # Convert a string containing a variable name to a symbol.
+    def symbolize(name)
+      name.downcase.to_sym
+    end
+
+    # Remove all child elements.
+    def forget_children
+      children = {}
+    end
+
+    # Remove a specific child element.
+    #
+    # param [Symbol] sym The element to remove
+    def remove_child(sym)
+      @children.delete(sym)
+    end
+
+    # Remove a DOM element.
+    def destroy
+      `#{parent.element}.removeChild(#{element})`
+      parent.remove_child(@sym)
+    end
 
-  # Getter for children
-  def method_missing(method_name, *args, &block)
-    if @children.has_key?(method_name)
-      @children[method_name]
-    else
-      super
+    # Getter for children.
+    def method_missing(method_name, *args, &block)
+      if @children.has_key?(method_name)
+        @children[method_name]
+      else
+        super
+      end
     end
   end
 end

data/opal/opal-ferro/ferro_factory.js.rb

@@ -1,58 +1,83 @@
-class FerroFactory
+module Ferro
+  # Create DOM elements.
+  class Factory
 
-  attr_reader :body
+    attr_reader :body
 
-  def initialize
-    @body = `document.body`
-    `while (document.body.firstChild) {document.body.removeChild(document.body.firstChild);}`
-  end
+    # Creates the factory. Do not create a factory directly, instead
+    # call the 'factory' method that is available in all Ferro classes
+    def initialize
+      @body = `document.body`
+      `while (document.body.firstChild) {document.body.removeChild(document.body.firstChild);}`
+    end
 
-  def create_element(target, type, parent, options = {})
-    # Create element
-    element = `document.createElement(#{type})`
+    # Create a DOM element.
+    #
+    # @param [String] target The Ruby class instance
+    # @param [String] type Type op DOM element to create
+    # @param [String] parent The Ruby parent element
+    # @param [Hash] options Options to pass to the element.
+    #   See FerroElementary::add_child
+    # @return [String] the DOM element
+    def create_element(target, type, parent, options = {})
+      # Create element
+      element = `document.createElement(#{type})`
 
-    # Add element to DOM
-    if options[:prepend]
-      `#{parent.element}.insertBefore(#{element}, #{options[:prepend].element})`
-    else
-      `#{parent.element}.appendChild(#{element})`
-    end
+      # Add element to DOM
+      if options[:prepend]
+        `#{parent.element}.insertBefore(#{element}, #{options[:prepend].element})`
+      else
+        `#{parent.element}.appendChild(#{element})`
+      end
 
-    # Add ruby class to the node
-    `#{element}.classList.add(#{dasherize(target.class.name)})`
+      # Add ruby class to the node
+      `#{element}.classList.add(#{dasherize(target.class.name)})`
 
-    # Add ruby superclass to the node to allow for more generic styling
-    if target.class.superclass != FerroElement
-      `#{element}.classList.add(#{dasherize(target.class.superclass.name)})`
-    end
+      # Add ruby superclass to the node to allow for more generic styling
+      if target.class.superclass != BaseElement
+        `#{element}.classList.add(#{dasherize(target.class.superclass.name)})`
+      end
 
-    # Set ruby object_id as default element id
-    if !options.has_key?(:id)
-      `#{element}.id = #{target.object_id}`
-    end
-        
-    # Set attributes
-    options.each do |name, value|
-      case name
-      when :prepend
-        nil
-      when :content
-        `#{element}.appendChild(document.createTextNode(#{value}))`
-      else
-        `#{element}.setAttribute(#{name}, #{value})`
+      # Set ruby object_id as default element id
+      if !options.has_key?(:id)
+        `#{element}.id = #{target.object_id}`
+      end
+          
+      # Set attributes
+      options.each do |name, value|
+        case name
+        when :prepend
+          nil
+        when :content
+          `#{element}.appendChild(document.createTextNode(#{value}))`
+        else
+          `#{element}.setAttribute(#{name}, #{value})`
+        end
       end
+
+      element
     end
 
-    element
-  end
+    # Convert a Ruby classname to a dasherized name for use with CSS.
+    #
+    # @param [String] class_name The Ruby class name
+    # @return [String] CSS class name
+    def dasherize(class_name)
+      return class_name if class_name !~ /[A-Z:_]/
+      c = class_name.to_s.gsub('::', '')
 
-  def dasherize(class_name)
-    return class_name if class_name !~ /[A-Z_]/
-    (class_name[0] + class_name[1..-1].gsub(/[A-Z]/){ |c| "-#{c}" }).downcase.gsub('_', '-')
-  end
+      (c[0] + c[1..-1].gsub(/[A-Z]/){ |c| "-#{c}" }).
+        downcase.
+        gsub('_', '-')
+    end
 
-  def camelize(class_name)
-    return class_name if class_name !~ /-/
-    class_name.gsub(/(?:-|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" }.strip
+    # Convert a CSS classname to a camelized Ruby class name.
+    #
+    # @param [String] class_name CSS class name
+    # @return [String] A Ruby class name
+    def camelize(class_name)
+      return class_name if class_name !~ /-/
+      class_name.gsub(/(?:-|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" }.strip
+    end
   end
 end

data/opal/opal-ferro/ferro_router.js.rb

@@ -1,118 +1,177 @@
-require 'native'
-
-class FerroRouter
-  
-  def initialize(page404)
-    @routes  = []
-    @page404 = page404
-    setup_navigation_listener
-  end
+module Ferro
+
+  require 'native'
+
+  # Wrapper for the web browsers history API.
+  # Note that there are no private methods in Opal. Methods that
+  # should be private are marked in the docs with 'Internal method'.
+  class Router
+    
+    # Create the router. Do not create a router directly, instead
+    # call the 'router' method that is available in all Ferro classes
+    # That method points to the router instance that is attached to
+    # the FerroDocument.
+    #
+    # @param [Method] page404 Method that is called when the web browser
+    #                 navigates and no route can be found. Override the
+    #                 page404 method in FerroDocument.
+    def initialize(page404)
+      @routes  = []
+      @page404 = page404
+      setup_navigation_listener
+    end
 
-  def add_route(path, callback)
-    @routes << { parts: path_to_parts(path), callback: callback }
-  end
+    # Add a new route to the router.
+    #
+    # Examples: when the following routes are created and the web browser
+    # navigates to a url matching the route, the callback method will be
+    # called with parameters:
+    #   add_route('/ferro/page1', my_cb) # '/ferro/page1'  => my_cb({})
+    #   add_route('/user/:id',    my_cb) # '/user/1'       => my_cb({id: 1})
+    #   add_route('/ferro',       my_cb) # '/ferro?page=1' => my_cb({page: 1})
+    #
+    # @param [String] path Relative url (without protocol and host)
+    # @param [Method] callback Method that is called when the web browser
+    #                 navigates and the path is matched. The callback
+    #                 method should accept one parameter [Hash]
+    #                 containing the parameters found in the matched url
+    def add_route(path, callback)
+      @routes << { parts: path_to_parts(path), callback: callback }
+    end
 
-  def setup_navigation_listener
-    `window.onpopstate = function(e){#{navigated}}`
-  end
+    # Internal method to set 'onpopstate'
+    def setup_navigation_listener
+      `window.onpopstate = function(e){#{navigated}}`
+    end
 
-  def replace_state(url)
-    `history.replaceState(null,null,#{url})`
-  end
+    # Replace the current location in the web browsers history
+    #
+    # @param [String] url Relative url (without protocol and host)
+    def replace_state(url)
+      `history.replaceState(null,null,#{url})`
+    end
 
-  def push_state(url)
-    `history.pushState(null,null,#{url})`
-  end
+    # Add a location to the web browsers history
+    #
+    # @param [String] url Relative url (without protocol and host)
+    def push_state(url)
+      `history.pushState(null,null,#{url})`
+    end
 
-  def go_to(url)
-    push_state(url)
-    navigated
-  end
+    # Navigate to url
+    #
+    # @param [String] url Relative url (without protocol and host)
+    def go_to(url)
+      push_state(url)
+      navigated
+    end
 
-  def go_back
-    `history.back()`
-  end
+    # Navigate back
+    def go_back
+      `history.back()`
+    end
 
-  def get_location
-    Native(`new URL(window.location.href)`)
-  end
+    # Internal method to get the new location
+    def get_location
+      Native(`new URL(window.location.href)`)
+    end
 
-  def path_to_parts(path)
-    path.
-      downcase.
-      split('/').
-      map { |part| part.empty? ? nil : part.strip }.
-      compact
-  end
+    # Internal method to split a path into components
+    def path_to_parts(path)
+      path.
+        downcase.
+        split('/').
+        map { |part| part.empty? ? nil : part.strip }.
+        compact
+    end
 
-  def decode(value)
-    `decodeURI(#{value})`
-  end
+    # URI decode a value
+    #
+    # @param [String] value Value to decode
+    def decode(value)
+      `decodeURI(#{value})`
+    end
 
-  def navigated
-    url = get_location
-    @params = []
+    # Internal method called when the web browser navigates
+    def navigated
+      url = get_location
+      @params = []
 
-    idx = match(path_to_parts(decode(url.pathname)), decode(url.search))
+      idx = match(path_to_parts(decode(url.pathname)), decode(url.search))
 
-    if idx
-      @routes[idx][:callback].call(@params)
-    else
-      @page404.call(url.pathname)
+      if idx
+        @routes[idx][:callback].call(@params)
+      else
+        @page404.call(url.pathname)
+      end
     end
-  end
 
-  def match(path, search)
-    matches = get_matches(path)
+    # Internal method to match a path to the most likely route
+    #
+    # @param [String] path Url to match
+    # @param [String] search Url search parameters
+    def match(path, search)
+      matches = get_matches(path)
 
-    if matches.length > 0
-      match = matches.sort { |m| m[1] }.first
+      if matches.length > 0
+        match = matches.sort { |m| m[1] }.first
 
-      @params = match[2]
-      add_search_to_params(search)
+        @params = match[2]
+        add_search_to_params(search)
 
-      match[0]
-    else
-      nil
+        match[0]
+      else
+        nil
+      end
     end
-  end
 
-  def get_matches(path)
-    matches = []
+    # Internal method to match a path to possible routes
+    #
+    # @param [String] path Url to match
+    def get_matches(path)
+      matches = []
 
-    @routes.each_with_index do |route, i|
-      score, pars = score_route(route[:parts], path)
-      matches << [i, score, pars] if score > 0
-    end
+      @routes.each_with_index do |route, i|
+        score, pars = score_route(route[:parts], path)
+        matches << [i, score, pars] if score > 0
+      end
 
-    matches
-  end
+      matches
+    end
 
-  def score_route(parts, path)
-    score = 0
-    pars  = {}
-
-    if parts.length == path.length
-      parts.each_with_index do |part, i|
-        if part[0] == ':'
-          score += 1
-          pars["#{part[1..-1]}"] = path[i]
-        elsif part == path[i].downcase
-          score += 2
+    # Internal method to add a match score
+    #
+    # @param [String] parts Parts of a route
+    # @param [String] path Url to match
+    def score_route(parts, path)
+      score = 0
+      pars  = {}
+
+      if parts.length == path.length
+        parts.each_with_index do |part, i|
+          if part[0] == ':'
+            score += 1
+            pars["#{part[1..-1]}"] = path[i]
+          elsif part == path[i].downcase
+            score += 2
+          end
         end
       end
-    end
 
-    return score, pars
-  end
+      return score, pars
+    end
 
-  def add_search_to_params(search)
-    if !search.empty?
-      pars = search[1..-1].split('&')
+    # Internal method to split search parameters
+    #
+    # @param [String] search Url search parameters
+    def add_search_to_params(search)
+      if !search.empty?
+        pars = search[1..-1].split('&')
 
-      pars.each do |par|
-        pair = par.split('=')
-        @params[ pair[0] ] = pair[1] if pair.length == 2
+        pars.each do |par|
+          pair = par.split('=')
+          @params[ pair[0] ] = pair[1] if pair.length == 2
+        end
       end
     end
   end