magicka 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 790574b274384507133ba81bff57316fdee267695e6a86bbb36da2065d98f918
-  data.tar.gz: ded516626da7b9825e1711aa4d299cd0388de7293776cc20c9facc607b4ba8ef
+  metadata.gz: 89c43463111b2c2105250a275a53b80861b06ad90881585c2928174728931567
+  data.tar.gz: 4c9f0a23503fc925cd60657706797e37596ae6e11b8e6d78c2e082124a0cbc78
 SHA512:
-  metadata.gz: a2fb23dfa2dca070216bede19831ca54bc0c9ee1340418848e647512d4ec7668ee97b0015aa8d7d3b85e6014883e263107ce8360efed4286342e714f502d93ce
-  data.tar.gz: 6e165bd37c83eb5d3c0c760164f2f93e9d51d05f284621960012e24b81d5b7779140cca6f1d47128bd24a4545201e77becd489fa20d9e0ac6ba816cd01dc8fdf
+  metadata.gz: ce20ae0d689c937f5c414288eeb493c3438c1f592f557286747fd9879c742288391a7cf619def37cfbb9d02a059572b77a1c13841ee34a8ae7d92536d7c58786
+  data.tar.gz: c665834d06f7ab392b350045279d062a3fdb6f66e008907c22cf0a221eed8b4c5af353a93501fabf156d19837984351f12b16c55c4def4b79dbb69f7b40f10a2

data/.circleci/config.yml

@@ -22,7 +22,7 @@ workflows:
 jobs:
   test:
     docker:
-      - image: darthjee/circleci_rails_gems:0.6.0
+      - image: darthjee/circleci_rails_gems:0.7.0
         environment:
           PROJECT: magicka
     steps:
@@ -41,7 +41,7 @@ jobs:
           command: cc-test-reporter after-build --exit-code $?
   checks:
     docker:
-      - image: darthjee/circleci_rails_gems:0.6.0
+      - image: darthjee/circleci_rails_gems:0.7.0
         environment:
           PROJECT: magicka
     steps:
@@ -66,7 +66,7 @@ jobs:
           command: check_specs
   build-and-release:
     docker:
-      - image: darthjee/circleci_rails_gems:0.5.4
+      - image: darthjee/circleci_rails_gems:0.7.0
         environment:
           PROJECT: magicka
     steps:

data/.rubocop.yml

@@ -32,7 +32,7 @@ RSpec/MultipleExpectations:
     - 'spec/integration/readme/**/*_spec.rb'
 
 RSpec/NestedGroups:
-  Max: 4
+  Max: 5
   Exclude:
     - 'spec/integration/yard/**/*.rb'
 

data/Dockerfile

@@ -1,6 +1,6 @@
 FROM darthjee/scripts:0.1.8 as scripts
 
-FROM darthjee/rails_gems:0.6.0 as base
+FROM darthjee/rails_gems:0.7.0 as base
 
 COPY --chown=app:app ./ /home/app/app/
 

data/README.md

@@ -9,20 +9,23 @@ Magicka
 
 ![magicka](https://raw.githubusercontent.com/darthjee/magicka/master/magicka.jpg)
 
+Magica helps creating html templates for forms and display data using js applications
+such as AngulaJS
+
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/magicka/0.5.3](https://www.rubydoc.info/gems/magicka/0.5.3)
+[https://www.rubydoc.info/gems/magicka/0.6.0](https://www.rubydoc.info/gems/magicka/0.6.0)
 
 Installation
 ---------------
 
--   Install it
+ - Install it
 
 ```ruby
   gem install magicka
 ```
 
--   Or add Magicka to your `Gemfile` and `bundle install`:
+ - Or add Magicka to your `Gemfile` and `bundle install`:
 
 ```ruby
   gem 'magicka'
@@ -31,3 +34,76 @@ Installation
 ```bash
   bundle install magicka
 ```
+
+## Usage
+Magicka is used as a helper for erb coding so that each element is paired with an
+element class, a template and a method in an aggregator.
+
+Different aggregators have the same method so that they render the same `element` in
+different ways
+
+### example
+```html.erb
+<!-- new.html.erb -->
+
+<% magicka_form('controller.person') do |form| %>
+  <%= render partial: 'person_form', locals: { form: form } %>
+<% end %>
+```
+
+```html.erb
+<!-- show.html.erb -->
+
+<% magicka_display('controller.person') do |form| %>
+  <%= render partial: 'person_form', locals: { form: form } %>
+<% end %>
+```
+
+```html.erb
+<!-- _person_form.html.erb -->
+
+<%= form.input(:first_name) %>
+<%= form.input(:last_name) %>
+<%= form.input(:age) %>
+<%= form.select(:gender, options: %w[MALE FEMALE] %>
+
+<%= form.only(:form) do %>
+  <!-- this block only appears in a form -->
+  <%= form.button(ng_click: 'controller.save', text: 'Save') %>
+<% end %>
+```
+
+## Configuring
+In order to use magicka, the helper has to added to the controllers and any custom
+element needs to added
+
+`app/controllers/application_controller.rb`
+```ruby
+class ApplicationController < ActionController::Base
+  helper Magicka::Helper
+end
+```
+
+### Including custom elements
+
+Elements can be included by defining attributes that they can be initialized with
+and that can be passed to the template
+
+`config/initializers/magicka.rb`
+```ruby
+module Magicka
+  class MyTextInput < Magicka::Element
+    with_attribute_locals :label, :field, :id
+  end
+end
+
+Magicka::Form.with_element(Magicka::MyTextInput)
+```
+
+`templates/form/_my_text_input.html.erb`
+```html.erb
+<div>
+  <label for="<%= field %>"><%= label %></label>
+  <input type="text" id="<%= id %>" name="field" />
+</div>
+```

data/config/check_specs.yml

@@ -1,6 +1,7 @@
 ignore:
   - lib/magicka/version.rb
   - lib/magicka.rb
-  - lib/magicka/aggregator.rb
+  - lib/magicka/aggregator/class_methods.rb
   - lib/magicka/aggregator/method_builder.rb
-  - lib/magicka/helper.rb
+  - lib/magicka/helper/class_methods.rb
+  - lib/magicka/helper/method_builder.rb

data/config/yardstick.yml

@@ -1,4 +1,4 @@
-threshold: 84.2
+threshold: 90.0
 require_exact_threshold: false
 rules:
   ApiTag::Presence:
@@ -23,6 +23,8 @@ rules:
     enabled: true
     exclude:
       - Magicka::Element#initialize
+      - Magicka::Aggregator#initialize
+      - Magicka::Aggregator::MethodBuilder#initialize
   Summary::Length:
     enabled: true
     exclude: []

data/lib/magicka/aggregator/class_methods.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Magicka
+  class Aggregator
+    # Class methods for {Magicka::Aggregator}
+    module ClassMethods
+      # (see Aggregator.with_element)
+      def with_element(element_class, method_name = nil, template: nil)
+        MethodBuilder
+          .new(self, element_class, method_name, template: template)
+          .prepare
+          .build
+      end
+
+      # Set and return the type of the aggregator
+      #
+      # When new_type is ommited, returns the last value
+      #
+      # @param new_type [Symbol,String] The value to be set
+      #
+      # @return [Symbol] the type of the aggregator
+      def type(new_type = nil)
+        return @type ||= default_type unless new_type
+
+        @type = new_type.to_sym
+      end
+
+      private
+
+      # @private
+      # @api private
+      #
+      # Default type when type is not defined
+      #
+      # Default type is extracted from class name
+      #
+      # @return [Symbol]
+      def default_type
+        name&.demodulize&.underscore&.to_sym
+      end
+    end
+  end
+end

data/lib/magicka/aggregator/method_builder.rb

@@ -6,19 +6,33 @@ module Magicka
     #
     # Class responsible for building an {Aggregator} method
     class MethodBuilder < Sinclair
-      def initialize(klass, element_class, method_name = nil)
+      # @param klass [Class.new<Aggregator>]
+      #   Aggragator class to receive the method
+      # @param element_class [Class<Magicka::ELement>]
+      #   Class of the element to be rendered
+      # @param method_name [String,Symbol]
+      #   Name of the method that will render the element
+      # @param template [String] custom template file to be used
+      def initialize(klass, element_class, method_name = nil, template: nil)
         super(klass)
 
         @element_class = element_class
         @method_name = method_name
+        @template = template
       end
 
+      # Prepare methods to be built
+      #
+      # @return [Aggregator::MethodBuilder] return self
       def prepare
         element_klass = element_class
+        template_file = template
 
         add_method(method_name) do |field, model: self.model, **args|
           element_klass.render(
-            renderer: renderer, field: field, model: model, **args
+            renderer: renderer, field: field,
+            model: model, template: template_file,
+            **args
           )
         end
 
@@ -27,8 +41,29 @@ module Magicka
 
       private
 
-      attr_reader :element_class
+      attr_reader :element_class, :template
+      # @method element_class
+      # @api private
+      # @private
+      #
+      # Class of the element to be rendered by the method
+      #
+      # @return [Class<Magicka::Element>]
 
+      # @method template
+      # @api private
+      # @private
+      #
+      # template file
+      #
+      # @return [String]
+
+      # name of the method to be generated
+      #
+      # When the method name was not supplied in the constructor,
+      # it is infered from {#element_class}
+      #
+      # @return [String,Symbol]
       def method_name
         @method_name ||= element_class
                          .name

data/lib/magicka/aggregator.rb

@@ -6,29 +6,86 @@ module Magicka
   # Class representing an element agregator, representing a model
   class Aggregator
     autoload :MethodBuilder, 'magicka/aggregator/method_builder'
+    autoload :ClassMethods,  'magicka/aggregator/class_methods'
 
     class << self
-      def with_element(element_class, method_name = nil)
-        MethodBuilder
-          .new(self, element_class, method_name)
-          .prepare
-          .build
-      end
+      include Aggregator::ClassMethods
     end
 
     attr_reader :model
+    # @method model
+    # @api public
+    #
+    # Model where the form elements will focus
+    #
+    # @return [String]
 
+    # @method self.with_element(element_class, method_name = nil, template: nil)
+    #
+    # Configure an {Aggregator} adding a method to render an element
+    #
+    # @param element_class [Class<Magicka::ELement>]
+    #   Class of the element to be rendered
+    # @param method_name [String,Symbol]
+    #   Name of the method that will render the element
+    # @param template [String] custom template file to be used
+    #
+    # @see Aggregator::ClassMethods#with_element
+    # @see Aggregator::MethodBuilder
+    #
+    # @return [Array<NilClass>]
+
+    # @param renderer [ActionView::Base] Object responsible for rendering
+    # @param model [String] Model where the form elements will focus
     def initialize(renderer, model)
       @renderer = renderer
       @model    = model
     end
 
+    # Returns a new aggregator focusing on a new model
+    #
+    # The new model is an attribute of +model+ unless base is given
+    #
+    # @param model [String] Model where the form elements will focus
+    # @param base [String] Model base
+    #
+    # @yield [Aggregator] new aggregator focused in the new model
+    #
+    # @return [Aggregator]
     def with_model(model, base: self.model)
       new_model = [base, model].compact.join('.')
 
       yield self.class.new(renderer, new_model)
     end
 
+    # Executes a block only when aggregator is one of given types
+    #
+    # @param types [Array<Symbol>] posssible types
+    #
+    # @return [Object] Result of the block
+    def only(*types)
+      return unless types.include?(self.class.type)
+
+      yield
+    end
+
+    # Executes a block only when aggregator is not one of given types
+    #
+    # @param types [Array<Symbol>] posssible types
+    #
+    # @return [Object] Result of the block
+    def except(*types)
+      return if types.include?(self.class.type)
+
+      yield
+    end
+
+    # @api private
+    # Checks if other aggragate is equal to this one
+    #
+    # @param [Object] other object to be compared
+    #
+    # @return [TrueClass,FalseClass]
     def equal?(other)
       return unless other.class == self.class
 
@@ -41,6 +98,13 @@ module Magicka
     protected
 
     attr_reader :renderer
+    # @method renderer
+    # @private
+    # @api private
+    #
+    # Returns the element needed to render the view
+    #
+    # @return [ActionView::Base]
 
     delegate :render, to: :renderer
   end

data/lib/magicka/display.rb

@@ -1,11 +1,43 @@
 # frozen_string_literal: true
 
 module Magicka
+  # @api public
+  #
   # Class responsible for controlling one object display
   class Display < Aggregator
     with_element(Text, :input)
     with_element(Text, :select)
 
+    # Noop
+    #
+    # Used to not render a button when using
+    # display and not form
+    #
+    # #return [NilClass]
     def button(**_args); end
+
+    # @method input(field, model: self.model, **options)
+    # @api public
+    #
+    # @param field [String,Symbol] field to be shown
+    # @param model [String] model being rendered
+    #   (when omited, use the aggregator model)
+    # @param options [Hash]
+    #
+    # @see Magicka::Text
+    #
+    # @return (see Magicka::Element#render)
+
+    # @method select(field, model: self.model, **options)
+    # @api public
+    #
+    # @param field [String,Symbol] field to be shown
+    # @param model [String] model being rendered
+    #   (when omited, use the aggregator model)
+    # @param options [Hash]
+    #
+    # @see Magicka::Text
+    #
+    # @return (see Magicka::Element#render)
   end
 end

data/lib/magicka/element/method_builder.rb

@@ -14,7 +14,7 @@ module Magicka
       #
       # @return [Array<Sinclair::MethodDefinition>]
       def add_template(template)
-        add_method(:template) do
+        add_method(:template, cached: true) do
           template
         end
 
@@ -25,7 +25,7 @@ module Magicka
       #
       # The method will always return the template folder given in the params
       #
-      # @param template_folder [String] path to template folder
+      # @param folder [String] path to template folder
       #
       # @return [Array<Sinclair::MethodDefinition>]
       def add_template_folder(folder)

data/lib/magicka/element.rb

@@ -33,6 +33,9 @@ module Magicka
     # @return [Array]
 
     # Render element HTML
+    # @api private
+    #
+    # @return [ActionView::OutputBuffer]
     def render
       renderer.render partial: template, locals: locals
     end
@@ -77,8 +80,11 @@ module Magicka
     #
     # @return [String]
     def template
-      self.class.name.underscore
-          .gsub(%r{^.*/}, "#{template_folder}/")
+      @template ||= self
+                    .class
+                    .name
+                    .underscore
+                    .gsub(%r{^.*/}, "#{template_folder}/")
     end
   end
 end

data/lib/magicka/form.rb

@@ -6,8 +6,35 @@ module Magicka
     with_element(Input)
     with_element(Select)
 
+    # Renders a button
+    #
+    # @return (see Magicka::Element#render)
     def button(**args)
       Button.render(renderer: renderer, **args)
     end
+
+    # @method input(field, model: self.model, **options)
+    # @api public
+    #
+    # @param field [String,Symbol] field to be shown
+    # @param model [String] model being rendered
+    #   (when omited, use the aggregator model)
+    # @param options [Hash]
+    #
+    # @see Magicka::Input
+    #
+    # @return (see Magicka::Element#render)
+
+    # @method select(field, model: self.model, **options)
+    # @api public
+    #
+    # @param field [String,Symbol] field to be shown
+    # @param model [String] model being rendered
+    #   (when omited, use the aggregator model)
+    # @param options [Hash]
+    #
+    # @see Magicka::Select
+    #
+    # @return (see Magicka::Element#render)
   end
 end

data/lib/magicka/helper/class_methods.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Magicka
+  module Helper
+    # Class methods for {Magicka::Helper}
+    module ClassMethods
+      # (see Magicka::Helper.with)
+      def with(aggregator_class, type = aggregator_class.type)
+        MethodBuilder.new(self).build_aggregator(aggregator_class, type)
+      end
+    end
+  end
+end

data/lib/magicka/helper/method_builder.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Magicka
+  module Helper
+    # Builds methods for {Magicka::Helper}
+    class MethodBuilder < Sinclair
+      # (see Magicka::Helper.with)
+      def build_aggregator(aggregator_class, type = aggregator_class.type)
+        add_method("magicka_#{type}") do |model, &block|
+          block.call(aggregator_class.new(self, model))
+        end
+
+        build
+      end
+    end
+  end
+end

data/lib/magicka/helper.rb

@@ -3,12 +3,55 @@
 module Magicka
   # Helper module to be used on rails
   module Helper
-    def magicka_form(model)
-      yield Form.new(self, model)
-    end
+    autoload :ClassMethods,  'magicka/helper/class_methods'
+    autoload :MethodBuilder, 'magicka/helper/method_builder'
 
-    def magicka_display(model)
-      yield Display.new(self, model)
+    class << self
+      include Helper::ClassMethods
     end
+
+    with Form
+    with Display
+
+    # @method self.with(aggregator_class, type = aggregator_class.type)
+    #
+    # Adds a helper method magicka_+type+
+    #
+    # The created method executes a block with a an aggragator
+    #
+    # @param aggregator_class [Class<Magicka::Aggregator>]
+    #   Agragator to be initialized
+    # @param type [String,Symbol] type of aggregator,
+    #   this will define the method name
+    #
+    # @return [Array<NilClass>]
+
+    # @method magicka_form(model)
+    #
+    # Execute a block with an aggregator focused on a model
+    #
+    # The aggregator renders elements as form elements
+    #
+    # @param model [String] Model to be processed
+    #
+    # @yield [Magicka::Form] Agregator to edit a model
+    #
+    # @see Magicka::Form
+    #
+    # @return [String]
+
+    # @method magicka_display(model)
+    #
+    # Execute a block with an aggregator focused on a model
+    #
+    # The aggregator renders elements as display elements
+    #
+    # @param model [String] Model to be processed
+    #
+    # @yield [Magicka::Display] Agregator to show a model
+    #
+    # @see Magicka::Display
+    #
+    # @return [String]
   end
 end

data/lib/magicka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magicka
-  VERSION = '0.5.3'
+  VERSION = '0.6.0'
 end

data/magicka.gemspec

@@ -19,31 +19,31 @@ Gem::Specification.new do |gem|
   gem.test_files            = gem.files.grep(%r{^(test|gem|features)/})
   gem.require_paths         = ['lib']
 
-  gem.add_runtime_dependency 'activesupport',       '~> 5.2.4.3'
+  gem.add_runtime_dependency 'activesupport',       '~> 5.2.x'
   gem.add_runtime_dependency 'sinclair',            '>= 1.6.7'
 
-  gem.add_development_dependency 'actionpack',               '5.2.4.3'
-  gem.add_development_dependency 'activerecord',             '5.2.4.3'
+  gem.add_development_dependency 'actionpack',               '~> 5.2.x'
+  gem.add_development_dependency 'activerecord',             '~> 5.2.x'
   gem.add_development_dependency 'bundler',                  '1.16.1'
   gem.add_development_dependency 'factory_bot',              '5.2.0'
-  gem.add_development_dependency 'nokogiri',                 '1.10.9'
+  gem.add_development_dependency 'nokogiri',                 '1.12.5'
   gem.add_development_dependency 'pry',                      '0.12.2'
   gem.add_development_dependency 'pry-nav',                  '0.3.0'
-  gem.add_development_dependency 'rails',                    '5.2.4.3'
+  gem.add_development_dependency 'rails',                    '~> 5.2.x'
   gem.add_development_dependency 'rails-controller-testing', '1.0.4'
   gem.add_development_dependency 'rake',                     '13.0.1'
-  gem.add_development_dependency 'reek',                     '5.6.0'
+  gem.add_development_dependency 'reek',                     '6.0.3'
   gem.add_development_dependency 'rspec',                    '3.9.0'
-  gem.add_development_dependency 'rspec-core',               '3.9.1'
-  gem.add_development_dependency 'rspec-expectations',       '3.9.1'
+  gem.add_development_dependency 'rspec-core',               '3.9.3'
+  gem.add_development_dependency 'rspec-expectations',       '3.9.4'
   gem.add_development_dependency 'rspec-mocks',              '3.9.1'
-  gem.add_development_dependency 'rspec-rails',              '3.9.0'
-  gem.add_development_dependency 'rspec-support',            '3.9.2'
+  gem.add_development_dependency 'rspec-rails',              '3.9.1'
+  gem.add_development_dependency 'rspec-support',            '3.9.4'
   gem.add_development_dependency 'rubocop',                  '0.80.1'
   gem.add_development_dependency 'rubocop-rspec',            '1.38.1'
-  gem.add_development_dependency 'rubycritic',               '4.4.1'
+  gem.add_development_dependency 'rubycritic',               '4.6.1'
   gem.add_development_dependency 'simplecov',                '0.17.1'
   gem.add_development_dependency 'sqlite3',                  '1.4.2'
-  gem.add_development_dependency 'yard',                     '0.9.24'
+  gem.add_development_dependency 'yard',                     '0.9.26'
   gem.add_development_dependency 'yardstick',                '0.9.9'
 end