binda 0.1.3 → 0.1.4

data/app/models/binda/component.rb

@@ -26,7 +26,7 @@ module Binda
 
 			aasm :column => 'publish_state' do
 					state :draft, initial: true
-					state :published    
+					state :published
 
 				event :publish do
 					transitions from: :draft, to: :published

data/app/models/binda/date.rb

@@ -1,9 +1,13 @@
 module Binda
+	# This class provides support for dates.
   class Date < ApplicationRecord
 
   	# Associations
   	belongs_to :fieldable, polymorphic: true
   	belongs_to :field_setting
 
+		validates :fieldable_id, presence: true
+		validates :fieldable_type, presence: true
+		
   end
 end

data/app/models/binda/deprecation.rb

@@ -0,0 +1,7 @@
+module Binda
+	class Deprecation < ActiveSupport::Deprecation
+		def initialize(deprecation_horizon = 'next major release', gem_name = 'Binda')
+			super
+		end
+	end
+end

data/app/models/binda/field_group.rb

@@ -9,8 +9,11 @@ module Binda
 		has_many :field_settings, dependent: :destroy
 
 		# Validations
-		validates :name, presence: true
-		validates :slug, uniqueness: true
+		validates :name, presence: {
+			message: I18n.t("binda.field_group.validation_message.name")
+		}
+		validate :slug_uniqueness
+		validates_associated :field_settings
 		accepts_nested_attributes_for :field_settings, allow_destroy: true, reject_if: :is_rejected
 
 		# Slug
@@ -43,11 +46,21 @@ module Binda
 			attributes['name'].blank? && attributes['field_type'].blank?
 		end
 
+		def slug_uniqueness
+			record_with_same_slug = self.class.where(slug: slug)
+			if record_with_same_slug.any? && !record_with_same_slug.ids.include?(id)
+				errors.add(:slug, I18n.t("binda.field_group.validation_message.slug", { arg1: slug }))
+				return false
+			else
+				return true
+			end
+		end
+
 		private 
 
 			def update_position
 				if self.position.nil?
-					self.update_attribute( 'position', self.structure.field_groups.length )
+					self.update_attribute('position', self.structure.field_groups.length)
 				end
 			end
 

data/app/models/binda/field_setting.rb

@@ -1,13 +1,21 @@
 module Binda
 	class FieldSetting < ApplicationRecord
+		cattr_accessor :field_settings_array
+		cattr_accessor :get_field_classes
+
+    # An array of all classes which represent fields associated to Binda::FieldSetting
+    # This definition must stay on the top of the file
+		def self.get_field_classes
+			%w( String Text Date Image Video Repeater Radio Selection Checkbox Relation )
+		end
+
+		# ASSOCIATIONS
+		# ------------
 
 		belongs_to :field_group
 		has_ancestry orphan_strategy: :destroy
 
-		# Is this reallly needed? Or can we just use accepted_structures? 
-		# has_and_belongs_to_many :structures
-
-		# Fields Associations
+		# FIELDS ASSOCIATIONS
 		# 
 		# If you add a new field remember to update:
 		#   - get_field_classes (see here below)
@@ -37,8 +45,15 @@ module Binda
 		has_many :selections,     dependent: :destroy
 		has_many :checkboxes,     dependent: :destroy
 		has_many :relations,      dependent: :destroy
+		has_many :assets,         dependent: :destroy
+		has_many :images,         dependent: :destroy
+		has_many :videos,         dependent: :destroy
+
+		# We don't want to run callbacks for choices!
+		# If you run a callback the last choice will throw a error
+		# @see `Binda::Choice` `before_destroy :check_last_choice`
+		has_many :choices,        dependent: :delete_all 
 
-		has_many :choices,        dependent: :destroy
 		has_one  :default_choice, -> (field_setting) { where(id: field_setting.default_choice_id) }, class_name: 'Binda::Choice'
 		
 		has_and_belongs_to_many :accepted_structures, class_name: 'Binda::Structure'
@@ -52,32 +67,71 @@ module Binda
 			attributes['label'].blank? || attributes['content'].blank?
 		end
 
-		cattr_accessor :field_settings_array
+
+
+		# CALLBACKS
+		# ---------
+
+		before_save do
+			check_allow_null_for_radio
+		end
+
+		after_save do
+			add_choice_if_allow_null_is_false
+		end
 
     after_create do 
-    	self.class.reset_field_settings_array 
-    	set_allow_null
+    	self.class.reset_field_settings_array
+    	convert_allow_null__nil_to_false
     	create_field_instances
     end
 
+    after_update do
+			if %w(radio selection checkbox).include?(self.field_type) && self.choices.empty?
+				check_allow_null_option
+			end
+    end
+
     after_destroy do 
     	self.class.reset_field_settings_array 
     end
 
-		def self.get_field_classes
-			%w( String Text Date Image Video Repeater Radio Selection Checkbox Relation )
-		end
 
-		# Validations
-		validates :name, presence: true
-		validates :field_type, inclusion: { in: [ *FieldSetting.get_field_classes.map{ |fc| fc.to_s.underscore } ], allow_nil: false, message: "Select field type among these: #{ FieldSetting.get_field_classes.join(", ") }" }
-		validates :field_group_id, presence: true
 
-		# Slug
+    # VALIDATIONS
+    # -----------
+    # @see http://guides.rubyonrails.org/active_record_validations.html#message
+
+		validates :name, presence: { 
+			message: I18n.t("binda.field_setting.validation_message.name") 
+		}
+		validates :field_type, inclusion: { 
+			in: [ *FieldSetting.get_field_classes.map{ |fc| fc.to_s.underscore } ], 
+			allow_nil: false,
+			message: -> (field_setting) { 
+				I18n.t(
+					"binda.field_setting.validation_message.field_type", 
+					{ arg1: field_setting.name, arg2: "#{FieldSetting.get_field_classes.join(", ")}" }
+				)
+			}
+		}
+		validates :field_group_id, presence: {
+			message: -> (field_setting, data) {
+				I18n.t(
+					"binda.field_setting.validation_messag e.field_group_id", 
+					{ arg1: field_setting.name, arg2: data[:value] }
+				)
+			}
+		}
+		validate :slug_uniqueness
+
+
+    # FRIENDLY ID
+    # -----------
+
 		extend FriendlyId
 		friendly_id :default_slug, use: [:slugged, :finders]
 
-
 		# Friendly id preference on slug generation
 		#
 		# Method inherited from friendly id 
@@ -98,28 +152,48 @@ module Binda
 				slug << '-' 
 				slug << self.parent.name 
 			end
-			
-			possible_names = [ 
+			return [ 
 				"#{ slug }--#{ self.name }",
 				"#{ slug }--#{ self.name }-1",
 				"#{ slug }--#{ self.name }-2",
 				"#{ slug }--#{ self.name }-3"
 			]
+		end
 
-			return possible_names
+		# Check slug uniqueness
+		def slug_uniqueness
+			record_with_same_slug = self.class.where(slug: slug)
+			if record_with_same_slug.any? && !record_with_same_slug.ids.include?(id)
+				errors.add(:slug, I18n.t("binda.field_setting.validation_message.slug", { arg1: slug }))
+				return false
+			else
+				return true 
+			end
+		end
+
+		# It makes sure radio buttons have allow_null set to false.
+		def check_allow_null_for_radio
+			if field_type == 'radio' && allow_null?
+				self.allow_null = false
+				warn "WARNING: it's not possible that a field setting with type `radio` has allow_null=true."
+			end
 		end
 
+
+		# MISCELLANEOUS
+		# -------------
+
 		# Retrieve the ID if a slug is provided and update the field_settings_array 
 		#   in order to avoid calling the database (or the cached response) every time.
 		#   This should speed up requests and make Rails logs are cleaner.
 		# 
 		# @return [integer] The ID of the field setting
-		def self.get_id( field_slug )
+		def self.get_id(field_slug)
 			# Get field setting id from slug, without multiple calls to database 
 			# (the query runs once and caches the result, then any further call uses the cached result)
 			@@field_settings_array = self.pluck(:slug, :id) if @@field_settings_array.nil?
 			selected_field_setting = @@field_settings_array.select{ |fs| fs[0] == field_slug }[0]
-			raise ArgumentError, "There isn't any field setting with the current slug.", caller if selected_field_setting.nil?
+			raise ArgumentError, "There isn't any field setting with the current slug \"#{field_slug}\".", caller if selected_field_setting.nil?
 			id = selected_field_setting[1]
 			return id
 		end
@@ -136,11 +210,33 @@ module Binda
 		end
 
 		# Make sure that allow_null is set to false instead of nil.
-		#   This isn't done with a database constraint in order to gain flexibility
-		def set_allow_null
+		#   (This isn't done with a database constraint in order to gain flexibility)
+		# 
+		# REVIEW: not sure what flexibility is needed. Maybe should be done differently
+		def convert_allow_null__nil_to_false
 			self.allow_null = false if self.allow_null.nil?
 		end
 
+		# Get structure on which the current field setting is attached. It should be one, but in order to 
+		#   be able to add other methods to the query this methods returns a `ActiveRecord::Relation` object, not
+		#   a `ActiveRecord`
+		# 
+		# @return [ActiveRecord::Relation] An array of `Binda::Structure` instances
+		def structures
+			Structure.left_outer_joins(
+				field_groups: [:field_settings]
+			).where(
+				binda_field_settings: { id: self.id }
+			)
+		end
+
+		# Get the structure of the field group to which the field setting belongs.
+		# 
+		# @return [ActiveRecord] The `Binda::Structure` instance
+		def structure
+			self.structures.first
+		end
+
 		# Generates a default field instances for each existing component or board
 		#   which is associated to that field setting. This avoid having issues 
 		#   with Binda::FieldSetting.get_id method which would throw an ambiguous error 
@@ -151,31 +247,62 @@ module Binda
 		#   a field instance is always present no matter if the component has been created
 		#   before the field setting or the other way around.
 		def create_field_instances
-			structure = self.field_group.structure
-			field_class = self.field_type.pluralize
-			field_setting_id = self.id
-			case 
-				when structure.components.any?
-					structure.components.each do |component|
-						create_field_instances_for_component( component, field_class, field_setting_id )
-					end
-				when structure.board.present?
-					create_field_instances_for_board( structure.board, field_class, field_setting_id )
+			# Get the structure
+			structure = self.structures.includes(:board, components: [:repeaters]).first
+			field_class = "Binda::#{self.field_type.classify}"
+			structure.components.each do |component|
+				create_field_instances_for_instance(component, field_class, self.id)
 			end
+			create_field_instances_for_instance(structure.board, field_class, self.id) if structure.board.present?
 		end
 
-		# Helper for create_field_instances method
-		def create_field_instances_for_component( component, field_class, field_setting_id )
-			unless component.send(field_class).where(field_setting_id: field_setting_id).any?
-				component.send(field_class).create!(field_setting_id: field_setting_id)
+		def create_field_instance_for(instance)
+			if self.is_root?
+				create_field_instances_for_instance(instance, field_class, self.id)
+			else
+				instance.repeaters.select{|r| r.field_setting_id == self.parent_id}.each do |repeater|
+					create_field_instances_for_instance(repeater, field_class, self.id)
+				end
 			end
 		end
 
 		# Helper for create_field_instances method
-		def create_field_instances_for_board ( board, field_class, field_setting_id )
-			unless board.send(field_class).where(field_setting_id: field_setting_id).any?
-				board.send(field_class).create!(field_setting_id: field_setting_id)
+		def create_field_instances_for_instance(instance, field_class, field_setting_id)
+			field_class.constantize.find_or_create_by!(
+				field_setting_id: field_setting_id,
+				fieldable_id: instance.id,
+				fieldable_type: instance.class.name
+			)
+		end
+
+		# Check `allow_null` option
+		# 
+		# Creating a selection with `allow_null` set to `false` will automatically generate a critical error.
+		#   This is due to the fact that 1) there is no choice to select, but 2) the selection field must have at least one.
+		#   The error can be easily removed by assigning a choice to the current field setting.
+		# 
+		# This method is preferred to a validation because it allows to remove all choices before adding new ones.
+		#   
+		def check_allow_null_option
+    	return if self.allow_null?
+  		Selection.check_all_selections_depending_on(self)
+		end
+
+		# Validation method that check if the current `Binda::Selection` instance has at least a choice before 
+		#   updating allow null to false
+		def add_choice_if_allow_null_is_false
+			if %(selection radio checkbox).include?(self.field_type) && 
+				!self.allow_null?
+				if self.choices.empty?
+					# Add a choice if there is none, it will be automatically assign as default choice
+					self.choices.create!(label: I18n.t("binda.choice.default_label"), value: I18n.t("binda.choice.default_value"))
+				elsif self.default_choice_id.nil?
+					# Assign a choice as default one if there is any
+					# REVIEW there is some deprecation going on, but I'm not sure i directly involves the `update` method
+					self.update!(default_choice_id: self.choices.first.id)
+				end
 			end
 		end
+
 	end
 end

data/app/models/binda/image.rb

@@ -1,4 +1,5 @@
 module Binda
+	# This class provides support for uploading images.
   class Image < Asset
 
     mount_uploader :image, ImageUploader

data/app/models/binda/radio.rb

@@ -1,4 +1,6 @@
 module Binda
+	# This class provides support for radio buttons and depends on `Binda::Selection`.
+	# You can find more info at the _selection_ [documentation](http://www.rubydoc.info/gems/binda/Binda/Selection)
 	class Radio < Selection
 
 	end

data/app/models/binda/relation.rb

@@ -21,6 +21,9 @@ module Binda
     belongs_to :fieldable, polymorphic: true
     belongs_to :field_setting
 
+    validates :fieldable_id, presence: true
+    validates :fieldable_type, presence: true
+
     # Relations are the connection between a Owner to its Dependents
     # The Active Relation connects a Relation to a Dependent (which is can be a Component or a Board)
     # The Passive Relation connects a Relation to a Owner (which is can be a Component or a Board)

data/app/models/binda/repeater.rb

@@ -7,6 +7,9 @@ module Binda
   	belongs_to :fieldable, polymorphic: true
     belongs_to :field_setting
 
+    validates :fieldable_id, presence: true
+    validates :fieldable_type, presence: true
+
     # The following direct association is used to securely delete associated fields
     # Infact via `fieldable` the associated fields might not be deleted 
     # as the fieldable_id is related to the `component` rather than the `field_setting`

data/app/models/binda/selection.rb

@@ -1,8 +1,245 @@
 module Binda
+	# `Binda::Selection` class provides support for **selection**, **radio** and **checkbox** fields.
+	# 
+	# More specifically `Binda::Selection` is used for **selection** fields, whereas **radio** and 
+	#   **checkbox** fields depend on `Binda::Radio` and `Binda::Checkbox` which are subclasses of `Binda::Selection`.
+	#   
+	# The architecture behind this class is pretty complex and deserves some attention. 
+	#   Here the rules that defines the class behaviour:
+	#   
+	# 1. Every selection can have multiple **choices** (see `Binda::Choice`) or none.
+	# 
+	# 2. Every **selection** depends on a **field setting** (see `Binda::FieldSetting` 
+	#   [documentation](http://www.rubydoc.info/gems/binda/Binda/FieldSetting)) which specify its behaviour.
+	# 
+	# 3. Every time you create a **field setting** a fallback ensure a **selection** exists for every 
+	#   **component** or **board** to which this **field setting** belongs. This ensure calling `get_selection_choices`
+	#   method doesn't throw a error.
+	#   ```ruby
+	#   # Create a field setting for a component
+	#   component = Binda::Component.first
+	#   field_setting = component.structure.field_groups.first.field_settings.create(
+	#       name: 'my selection',
+	#       field_type: 'selection'
+	#   )
+	#   # Reload component so the Active Record object is updated
+	#   component.reload
+	#   # We know for sure a selection exists
+	#   component.selections.any?
+	#   # => true
+	#   # We might not find any choice though
+	#   component.get_selection_choices(field_setting.slug)
+	#   # => []
+	#   ```
+	#   
+	# 4. When a **field setting** is created there is no **choice** available yet. Only if a **setting** requires 
+	#   at least a **choice**, a new **choice** is created. In that case the **choice** is also automatically set as 
+	#   the **default choice** for the **field setting** and applied to all **selections** that didn't have any **choice**. 
+	#   Again, this behaviour exists just for **field settings** that requires at least a **choice** and has just 
+	#   been created. Changing the **field setting** **default choice** persisted on the database with another one 
+	#   won't change the **selected choice** of any **selections** created before: they will keep the previous 
+	#   **default choice**. For more info look at `Binda::Choice` 
+	#   [documentation](http://www.rubydoc.info/gems/binda/Binda/Choice)
+	#   ```ruby
+	#   # Create a field setting for a component (note: allow_null is set to false)
+	#   component = Binda::Component.first
+	#   field_setting = component.structure.field_groups.first.field_settings.create(
+	#       name: 'my selection',
+	#       field_type: 'selection', 
+	#       allow_null: false # IMPORTANT: this means field setting requires at least a choice
+	#   )
+	#   # If field setting doesn't allow null, it means we always expect a choice to be selected
+	#   component.get_selection_choices(field_setting.slug)
+	#   # A default choice is returned
+	#   # => [{ label: 'Temporary choice', value: 'temporary-choice' }]
+	#   component.get_selection_choices(field_setting.slug)
+	#   # => [{ label: 'Temporary choice', value: 'temporary-choice' }]
+	#   # When we remove the initial choice we fallback to default
+	#   field_setting.choices.first.delete
+	#   # => error!
+	#   field_setting.choices.create(
+	#       label: 'second', 
+	#       value: 'second'
+	#   )
+	#   field_setting.choices.first.destroy
+	#   component.get_selection_choices(field_setting.slug)
+	#   # => [{ label: 'second', value: 'second' }]
+	#   ```
+	# 
+	# 5. Every time a **field setting** is updated a fallback ensures all **selections** relying on it are updated as well.
+	#   ```ruby
+	#   # Create a field setting for a component
+	#   component = Binda::Component.first
+	#   field_setting = component.structure.field_groups.first.field_settings.create(
+	#       name: 'my selection',
+	#       field_type: 'selection', 
+	#       allow_null: false
+	#   )
+	#   field_setting.choices.create([
+	#       {
+	#           label: 'first', 
+	#           value: 'first'
+	#       },
+	#       {
+	#           label: 'second', 
+	#           value: 'second'
+	#       },
+	#   ])
+	#   # field_setting automatically assigns **first choice** as default and replace the **temporary default choice**.
+	#   # Now reload component to update it with the instances just created
+	#   component.reload
+	#   component.selections.first.choices << field_setting.choices.first
+	#   component.selections.first.choices << field_setting.choices.last
+	#   component.get_selection_choices(field_setting.slug)
+	#   # => [{ label: 'first', value: 'first' }, { label: 'second', value: 'second' }]
+	#   # Remove the initial choice
+	#   field_setting.choices.first.delete
+	#   # Get selection choices again. Now you should get a different result
+	#   component.reload.get_selection_choices(field_setting.slug)
+	#   # => [{ label: 'second', value: 'second' }]
+	#   ```
+	# 
+	# 6. (This is the trickiest) 
+	#   Assuming that 
+	#   1) **field setting** requires at least a **choice**, 
+	#   2) there is only one **choice** available, 
+	#   3) some **selections** are associated to that **choice**. 
+	#   If the user replace that **choice** with another one, all **selections** fields will be associated to 
+	#   the new one.
+	#   ```ruby
+	#   # Create a field setting for a component
+	#   component = Binda::Component.first
+	#   field_setting = component.structure.field_groups.first.field_settings.create(
+	#       name: 'my selection',
+	#       field_type: 'selection', 
+	#       allow_null: false
+	#   )
+	#   # Trying to delete the default temporary choice, which is the only one, won't work
+	#   field_setting.choices.first.destroy
+	#   # => false
+	#   # You need to create another choice first
+	#   field_setting.choices.create(
+	#       label: 'Second', 
+	#       value: 'second'
+	#   )
+	#   field_setting.choices.first.destroy
+	#   component.reload.get_selection_choices(field_setting.slug)
+	#   # => [{ label: 'second', value: 'second' }]
+	#   # BE AWARE THAT:
+	#   field_setting.choices.delete_all
+	#   # => deletes everything skipping callbacks and will cause inconsistency throughout the database
+	#   ```
+	# 
 	class Selection < ApplicationRecord
 
 		has_and_belongs_to_many :choices
 		belongs_to :field_setting
 
+		validate :has_choices
+		validates :fieldable_id, presence: true
+
+		after_save do
+			if !self.field_setting.allow_null && 
+				!self.field_setting.default_choice_id.nil? &&
+				!self.choices.any?
+				assign_default_choice
+			end
+		end
+
+		# Fix selections which have no choice even though the field setting requires at least one
+		#
+		# This method gets all `Binda::Selection` records that depend on a field setting which 
+		#   requires that the selection has at least one choice and which haven't any choice selected. 
+		#   This method is used on the user interface and a rake task.
+		# 
+		# Raise an error if the related field setting doesn't have any choice or the default choice isn't selected
+		def self.add_default_choice_to_all_selections_with_no_choices(field_setting = nil)
+			# Get all Binda::Selection records that:
+			# - depend on a field setting which requires to have at least a choice
+			# - have no choice selected
+
+			selections = Selection.get_selections_which_must_have_a_choice_but_have_none(field_setting)
+			selections.each do |selection|
+				unless selection.field_setting.default_choice_id.nil?
+					selection.assign_default_choice
+				else
+					raise "Binda::Selection with id=\"#{selection.id}\" cannot be fixed because its field setting doesn't have any available choice. Please add at least a choice to field setting \"#{selection.field_setting.slug}\"."
+				end
+			end
+		end
+
+		# Assign default choice to a selection
+		def assign_default_choice
+			self.choices << self.field_setting.default_choice
+		end
+
+		# Check all Binda::Selection records which are required to have a choice.
+		# 
+		# The purpose of this method is to check, not to update. You don't won't to decide which choice 
+		#   must be selected if the selection is required to have one. You just want the user to know that
+		#   it's not possible to leave it without any.
+		# 
+		# @param field_setting [ActiveRecord Object]
+		def self.check_all_selections_depending_on(field_setting)
+			# Make sure Active Record object of field setting is updated
+			field_setting.reload
+
+			# Don't bother if field setting allow having no choice or if default_choice isn't set
+			return if field_setting.allow_null? || field_setting.default_choice_id.nil?
+
+			# Get all selection related to this field setting which have an issue with choices
+			selections = Selection.get_selections_which_must_have_a_choice_but_have_none(field_setting)
+
+			# Warn the user that there's a problem
+			selections.each do |selection|
+				selection.choices << field_setting.default_choice
+				unless selection.save
+					raise "It hasn't been possible to assign Binda::Choice with id=\"#{field_setting.default_choice_id}\" to Binda::Selection with id=\"#{self.id}\"."
+				end
+			end
+		end
+
+		# Get selections which must have a choice, but have none
+		# 
+		# Get all Binda::Selection records that:
+		# - depend on a field setting which requires to have at least a choice
+		# - have no choice selected
+		# 
+		# @param field_setting_slug [string] Add the slug of a field setting to filter the query
+		# 
+		# @return [array] An array of Binda::Selection objects
+		def self.get_selections_which_must_have_a_choice_but_have_none(field_setting = nil)
+			if field_setting.nil?
+				Selection.includes(:choices, :field_setting)
+					.where(
+						binda_choices_selections: { selection_id: nil },
+						binda_field_settings: { allow_null: false }
+					)
+			else
+				field_setting_id = FieldSetting.get_id(field_setting.slug)
+				Selection.includes(:choices, :field_setting)
+					.where(
+						binda_choices_selections: { selection_id: nil }, 
+						binda_selections: { field_setting_id: field_setting_id },
+						binda_field_settings: { allow_null: false }
+					)
+			end
+		end
+
+		# Get selection
+		def has_choices
+			field_setting = self.field_setting
+			case 
+			when self.new_record?
+				return true
+			when !field_setting.allow_null? && field_setting.choices.any? && self.choices.empty?
+				errors.add(:base, I18n.t("binda.selection.validation_message.choices", { arg1: self.id, arg2: field_setting.slug })
+				)
+				return false
+			else
+				return true
+			end
+		end
+
 	end
 end