opal-ferro 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f56567922f613ccb4b5dc4bf3dae7ea52c67f24b
-  data.tar.gz: 9214aa5989306aacd55e435d43161ba60ac26a30
+SHA256:
+  metadata.gz: 0cf34d1239b6886601737690e639cadd7e0fd9971a73cb233eed18faf78ba764
+  data.tar.gz: 9d6f89cbc0c4fc22c095d0b3d057e1255ccbc28f2b6ae8da7cdca3222d6fae39
 SHA512:
-  metadata.gz: 66c1f60432258923680daddeef451abecfae6cf9b77d94877f088cd574f8d59385c4210cbe073614e1164b65c0e676c64de8646d6f1d9c9ce3069a4b454d54a1
-  data.tar.gz: d82fc2be389ff2954bf55f086ffc1f3bef427017c6dd534d0d35b63425dd702673617290a8339f6fe874367a5aa84b4142ffeb2d49f84c08707a7ae20aa6a8f2
+  metadata.gz: 4e92a9b4a555a1a8c9ae937b222a43880b3d650aefb5400fe08766cb8cdf7f4e3f95351ba8b267c3f7f6e1d08dc5967c465056bf911572cd2fd2c6a1c94b3e4d
+  data.tar.gz: 7de1f758372345527f612eeb744727c4c97282f706154979edc439f230f00a4fa043403c2785570dee947f625212b9041c9e691c8019c03ee8a34704074b386a

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 /.ruby-version
+*.gem

data/.yardopts

@@ -0,0 +1,8 @@
+opal/**/*.rb
+lib/**/*.rb
+-
+README.md
+docs/GettingStarted.md
+CHANGELOG.md
+LICENSE.txt
+CODE_OF_CONDUCT.md

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# 0.10.1 - March 31, 2018
+
+- Added documentation (using Yard)
+- Modularized Ferro (breaking change), see below
+- AJAX can now handle any type of request (not just get)
+
+To upgrade from 0.10.0 to 0.10.1:
+
+- replace FerroDocument with Ferro::Document
+- replace FerroXhr with Ferro::Xhr
+- replace FerroSequence with Ferro::Sequence
+- replace FerroElementForm with Ferro::Form::Base
+- replace FerroElementForm... with Ferro::Form::...
+- replace FerroElementComponent with Ferro::Component::Base
+- replace FerroElementComponent... with Ferro::Component::...
+- replace FerroSearch with Ferro::Combo::Search
+- replace FerroPullDown with Ferro::Combo::PullDown
+- replace FerroElement... with Ferro::Element::...
+
+
+# 0.10.0 - February 2, 2018
+
+Initial version

data/README.md

@@ -1,4 +1,9 @@
 # Opal-Ferro
+
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/opal-ferro)
+[![Gem Version](https://img.shields.io/badge/gem%20version-0.10.1-blue.svg)](https://github.com/easydatawarehousing/opal-ferro/releases)
+[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
+
 Ferro is a small Ruby library on top of [Opal](http://opalrb.com/)
 that enables an object-oriented programming style for creating code
 that runs in the webbrowser.
@@ -24,6 +29,17 @@ Or install it yourself:
 Please see the [Ferro website](https://easydatawarehousing.github.io/ferro/)
 for background information and examples.
 
+## Versioning
+Opal-Ferro follows the versioning scheme of [Opal](https://github.com/opal/opal).
+The first two parts of the version number of Ferro imply compatibility
+with the Opal version with that same number.
+So Ferro 0.10.x should be compatible with and dependant on Opal 0.10.x.
+
+## Roadmap
+Please see the development roadmap
+[here](https://github.com/easydatawarehousing/opal-ferro/wiki/Development-roadmap)
+for the current wishlist of features to be added to Ferro.
+
 ## Development
 To install this gem onto your local machine, run `bundle exec rake install`.
 To release a new version, update the version number in `version.rb`
@@ -38,6 +54,19 @@ This project is intended to be a safe, welcoming space for collaboration
 and contributors are expected to adhere to the
 [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## Documentation
+Yard is used to generate documentation. In development start yard using:
+
+    yard server -r
+
+Use this to list all undocumented items:
+
+    yard stats --list-undoc
+
+To generate documentation for publication, cd into project root and use:
+
+    yardoc
+
 ## License
 The gem is available as open source under the terms of the MIT License.
 See LICENSE.txt

data/docs/GettingStarted.md

@@ -0,0 +1,187 @@
+# @title Getting started with Opal-Ferro
+
+# Getting started with Opal-Ferro
+
+Ferro is a small Ruby library on top of [Opal](http://opalrb.com/)
+that enables an object-oriented programming style for creating code
+that runs in the webbrowser.
+No more distractions like HTML and searching for DOM elements,
+just beautiful and simple Ruby code. Front-End-Ruby-ROcks!
+
+
+* [How does Ferro work](#ferro)
+* [Creating the Master Object Model](#mom)
+* [Adding elements](#demo)
+* [Creation lifecycle](#lifecycle)
+* [Navigating the Master Object Model](#navigating)
+* [Styling Ferro elements](#styling)
+* [More information](#more)
+
+<a name="ferro"></a>
+
+## How does Ferro work?
+Ferro uses an object oriented programming style. You instantiate an object, that object
+in turn instantiates more child objects and add these as instance variables to itself.
+And so on, producing a hierarchy of object instances.
+This is called the Master Object Model (MOM).
+
+When an object is instanciated in the MOM, Ferro will add an element to the webbrowsers
+Document Object Model (DOM). The MOM keeps a reference to every DOM element.
+This erradicates the need for element lookups (jquery $ searches).
+If you need an element you know where to find it in the MOM.
+Getter methods are automatically added by Ferro for easy access to instance variables.
+
+Each object in the MOM inherits from a Ferro class.
+Which Ferro class you use determines what type of DOM element will be created.
+All Ferro classes inherit from one base class: Ferro::BaseElement.
+For most DOM elements in the html specs there is a corresponding Ferro class.
+For instance if you need a html5 `<header>` element you would create a class that inherits
+from Ferro::Component::Header.  
+Other html elements have a more abstract counterpart:
+all text elements (`<p>`, `<h1>` .. `<h6>`) have one Ferro class `Ferro::Element::Text`.
+The size of the text element is an option when you instantiate the object.
+
+<a name="mom"></a>
+
+## Creating the Master Object Model
+
+First we need a class that inherits from FerroDocument.
+This is the staring point for any Ferro application.
+The Document instance will attach itself in the DOM to
+`document.body`.
+
+In the example below, the Document instance will create one child element.
+
+    class Document < Ferro::Document
+
+      # The cascade method is called after the Document
+      # has been created and is ready to create child
+      # objects.
+      def cascade
+        add_child :demo, Demo
+      end
+    end
+
+To start the application one instance of the Document must be created.
+In the `application.js` file (if you are using Rails for instance)
+`Document.new` is called when the browser has loaded the necessary
+files.
+
+    `document.addEventListener("DOMContentLoaded", function() {#{Document.new};})`
+
+The backticks are Opal's way of entering _raw_ Javascript. Using
+familiar Ruby string interpolation `#{}` a reference to `Document.new` can
+be inserted.
+This is the first and last line of Javascript that is needed.
+Everyting else is Ruby code.
+
+<a name="demo"></a>
+
+## Adding elements
+
+Let's look at a very simple example. We will define a small component
+with a title and a button. The button should change the title text when clicked.
+
+    class Demo < Ferro::Component::Base
+      def cascade
+        # Add a title
+        add_child :title, Ferro::Element::Text, size: 4, content: 'Title'
+
+        # Add a button
+        add_child :btn, DemoButton, content: 'Click me'
+      end
+
+      def rotate_title
+        # We have access to the 'title' instance variable
+        txt = title.get_text
+        title.set_text (txt[1..-1] + txt[0]).capitalize
+      end
+    end
+
+    class DemoButton < Ferro::Form::Button
+      def clicked
+        # Every element knows its parent
+        parent.rotate_title
+      end
+    end
+
+The code in Demo _cascade_ method is equivalent to something like this,
+which should look more familiar to a Ruby programmer:
+
+    class Demo
+      def initialize
+        @title = Ferro::Element::Text.new(size: 4, content: 'Title')
+        @btn   = DemoButton.new(content: 'Click me')
+      end
+    end
+
+Just like above, the `add_child` method will create instance variables
+`@title` and `@btn`. In Ferro we don't need to use the @.
+
+<a name="lifecycle"></a>
+
+## Creation lifecycle
+
+Every Ferro class has 3 hooks into the object creation lifecycle:
+
+- before_create
+- after_create
+- cascade
+
+The first two are called just before and after the object itself
+is created. The cascade hook is called when the object is ready
+to create child objects.  
+In this example most of the action happens in the _cascade_ method.
+
+By inheriting from _Ferro::Form::Button_, _DemoButton_ has access
+to the click event handler. After a click occurred, it signals
+its parent (_Demo_) to rotate the title text.
+
+<a name="navigating"></a>
+
+## Navigating the Master Object Model
+
+There are two ways to navigate around the MOM: upward and downward.
+Every object in the MOM knows its parent. If an event is received by an
+object like a button, the parent of that object usually can handle the
+event. The parent element can be accessed using the `parent` method.
+
+Searching upward further than one parent quickly becomes difficult to
+follow. So you can always search downward starting from the top.
+Every object in the MOM can access the root object using the `root`
+method. From the root you can access all MOM objects.
+
+There is a shortcut to find an object starting from the nearest element
+in the hierarchy that is a component. All semantical elements
+(like header and section) are components. All objects that are children
+of a component have immediate access to that component using the
+`component` method.
+
+<a name="styling"></a>
+
+## Styling Ferro elements
+
+The created elements still need some styling. Ferro uses a handy
+naming convention: CSS classnames match Ruby classnames.
+For example:
+
+    class DemoButton < Ferro::Form::Button
+    end
+
+When we create this button in the MOM, its DOM counterpart receives
+two classnames. One matching the Ruby classname `DemoButton` and
+one for its Ruby superclass `FerroFormButton`.
+These classnames are _dasherized_. In CSS you can reference these
+classnames as `demo-button` and `ferro-form-button`.
+
+<a name="more"></a>
+
+## More information
+
+Please see the [Ferro website](https://easydatawarehousing.github.io/ferro/)
+for more information and examples.
+The [source code](https://github.com/easydatawarehousing/ferro)
+for that webapp is a good Ferro example in itself.
+
+For some simple boilerplate code to get started with Ferro you can use
+[this Rails example](https://github.com/easydatawarehousing/ferro-example-todolist).

data/lib/opal-ferro/version.rb

@@ -1,5 +1,13 @@
+# Ferro relies on Opal to run in the webbrowser.
 module Opal
+
+  # This module contains all Ferro functionality.
   module Ferro
-    VERSION = "0.10.0"
+    # Opal-Ferro follows the versioning scheme of Opal.
+    # The first two parts of the version number of Ferro imply
+    # compatibility with the Opal version with that same number.
+    # So Ferro 0.10.x should be compatible with and dependant
+    # on Opal 0.10.x.
+    VERSION = "0.10.1"
   end
-end
+end

data/opal/opal-ferro/elements/ferro_combos.js.rb

@@ -0,0 +1,130 @@
+module Ferro
+
+  # This module contains some combined elements.
+  module Combo
+    # Creates a form with a text input and a submit button.
+    # Specify option :button_text to set the submit button text.
+    # Specify option :placeholder to set a placeholder text for the input.
+    # Two states are defined: search-input-open, search-submit-open
+    # to define CSS rules.
+    class Search < Form::Base
+      
+      # Internal method.
+      def _before_create
+        @button_text = option_replace :button_text, ' '
+        @placeholder = option_replace :placeholder, ' Search...'
+      end
+
+      # Internal method.
+      def cascade
+        add_child :entry,  SearchInput,  { placeholder: @placeholder }
+        add_child :submit, SearchSubmit, { content: @button_text }
+      end
+
+      # Internal method.
+      def do_submit
+        value = entry.value.strip
+        submitted(value) if !value.empty?
+
+        entry.toggle_state :search_input_open
+        submit.toggle_state :search_submit_open
+
+        entry.value = nil
+        entry.set_focus if entry.state_active?(:search_input_open)
+      end
+
+      # Override this method to specify what happens when
+      # submit button is clicked or enter key is pressed.
+      #
+      # @param [String] value The value of the text input.
+      def submitted(value);end
+    end
+
+    # Internal class for use with {Search}.
+    class SearchInput < Form::Input
+
+      # Internal method.
+      def _after_create
+        add_state :search_input_open
+        super
+      end
+
+      # Internal method.
+      def entered
+        parent.do_submit
+      end
+    end
+
+    # Internal class for use with {Search}.
+    class SearchSubmit < Form::Button
+
+      # Internal method.
+      def _after_create
+        add_state :search_submit_open
+        super
+      end
+
+      # Internal method.
+      def clicked
+        parent.do_submit
+      end
+    end
+
+    # Creates a simple pull-down menu.
+    # Specify option :title to set the menu title text.
+    # Specify option :items as an Array of Ferro classes.
+    # Each class should be something clickable, for instance a
+    # FormBlock. These classes will be instanciated by
+    # this element.
+    class PullDown < BaseElement
+
+      # Internal method.
+      def _before_create
+        @title_text = option_replace :title, '='
+        @items      = option_replace :items, []
+        super
+      end
+
+      # Internal method.
+      def _after_create
+        add_state :pull_down_open
+        super
+      end
+
+      # Internal method.
+      def cascade
+        add_child :title, PullDownTitle, { content: @title_text }
+        add_child :items, PullDownItems, { items:   @items }
+      end
+    end
+
+    # Internal class for use with {PullDown}.
+    # This element has a state: pull-down-open
+    # to define CSS rules.
+    class PullDownTitle < Form::Block
+
+      # Internal method.
+      def clicked
+        parent.toggle_state :pull_down_open
+      end
+    end
+
+    # Internal class for use with {PullDown}.
+    class PullDownItems < BaseElement
+
+      # Internal method.
+      def _before_create
+        @id       = Sequence.new 'pdi_'
+        @itemlist = option_replace :items, []
+        super
+      end
+
+      # Internal method.
+      def cascade
+        @items = @itemlist.map do |item|
+          add_child @id.next, item
+        end
+      end
+    end
+  end
+end

data/opal/opal-ferro/elements/ferro_components.js.rb

@@ -0,0 +1,82 @@
+module Ferro
+
+  # This module contains all semantic elements.
+  module Component
+    # A generic component element.
+    # In the DOM creates a: <div>.
+    # All semantical elements inherit from this class.
+    class Base < BaseElement
+
+      # Return self when called by children / descendants.
+      def component
+        self
+      end
+    end
+
+    # Creates a semantical element.
+    # This is a component.
+    # In the DOM creates a: <header>.
+    class Header < Base
+
+      # Internal method.
+      def _before_create
+        @domtype = :header
+      end
+    end
+
+    # Creates a semantical element.
+    # This is a component.
+    # In the DOM creates a: <nav>.
+    class Navigation < Base
+
+      # Internal method.
+      def _before_create
+        @domtype = :nav
+      end
+    end
+
+    # Creates a semantical element.
+    # This is a component.
+    # In the DOM creates a: <section>.
+    class Section < Base
+
+      # Internal method.
+      def _before_create
+        @domtype = :section
+      end
+    end
+
+    # Creates a semantical element.
+    # This is a component.
+    # In the DOM creates a: <article>.
+    class Article < Base
+
+      # Internal method.
+      def _before_create
+        @domtype = :article
+      end
+    end
+
+    # Creates a semantical element.
+    # This is a component.
+    # In the DOM creates a: <aside>.
+    class Aside < Base
+
+      # Internal method.
+      def _before_create
+        @domtype = :aside
+      end
+    end
+
+    # Creates a semantical element.
+    # This is a component.
+    # In the DOM creates a: <footer>.
+    class Footer < Base
+
+      # Internal method.
+      def _before_create
+        @domtype = :footer
+      end
+    end
+  end
+end