voom-presenters 0.1.10 → 2.0.0

data/lib/voom/presenters/errors.rb

@@ -0,0 +1 @@
+Dir[File.join(__dir__, 'errors', '*.rb')].each { |file| require file }

data/lib/voom/presenters/errors/invalid_dsl.rb

@@ -0,0 +1,8 @@
+module Voom
+  module Presenters
+    module Errors
+      class InvalidDsl < StandardError
+      end
+    end
+  end
+end

data/lib/voom/presenters/errors/parameter_validation.rb

@@ -1,5 +1,3 @@
-require_relative 'unprocessable'
-
 module Voom
   module Presenters
     module Errors
@@ -7,4 +5,4 @@ module Voom
       end
     end
   end
-end
+end

data/lib/voom/presenters/generators/inflectors.rb

@@ -0,0 +1,59 @@
+module Voom
+  module Presenters
+    module Generators
+      module Inflectors
+        def classify(input)
+          # "books" => "Book"
+          @inflector.classify(input)
+        end
+
+        def pluralize(input)
+          #book" => "books"
+          @inflector.pluralize(input)
+        end
+
+        def singularize(input)
+          #"books" => "book"
+          @inflector.singularize(input)
+        end
+
+        def camelize(input)
+          # "dry/inflector" => "Dry::Inflector"
+          @inflector.camelize(input)
+        end
+
+        def tableize(input)
+          # "Book" => "books"
+          @inflector.tableize(input)
+        end
+
+        def dasherize(input)
+          # "dry_inflector" => "dry-inflector"
+          @inflector.dasherize(input)
+        end
+
+        def underscore(input)
+          # "dry-inflector" => "dry_inflector"
+          @inflector.underscore(input)
+        end
+
+        def demodulize(input)
+          # "Dry::Inflector"  => "Inflector"
+          @inflector.demodulize(input)
+        end
+
+        def humanize(input)
+          # "dry_inflector"  => "Dry inflector", "author_id" => "Author"
+          @inflector.humanize(input)
+        end
+
+        def ordinalize(input)
+          # 1 => "1st
+          @inflector.ordinalize(input)
+        end
+
+      end
+    end
+  end
+end
+

data/lib/voom/presenters/generators/plugin.rb

@@ -0,0 +1,115 @@
+require "dry/inflector"
+require_relative 'inflectors'
+
+module Voom
+  module Presenters
+    module Generators
+      class Plugin < ::Thor::Group
+        TEMPLATES_ROOT = File.join('templates','plugin')
+        LIB_ROOT = File.join('lib','voom','presenters','plugins')
+        include Thor::Actions
+        argument :name
+
+        def initialize(args = [], local_options = {}, config = {})
+          @inflector = Dry::Inflector.new
+          super
+        end
+
+        def self.source_root
+          File.dirname(__FILE__)
+        end
+
+        no_tasks do
+          include Voom::Presenters::Generators::Inflectors
+
+          def join_path(*parts)
+            File.join(*parts.compact)
+          end
+
+          def template_file(template, target_filename=template, source_path=nil, target_path=source_path)
+            underscore_name = underscored_name
+            source = join_path(TEMPLATES_ROOT, source_path, "#{template}.tt")
+            destination = join_path(underscore_name, target_path, target_filename)
+            template source, destination
+          end
+
+          def file(file, target_filename=file, source_path=nil, target_path=nil)
+            underscore_name = underscored_name
+            source = join_path(TEMPLATES_ROOT, source_path, file)
+            destination = join_path(underscore_name, target_path, target_filename)
+
+            copy_file source, destination
+          end
+
+          def lib_dir(*args)
+            dir(LIB_ROOT, *args)
+          end
+
+          def dir(*args)
+            join_path(*args)
+          end
+          
+          def named_dir(*args)
+            lib_dir(underscored_name, *args)
+          end
+          
+          def underscored_name
+            underscore(name)
+          end
+        end
+
+        def create_root_files
+          file('.gitignore')
+          file('Gemfile')
+          template_file('LICENSE.txt')
+          template_file('presenter_plugin.gemspec', "#{underscored_name}_presenter_plugin.gemspec")
+          file 'README.md'
+        end
+
+        def create_plugin
+          template_file('plugin.rb', "#{underscored_name}.rb", LIB_ROOT)
+        end
+
+        def create_component_files
+          template_file('component.rb', "#{underscored_name}_component.rb",
+                        lib_dir('components'),
+                        named_dir('components'))
+          template_file('dsl.rb', "#{underscored_name}_dsl.rb",
+                        lib_dir('components'),
+                        named_dir('components'))
+          template_file('render.rb', "#{underscored_name}_render.rb",
+                        lib_dir('web_client', 'components'),
+                        named_dir('web_client', 'components'))
+          template_file('component.css', "#{underscored_name}.css",
+                        dir('views', 'assets', 'css', 'components'))
+          template_file('component.js', "#{underscored_name}.js",
+                        dir('views', 'assets', 'js', 'components'))
+          template_file('component.erb', "#{underscored_name}.erb",
+                        dir('views', 'components'))
+          template_file('component_header.erb', "#{underscored_name}_header.erb",
+                        dir('views', 'components'))
+        end
+
+        def create_action_files
+          template_file('action.rb', "#{underscored_name}_action.rb",
+                        lib_dir('components', 'actions'),
+                        named_dir('components', 'actions'))
+          template_file('dsl.rb', "#{underscored_name}_dsl.rb",
+                        lib_dir('components', 'actions'),
+                        named_dir('components', 'actions'))
+          template_file('data.rb', "#{underscored_name}_data.rb",
+                        lib_dir('web_client', 'components', 'actions'),
+                        named_dir('web_client', 'components', 'actions'))
+          template_file('action.js', "#{underscored_name}.js",
+                        dir('views', 'assets', 'js', 'components', 'actions'))
+        end
+
+        def create_helper_files
+          template_file('helper.rb', "#{underscored_name}_helper.rb",
+                        lib_dir('helpers'),
+                        named_dir('helpers'))
+        end
+      end
+    end
+  end
+end

data/lib/voom/presenters/generators/templates/plugin/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+.idea

data/lib/voom/presenters/generators/templates/plugin/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+# git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in voom-sample_presenter_plugin.gemspec
+gemspec

data/lib/voom/presenters/generators/templates/plugin/LICENSE.txt.tt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <%= Time.new.year %> <%=`git config user.name`.strip%> (<%= `git config user.email`.strip %>)
+
+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/lib/voom/presenters/generators/templates/plugin/README.md

@@ -0,0 +1,253 @@
+# Presenter Plugins
+
+Presenter plugins allows extension and modification of the DSL and WebClient.
+It is powerfully designed for adding additional components to the system, or to change the behavior/look feel/capabilities of existing components.
+
+## Global Plugins
+
+Presenters have global plugins that are configured in the system. They are declared as a setting like so:
+  
+    Voom::Presenters::Settings.configure do |config|
+      config.presenters.plugins.push(:foo)
+    end 
+
+A global plugin is available to all presenters.
+
+## Local Plugins
+
+A presenters can define that it uses a plugin like so: 
+
+    Voom::Presenters.define(:index, namespace: :plugins) do
+      plugin :foo
+    end
+
+A local plugin is available only to the presenter that it is defined in.
+
+
+## Creating Plugins
+
+The skeleton for a plugin starts with an empty module in a file stored in `voom/presenters/plugins` somewhere in ruby's load path 
+(typically in a gemfile or in the lib directory of an framework app, like Rails):
+
+    module Voom
+      module Presenters
+        module Plugins
+          module Foo
+          end
+        end
+      end
+    end
+
+## Extending the presenter DSL and POM
+
+### Components
+If you want to add additional components to the presenters DSL, provide a `DSLComponents` module under the plugin module:
+
+     module DSLComponents
+       def foo(random_fact, **attributes, &block)
+         self << Foo::Component.new(random_fact, parent: self, **attributes, &block)
+       end
+     end
+
+The above example will extend the dsl by adding the foo method that will add the Foo component to the 
+presenter object model tree.
+
+A presenter component derives from `DSL::Components::Base` or if it needs to handle events  `DSL::Components::EventBase`
+
+      require 'voom/presenters/dsl/components/base'
+      
+      module Voom
+        module Presenters
+          module Plugins
+            module Foo
+              class Component < DSL::Components::Base
+                def initialize(**attribs_, &block)
+                  super(type: :foo, **attribs_, &block)
+                end      
+              end
+            end
+          end
+        end
+      end
+      
+### Helpers
+
+To add helpers to the POM define the module `DSLHelpers`
+    
+    module DSLHelpers
+      def random_fact
+        "http://en.wikipedia.org/wiki/Special:Randompage"
+      end
+    end
+
+### Event Actions
+A plugin can extend the set of event actions that are available. 
+When an event fires in the client, like mouse click, a set of actions are executed. A plugin can provide custom
+actions. This examnple adds a actionJs actionJs that can be bound to an event.
+
+    module DSLEventActions
+      def actionJs(text, **attributes, &block)
+        self << Foo::Action.new(text: text, parent: self, **attributes, &block)
+      end
+    end
+    
+Example actionJs class:
+
+    require 'voom/presenters/dsl/components/actions/base'
+    
+    module Voom
+      module Presenters
+        module Plugins
+          module Foo
+              class Action < DSL::Components::Actions::Base
+                def initialize(**attribs_, &block)
+                  super(type: :actionJs, **attribs_, &block)
+                end
+            end
+          end
+        end
+      end
+    end
+
+    
+## Adding a WebClient implementation
+
+A plugin that extends the DSL will give you a new custom POM (Presenter Object Model), but that alone won't get you very far.
+The POM describes the user interface, a client must implement each of the components.
+For the WebClient this means adding a template with HTML, CSS and Javascript. 
+
+### Component Templates
+
+To render your component you need to add the following to your plugin:
+  
+    module WebClientComponents
+      def render_foo(comp,
+                     render:,
+                     components:,
+                     index:)
+        view_dir = File.join(__dir__, 'foo')
+        render.call :erb, :foo, views: view_dir,
+                    locals: {comp: comp,
+                             components: components, index: index}
+      end
+    end
+    
+From you ERB you can call any of the other built in WebClient erb's. You can even replace built in component templates.
+The render object supports all the template types supported by Tilt/Sinatra (http://sinatrarb.com/intro.html)
+
+Example template:
+
+    <iframe id="random_fact" src="<%= comp.random_fact %>" height=512 <%= erb :"components/event", :locals => {comp: comp, events: comp.events, parent_id: comp.id} %>></iframe>
+
+
+### Event Action Data
+
+An actionJs from the Presenter Object Model (POM) is sent to a ruby method during template expansion. 
+You are able to then setup any data that you want passed to your actionJs javascript method.
+It expects you will return an array with a type that matches your event actionJs presenter type. The rest is up to you.
+
+
+    module WebClientActions
+      def action_data_bar(actionJs, _parent_id, *)
+        # Type, URL, Options, Params (passed into javascript event/actionJs classes)
+        [actionJs.type, actionJs.url, actionJs.options.to_h, actionJs.attributes.to_h]
+      end
+    end
+    
+Example Javascript method (typically rendered by a template triggered by the render_foo method above):
+
+    <script>
+      function actionJs(_options, params, _event) {
+        // Reload iFrame: https://stackoverflow.com/questions/86428/what-s-the-best-way-to-reload-refresh-an-iframe
+        document.getElementById('random_fact').src += '';
+        return {actionJs: 'actionJs', content: {data: params.text}, statusCode: 200};
+      }
+    </script>
+
+Event actionJs WebClient methods must return a Javascript Object with the properties `actionJs`, `content` and `statusCode`.
+
+
+## WebClient Javascript Interface
+
+When developing a plugin for the WebClient you may want to have your data submitted as part of another component container.
+The most familiar example is a Form.  This requires that you bind your component to the DOM with a few methods.
+Not all plugins need to do this.
+It is only needed in the case of those components that add their data to an http post.
+
+The following components are Containers that will collect data from nested DOM elements using this lifecycle protocol.
+cards.js
+content.js
+dialogs.js
+file-inputs.js
+forms.js
+grid.js
+steppers.js
+
+Lifecycle Protocol:
+
+We call it it a protocol, because it defines a small number of DOM relationships to participate as an integrated component.
+Many frameworks require a common base class, this approach is very light by design.
+
+Container data in the WebClient is collected and submitted using the following sequence:
+
+In your element markup include the `v-input` class on an DOM element.
+
+You can see the container calling code here:
+https://github.com/rx/presenters/blob/master/views/mdc/assets/js/components/base-container.js
+
+If you add the v-plugin class to the DOM element along with a data-plugin-callback dataset that contains a string
+with the class name to proxy the plugin events to.
+
+
+Sample callback class:
+
+    // Optional Javascript callback class. You typically need to define this when you have data to submit, or special
+    // event handling to bind to.
+    // To hook this up you need to provide the `v-plugin` class and
+    // data-plugin-callback='RandomFacts' on the element.
+    class RandomFacts {
+      // passed the DOM element that has the .v-plugin class on it.
+      constructor(element) {
+      }
+  
+      // optional.
+      // Called before the component is submitted via post/put. Allows the component to add its key/value pairs to the
+      // submitted data.
+      // If you provide this you need to add the v-input class to your DOM element to get called.
+      // Containers iterate their elements that have the v-input class defined on them and invoke the prepareSubmit
+      // function for each.
+      prepareSubmit(params) {
+        // params is a key,value pair. Add name/value like so:
+        // params.push(['some_name', 'some_value']);
+      }
+  
+      // optional.
+      // Called whenever a container is about to be submitted, before prepareSubmit.
+      // returns true on success
+      // returns on failure return an error object that can be processed by VErrors:
+      //    { email: ["email must be filled", "email must be from your domain"] }
+      //    { page:  ["must be filled"] }
+      // Returning an error stops the submission.
+      validate(formData) {
+        return true;
+      }
+  
+      // optional.
+      // Clear's the control
+      clear() {
+      }
+  
+      // called to add an event listener to the component
+      // this only needs to be defined if you need the event handler to be bound to the component
+      // in a different manner.  Here is the default implementation you get if you don't define this method:
+      initEventListener(eventName, eventHandler) {
+        if (typeof this.eventsHandler === 'undefined') {
+          this.eventsHandler = {};
+        }
+        if (!this.eventsHandler[eventName]) {
+          // Delegate to the component if possible
+          this.eventsHandler[eventName] = eventHandler;
+          this.element.addEventListener(eventName, eventHandler);
+        }
+      }
+    }