magicka 0.5.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b014302f0498ecea2e69670c168bdf2ee5eaaa8162b210faf007351d4417976
-  data.tar.gz: 1ee57425d99ce223334f9567156ff1ab791f78e6f043c9ae5adca87291e28f1b
+  metadata.gz: 89c43463111b2c2105250a275a53b80861b06ad90881585c2928174728931567
+  data.tar.gz: 4c9f0a23503fc925cd60657706797e37596ae6e11b8e6d78c2e082124a0cbc78
 SHA512:
-  metadata.gz: 37e81304adc719f63fd65d3a643d2392cca27fdce94489072f675571b440815f074e9bf5613bf365dae1b8f26edc24cdf4a564d8821e69a49d4419488bf7cd0c
-  data.tar.gz: 20b572511516fd8af749499059b2d14d01bf0047fbe3b509304b4c117032b617427aa84d7389ed400aa5b9acfb0d6c6dff539cd67e448b55e0c25dd5582f17ab
+  metadata.gz: ce20ae0d689c937f5c414288eeb493c3438c1f592f557286747fd9879c742288391a7cf619def37cfbb9d02a059572b77a1c13841ee34a8ae7d92536d7c58786
+  data.tar.gz: c665834d06f7ab392b350045279d062a3fdb6f66e008907c22cf0a221eed8b4c5af353a93501fabf156d19837984351f12b16c55c4def4b79dbb69f7b40f10a2

data/README.md

@@ -14,7 +14,7 @@ such as AngulaJS
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/magicka/0.5.6](https://www.rubydoc.info/gems/magicka/0.5.6)
+[https://www.rubydoc.info/gems/magicka/0.6.0](https://www.rubydoc.info/gems/magicka/0.6.0)
 
 Installation
 ---------------
@@ -66,7 +66,11 @@ different ways
 <%= form.input(:last_name) %>
 <%= form.input(:age) %>
 <%= form.select(:gender, options: %w[MALE FEMALE] %>
-<%= form.button(ng_click: 'controller.save', text: 'Save') %>
+
+<%= form.only(:form) do %>
+  <!-- this block only appears in a form -->
+  <%= form.button(ng_click: 'controller.save', text: 'Save') %>
+<% end %>
 ```
 
 ## Configuring

data/config/check_specs.yml

@@ -1,5 +1,7 @@
 ignore:
   - lib/magicka/version.rb
   - lib/magicka.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.1
+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,6 +6,13 @@ module Magicka
     #
     # Class responsible for building an {Aggregator} method
     class MethodBuilder < Sinclair
+      # @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)
 
@@ -14,6 +21,9 @@ module Magicka
         @template = template
       end
 
+      # Prepare methods to be built
+      #
+      # @return [Aggregator::MethodBuilder] return self
       def prepare
         element_klass = element_class
         template_file = template
@@ -32,7 +42,28 @@ module Magicka
       private
 
       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, template: nil)
-        MethodBuilder
-          .new(self, element_class, method_name, template: template)
-          .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

@@ -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

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.6'
+  VERSION = '0.6.0'
 end

data/magicka.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |gem|
   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.11.4'
+  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.x'

data/spec/lib/magicka/aggregator_spec.rb

@@ -11,6 +11,31 @@ describe Magicka::Aggregator do
   let(:template)         { 'templates/forms/input' }
   let(:locals)           { {} }
 
+  describe '.type' do
+    let(:type) { %w[form display other].sample }
+
+    it 'sets aggregator type' do
+      expect { aggregator_class.type(type) }
+        .to change(aggregator_class, :type)
+        .from(nil).to(type.to_sym)
+    end
+
+    context 'when type has not been set' do
+      let(:aggregator_class) do
+        Class.new(described_class) do
+          def self.name
+            'Magicka::MyClass'
+          end
+        end
+      end
+
+      it 'Uses class name as type' do
+        expect(aggregator_class.type)
+          .to eq(:my_class)
+      end
+    end
+  end
+
   describe '.with_element' do
     context 'when seeting element class only' do
       it do
@@ -206,4 +231,68 @@ describe Magicka::Aggregator do
       end
     end
   end
+
+  describe '#with_model' do
+    let(:expected_aggregator) do
+      aggregator_class.new(renderer, 'my_model.inner')
+    end
+
+    it do
+      aggregator.with_model(:inner) do |new_aggregator|
+        expect(new_aggregator).to eq(expected_aggregator)
+      end
+    end
+  end
+
+  describe '#only' do
+    let(:aggregator_class) do
+      Class.new(described_class) do
+        type :included
+      end
+    end
+
+    context 'when the type is included in the list' do
+      it 'executes the block' do
+        value = 0
+
+        aggregator.only(:not_included, :included, :other) { value += 1 }
+        expect(value).to eq(1)
+      end
+    end
+
+    context 'when the type is not included in the list' do
+      it 'does not execute the block' do
+        value = 0
+
+        aggregator.only(:not_included, :other) { value += 1 }
+        expect(value).to be_zero
+      end
+    end
+  end
+
+  describe '#except' do
+    let(:aggregator_class) do
+      Class.new(described_class) do
+        type :included
+      end
+    end
+
+    context 'when the type is included in the list' do
+      it 'does not execute the block' do
+        value = 0
+
+        aggregator.except(:not_included, :included, :other) { value += 1 }
+        expect(value).to be_zero
+      end
+    end
+
+    context 'when the type is not included in the list' do
+      it 'executes the block' do
+        value = 0
+
+        aggregator.except(:not_included, :other) { value += 1 }
+        expect(value).to eq(1)
+      end
+    end
+  end
 end

data/spec/lib/magicka/display_spec.rb

@@ -16,6 +16,12 @@ describe Magicka::Display do
       .with(partial: template, locals: locals)
   end
 
+  describe '.type' do
+    it do
+      expect(described_class.type).to eq(:display)
+    end
+  end
+
   describe '#input' do
     let(:template)    { 'templates/display/text' }
     let(:field)       { :field }
@@ -166,4 +172,44 @@ describe Magicka::Display do
       end
     end
   end
+
+  describe '#only' do
+    context 'when the type is included in the list' do
+      it 'executes the block' do
+        value = 0
+
+        form.only(:not_included, :display, :other) { value += 1 }
+        expect(value).to eq(1)
+      end
+    end
+
+    context 'when the type is not included in the list' do
+      it 'does not execute the block' do
+        value = 0
+
+        form.only(:not_included, :other) { value += 1 }
+        expect(value).to be_zero
+      end
+    end
+  end
+
+  describe '#except' do
+    context 'when the type is included in the list' do
+      it 'does not execute the block' do
+        value = 0
+
+        form.except(:not_included, :display, :other) { value += 1 }
+        expect(value).to be_zero
+      end
+    end
+
+    context 'when the type is not included in the list' do
+      it 'executes the block' do
+        value = 0
+
+        form.except(:not_included, :other) { value += 1 }
+        expect(value).to eq(1)
+      end
+    end
+  end
 end

data/spec/lib/magicka/form_spec.rb

@@ -16,6 +16,12 @@ describe Magicka::Form do
       .with(partial: template, locals: locals)
   end
 
+  describe '.type' do
+    it do
+      expect(described_class.type).to eq(:form)
+    end
+  end
+
   describe '#input' do
     let(:template)    { 'templates/forms/input' }
     let(:field)       { :field }
@@ -180,4 +186,44 @@ describe Magicka::Form do
       end
     end
   end
+
+  describe '#only' do
+    context 'when the type is included in the list' do
+      it 'executes the block' do
+        value = 0
+
+        form.only(:not_included, :form, :other) { value += 1 }
+        expect(value).to eq(1)
+      end
+    end
+
+    context 'when the type is not included in the list' do
+      it 'does not execute the block' do
+        value = 0
+
+        form.only(:not_included, :other) { value += 1 }
+        expect(value).to be_zero
+      end
+    end
+  end
+
+  describe '#except' do
+    context 'when the type is included in the list' do
+      it 'does not execute the block' do
+        value = 0
+
+        form.except(:not_included, :form, :other) { value += 1 }
+        expect(value).to be_zero
+      end
+    end
+
+    context 'when the type is not included in the list' do
+      it 'executes the block' do
+        value = 0
+
+        form.except(:not_included, :other) { value += 1 }
+        expect(value).to eq(1)
+      end
+    end
+  end
 end

data/spec/lib/magicka/helper_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Magicka::Helper do
+  subject(:object) { klass.new }
+
+  let(:klass) do
+    Class.new do
+      include Magicka::Helper
+    end
+  end
+
+  let(:model) { 'model' }
+
+  describe '.with' do
+    let(:aggregator_class) do
+      Class.new(Magicka::Aggregator) do
+        def self.name
+          'Magicka::MyClass'
+        end
+      end
+    end
+
+    it do
+      expect { described_class.with(aggregator_class) }
+        .to add_method('magicka_my_class')
+        .to(object)
+    end
+  end
+
+  describe '#magicka_display' do
+    it do
+      object.magicka_display(model) do |display|
+        expect(display).to be_a(Magicka::Display)
+      end
+    end
+
+    it 'populates the model' do
+      object.magicka_display(model) do |display|
+        expect(display.model).to eq(model)
+      end
+    end
+
+    it 'populates the renderer' do
+      object.magicka_display(model) do |display|
+        expect(display.send(:renderer)).to eq(object)
+      end
+    end
+  end
+
+  describe '#magicka_form' do
+    it do
+      object.magicka_form(model) do |form|
+        expect(form).to be_a(Magicka::Form)
+      end
+    end
+
+    it 'populates the model' do
+      object.magicka_form(model) do |form|
+        expect(form.model).to eq(model)
+      end
+    end
+
+    it 'populates the renderer' do
+      object.magicka_form(model) do |form|
+        expect(form.send(:renderer)).to eq(object)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: magicka
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.6.0
 platform: ruby
 authors:
 - DarthJee
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-21 00:00:00.000000000 Z
+date: 2021-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.11.4
+        version: 1.12.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.11.4
+        version: 1.12.5
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -398,6 +398,7 @@ files:
 - docker-compose.yml
 - lib/magicka.rb
 - lib/magicka/aggregator.rb
+- lib/magicka/aggregator/class_methods.rb
 - lib/magicka/aggregator/method_builder.rb
 - lib/magicka/button.rb
 - lib/magicka/display.rb
@@ -407,6 +408,8 @@ files:
 - lib/magicka/form.rb
 - lib/magicka/form_element.rb
 - lib/magicka/helper.rb
+- lib/magicka/helper/class_methods.rb
+- lib/magicka/helper/method_builder.rb
 - lib/magicka/input.rb
 - lib/magicka/select.rb
 - lib/magicka/text.rb
@@ -482,6 +485,7 @@ files:
 - spec/lib/magicka/element_spec.rb
 - spec/lib/magicka/form_element_spec.rb
 - spec/lib/magicka/form_spec.rb
+- spec/lib/magicka/helper_spec.rb
 - spec/lib/magicka/input_spec.rb
 - spec/lib/magicka/select_spec.rb
 - spec/lib/magicka/text_spec.rb