cck_forms 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b40277032af600f826f2a98dbf141a6f5c2612c
-  data.tar.gz: 7f1283c1d9b3cc1e5fcdde697c5bcb345d96fd1a
+  metadata.gz: 879b5ac5dd9add74c06463c6ea0ea8d9ac919690
+  data.tar.gz: 1deecc0d0cb355f2b1ab22881ffea197ff920926
 SHA512:
-  metadata.gz: 46bb42b6d45311327227f56ddce705a6626df1796844b88533c6383d38b497f37d8547ca51f482f84c2dcbef74a6bb3ad8b2f37d5e41d07877a901f55e31534a
-  data.tar.gz: cd1050682502bfd5a6968e8cdc6b60342610604795d23c9248394a1fec1156725428e80a2c69177144cb81fea24acbb6997d1052687f4cc054faaa6f9e16fde9
+  metadata.gz: e493ead26cdd54b827078bfdd6ac8c63446dfb1e9e80af6cf42b0f3607d2944101650764d130fd3c1a8c1ff8290051c0c841f015676fe4fc5eefe4d86888cddf
+  data.tar.gz: 28a00be50aaecd6165db9dbb3158a1971de0b74d30fe18c97b7fed33ff9e95cb7f527ae9e7bbdad8bd3808f4fc6d25f947fe9c02e83ca846c171e46c99ccf202

data/README.md

@@ -1 +1,254 @@
-TODO
+CCK Forms
+=========
+ 
+CCK Forms is a companion to the yet-to-be-published CCK gem. (CCK stands for Content Construction Kit — a name borrowed
+from PHP Drupal CMS.)
+
+Whilst the CCK gem provides ability to store category-related custom fields in an ActiveModel, this gem defines possible
+field types for that matter (string, enum, image album etc.)
+
+As CCK is aimed to simplify storing & editing model fields (especially in admin panels), these custom field types define
+common (and complex) notions like work hours, sets of images, WYSIWYG-capable fields and so on. "Define" here means
+these field types can be stored in CCK-capable models and they all have HTML form templates. The latter implies possible
+standalone usage, for example, if you just need a field of type Image inside your model, you can use CCK Forms without
+CCK and still have nice looking and convenient editor form template.
+
+The UI is written in Bootstrap 3 and can not be easily changed, sorry folks.
+
+
+Criticism
+---------
+
+Generally speaking, this gem combines two aspects: CCK-related storage things and UI editor forms. The latter is very
+project & design dependent and should not be fixed in the gem (especially in the way it is now, with HTML constructed
+in class methods, heavily relying on Bootstrap). Moreover, it may be a good idea to completely decouple UI into separate
+gem/module using, say, Simpleforms to do the frontend job.
+
+Then, this gem will only define pure classes to be used either with CCK or standalone as proper "types", like String
+or MapPoint or anything else.
+
+
+Installation, dependencies
+--------------------------
+
+***Important***: CCK requires a MongoDB database as a mean to store data, so your models must be Mongoid documents.
+
+Add CCK Forms and its dependencies to your gemfile:
+
+``` ruby
+# neofiles-related
+gem 'neofiles'
+gem 'ruby-imagespec', git: 'git://github.com/dim/ruby-imagespec.git'
+gem 'mini_magick', '3.7.0'
+
+gem 'cck_forms'
+```
+
+This gem requires [Neofiles](https://github.com/ilya-konanykhin/neofiles) for File, Image and Album types. Please read
+its installation instructions, there are some gotchas.
+
+Next, include CSS & JS files where needed (say, application.js or admin.js)...
+
+``` javascript
+#= require jquery # neofiles requires jquery
+#= require neofiles
+#= require cck_forms
+```
+
+... and application.css/admin.css or whatever place you need it in:
+
+``` css
+ *= require neofiles
+```
+
+Don't forget to set up Neofiles routing!
+
+
+Usage with CCK
+--------------
+
+Basic usage only, more to come when CCK gem will finally be published.
+
+```ruby
+# in model:
+class Content
+  include Mongoid::Document
+  include Cck::Cckable
+  
+  cck_config do |c|
+    c.category 'news' do |cc|
+      cc.string 'title', 'News title'
+      cc.enum   'region', valid_values: {world: 'World news', local: 'Local news'}
+      cc.image  'announce_pic', 'Announce image', hint: '100x100 only'
+      cc.text   'body', 'News article body'
+      cc.map    'map_point', 'Where did it happen?'
+      
+      c.require_params %w{title body}
+    end
+    
+    c.category 'page' do |cc|
+      ...
+    end
+  end
+  
+  field :category_id, type: String
+end
+
+# in controller:
+def edit
+  @content = Content.new category_id: params[:category_id]
+end
+
+# in view:
+= form_for @content do |ff|
+ = cck_fields_for :cck_params
+ 
+# elsewhere:
+content = Content.find(...)
+content.cck_params[:title].to_s
+content.cck_params[:map_point].value[:latitude]
+content.cck_params.to_h.each_pair { |k, v| puts "#{k}: #{v}" } # outputs every CCK field with its ID
+```
+
+
+Standalone usage
+----------------
+
+First, create a model and add as many CCK fields as you need:
+
+```ruby
+class User
+  include Mongoid::Document
+  
+  field :avatar,  type: CckForms::ParameterTypeClass::Image
+  field :cv,      type: CckForms::ParameterTypeClass::File
+  field :phones,  type: CckForms::ParameterTypeClass::Phones
+  
+  validates do |doc|
+    if doc.avatar.try(:value) && doc.avatar.value.width > 1000
+      doc.errors.add :avatar, 'must be no more than 1000 px wide'
+    end
+    
+    if doc.phones.try(:value) && doc.phones.value.count > 2
+      doc.errors.add :phones, 'must have at most 2 phone numbers'
+    end
+  end
+end
+```
+
+Then in a view form use helper to output UI:
+
+```slim
+= form_for @user, html: {class: 'form-horizontal'} do |f|
+  .form-group
+    label.control-label.col-sm-2 Avatar
+    .col-sm-9= f.standalone_cck_field :avatar
+ 
+  .form-group
+     label.control-label.col-sm-2 CV
+     .col-sm-9= f.standalone_cck_field :cv, with_desc: true
+
+  .form-group
+    label.control-label.col-sm-2 Phone numbers
+    .col-sm-9= f.standalone_cck_field :phones
+end
+```
+
+Use model fields as usual with one exception: to get a field value you need to unwrap its first with call to `value`
+(as it is a wrapper class instance). Assign values directly though.
+
+```ruby
+user = User.first
+puts "User avatar file: #{neofiles_image_path user.avatar.value} (#{user.avatar.value.length} bytes)"
+puts "User phone#{user.phones.try(:value).try(:count).to_i == 0 ? '' : 's'}: #{user.phones.to_s}"
+
+user.avatar = Neofiles::Image.find(...)
+user.phones = ['+7 111 222 33 44', '1231231231', {prefix: '+906', code: '1234', number: '223344'}]
+user.save! # should raise exception indicating phones validation failure
+```
+
+Common methods:
+* `value`: returns the real field value. Each field type has its own value, say Phones returns an array of phone numbers
+   and Map returns a hash with keys `:latitude, :longitude, :zoom`
+* `to_s`: string representation
+* `to_html`: HTML representation
+* `to_diff_value`: representation in form was/became to show history of changes
+* `search`: returns a Mongoid Criteria filled with search query params specific to this particular field type
+* `build_form`: builds an HTML editor form
+
+
+Available field types
+---------------------
+
+***Album***: sortable collection of images.
+
+***Boolean***: checkbox.
+
+***Checkboxes***: several checkboxes. Requires the `valid_values` option.
+
+***Date, DateTime, Time***: date/date&time/time select.
+
+***DateRange***: two sets of selects "date from/till".
+
+***Enum***: select or set of radio buttons. Requires the `valid_values` option.
+
+***File, Image***: single file or image.
+
+***Integer, Float***: numeric input.
+
+***IntegerRange***: two inputs for "number from/till".
+
+***Map***: map point. Two map providers available: Google and Yandex. Google requires an API key.
+
+***Phones***: array of phone numbers.
+
+***String***: text input.
+
+***StringCollection***: set of strings. Represented by a textarea, one line — one string.
+
+***Text***: textarea.
+
+***WorkHours***: complex input to construct work schedule on a weekly basis.
+
+
+Configuration
+-------------
+
+CCK Forms offers the following config options which can be set in `config/application.rb` or `config/environments/*.rb`:
+
+```ruby
+# load all available type classes on application start
+config.cck_forms.load_type_classes = true
+
+# extend default form builder to add `standalone_cck_field` method
+config.cck_forms.extend_form_builder = true
+
+# how many phone numbers will the edit form contain by default for each field
+config.cck_forms.phones.min_phones_in_form = 3
+
+# which area codes are considered as mobile carrier codes (mobile and landline numbers have different HTML forms)
+# the codes listed below are Kazakhstan mobile operators as of year 2016
+config.cck_forms.phones.mobile_codes = %w{ 777 705 771   701 702 775 778   700   707 }
+
+# phone number prefix
+# +7 is Russia/Kazakhstan
+config.cck_forms.phones.prefix = '+7'
+
+# the glue for concatenating phone number parts: 111[glue]22[glue]33
+config.cck_forms.phones.number_parts_glue = '-'
+```
+
+
+Roadmap, TODOs
+--------------
+
+- Add new field type: Tags (a collection of — possibly pre-set — strings)
+- Extract HTML templates into separate gem/module
+- Extract map providers or at lease make them configurable
+- Custom phone format on input/ouput (`#build_form, #to_html`)
+
+
+License
+-------
+
+Released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/cck_forms/date_time.rb

@@ -1,7 +1,11 @@
+# Utility module grouping all date & time related methods
+#
 module CckForms::DateTime
   extend ActiveSupport::Concern
 
   module DateTimeParser
+    # Create Date/DateTime object from its MongoDB/HTML representation: either a hash with keys :year, :month and so on
+    # or a Hash with keys (5i), (1i) etc.
     def date_object_from_what_stored_in_database(value)
       parsed_value = nil
       if value.is_a? Hash

data/lib/cck_forms/engine.rb

@@ -10,8 +10,8 @@ module CckForms
     config.cck_forms = ActiveSupport::OrderedOptions.new
 
     # general
-    config.cck_forms.load_type_classes          = true
-    config.cck_forms.extend_form_builder        = true
+    config.cck_forms.load_type_classes          = true # if true, require all default type classes
+    config.cck_forms.extend_form_builder        = true # if true, extend FormBuilder via form_builder_extensions.rb
 
     # phones
     config.cck_forms.phones = ActiveSupport::OrderedOptions.new

data/lib/cck_forms/form_builder_extensions.rb

@@ -1,4 +1,4 @@
-# Примесь для расширения ActionView::Helpers::FormBuilder, чтобы работать с нашими полями:
+# Extends ActionView::Helpers::FormBuilder to add CCK Forms related methods:
 #
 #   class CckEnabled
 #     field :logo, type: CckForms::ParameterTypeClass::Image
@@ -9,6 +9,7 @@
 #
 module CckForms::FormBuilderExtensions
   ActionView::Helpers::FormBuilder.class_eval do
+    # Returns HTML for a standalone CCK field field_name
     def standalone_cck_field(field_name, options = {})
       fields_for(field_name) do |ff|
         @template.raw object.send(field_name).build_form ff, options

data/lib/cck_forms/neofiles_denormalize.rb

@@ -0,0 +1,71 @@
+# Utility class to handle denormalization of Neofile::File object fields to be stored in a host object.
+#
+# This module is included in Album and Image parameter type classes.
+#
+module CckForms::NeofilesDenormalize
+  extend ActiveSupport::Concern
+
+  # Fields that should not be stored in a host object since they are mutable
+  NEOFILES_LAZY_ATTRS = %i{ no_wm description is_deleted }
+
+  module ClassMethods
+    # Returns all fields of Neofiles::File obj to be denormalized
+    def neofiles_attrs(obj)
+      obj.attributes.except *NEOFILES_LAZY_ATTRS
+    end
+
+    # Returns all fields of Neofiles::File to be denormalized or the object ID if the object itself can not be found
+    def neofiles_attrs_or_id(obj_or_id, klass = ::Neofiles::File)
+      if obj_or_id.present?
+        obj, id = if obj_or_id.is_a? klass
+                    [obj_or_id, nil]
+                  elsif obj_or_id.is_a?(::String) || obj_or_id.is_a?(::BSON::ObjectId)
+                    [::Neofiles::File.where(id: obj_or_id).first, obj_or_id.to_s]
+                  end
+
+        obj.try { |x| neofiles_attrs(x) } || id
+      end
+    end
+
+    # Constructs a Mongoid::Document of class klass with attrs as if it was a usual document loaded from MongoDB
+    def neofiles_mock(attrs, klass)
+      Mongoid::Factory.from_db(klass, attrs).tap do |obj|
+        neofiles_lazy_loadable obj
+      end
+    end
+
+    # If attrs_or_id is a Hash, constructs a mock from it. Otherwise, load an object by its ID
+    def neofiles_mock_or_load(attrs_or_id, klass = ::Neofiles::File)
+      if attrs_or_id.present?
+        case attrs_or_id
+          when ::String then klass.where(id: attrs_or_id).first
+          when ::BSON::ObjectId then klass.where(id: attrs_or_id).first
+          when ::Hash then neofiles_mock(attrs_or_id.with_indifferent_access, klass)
+        end
+      end
+    end
+
+    # Makes obj lazy load fields NEOFILES_LAZY_ATTRS. That is, when these fields are accessed vie getters or
+    # read_attribute, make a request to MongoDB to fetch fresh data (all at once)
+    def neofiles_lazy_loadable(obj)
+      def obj.__lazy_load
+        return if @__lazy_loaded
+        @__lazy_loaded = true
+        from_db = self.class.find(id)
+        attributes.merge! from_db.attributes.slice(*NEOFILES_LAZY_ATTRS)
+      end
+
+      def obj.read_attribute(field)
+        __lazy_load if field.in? NEOFILES_LAZY_ATTRS
+        super(field)
+      end
+
+      NEOFILES_LAZY_ATTRS.each do |field|
+        obj.define_singleton_method field do
+          __lazy_load
+          super()
+        end
+      end
+    end
+  end
+end

data/lib/cck_forms/parameter_type_class/album.rb

@@ -1,12 +1,14 @@
+# Represents an ordered collection of photos (Image types).
+#
 class CckForms::ParameterTypeClass::Album
   include CckForms::ParameterTypeClass::Base
+  include CckForms::NeofilesDenormalize
 
   def self.name
     'Альбом'
   end
 
-  # Преобразует данные для Монго.
-  # Приводит переданный массив или хэш объектов Neofiles::Image или их идентификаторов в массив.
+  # Converts input array of Neofiles::Image or IDs to array of hashes (denormalized image data) or IDs
   def mongoize
     the_value = value.is_a?(Hash) ? value['value'] : value
 
@@ -14,28 +16,27 @@ class CckForms::ParameterTypeClass::Album
     if the_value.respond_to? :each
       the_value.each do |image|
         image = image[1] if the_value.respond_to? :each_value
-        result.push(image.is_a?(::Neofiles::Image) ? image.id : image.to_s) if image.present?
+        result.push self.class.neofiles_attrs_or_id(image, ::Neofiles::Image)
       end
     end
 
-    result
+    result.compact
   end
 
-  # Преобразуем данные из Монго.
-  # Приводим в массив (по идее, массив идентификаторов Neofiles::Image, хотя может быть что угодно).
+  # Converts input array of attr hashes or IDs to array if Neofiles::Image (possibly lazy loadable)
   def self.demongoize_value(value, parameter_type_class=nil)
     if value.respond_to? :each
-      value
+      value = value.values if value.respond_to? :values
+      value.map { |x| neofiles_mock_or_load(x) }.compact
     else
       []
     end
   end
 
-  # Строит форму для обновления файлов альбома.
+  # options:
   #
-  # Ключи options:
-  #
-  #   value - текущее значение (идентификатор или объект Neofiles::Album)
+  #   value     - current value (ID or Neofiles::Album)
+  #   with_desc - if true, show the description edit richtext (default false)
   def build_form(form_builder, options)
     set_value_in_hash options
 
@@ -49,6 +50,7 @@ class CckForms::ParameterTypeClass::Album
     file_forms = []
 
     the_value.each do |image_id|
+      image_id = image_id.is_a?(::Neofiles::File) ? image_id.id : image_id
       file_forms << CckForms::ParameterTypeClass::Image.create_load_form( helper: self,
                                                                           file: image_id,
                                                                           input_name: input_name_prefix,
@@ -84,10 +86,12 @@ class CckForms::ParameterTypeClass::Album
 HTML
   end
 
+  # Returns empty string
   def to_s(options = nil)
     ''
   end
 
+  # Returns a collection of 64x64 IMGs
   def to_diff_value(options = {})
     view_context = options[:view_context]
     images_html_list = []