nocms-blocks 1.0.0

data/README.md

@@ -0,0 +1,233 @@
+# NoCMS Blocks
+
+## What's this?
+
+This is a Rails engine with a basic functionality of customizable blocks of content attachable to objects. It's not attached to any particular CMS so you can use it freely within your Rails application without too much dependencies.
+
+## How do I install it?
+
+Right now there's no proper gem, although we have a couple of projects making extensive use of it.
+
+To install it just put the repo in your Gemfile:
+
+```ruby
+gem "nocms-blocks", git: 'git@github.com:simplelogica/nocms-blocks.git'
+```
+
+And then import all the migrations:
+
+```
+rake no_cms_blocks:install:migrations
+```
+
+And run the initializer:
+
+```
+rails g nocms:blocks
+```
+
+## How does it works?
+
+Blocks are thought to be independent and customizable modules of content that can be created, edited or removed on their own, without dependency of any other module or class.
+
+### Block layouts
+
+In NoCMS Blocks, block layouts define two main things:
+
+1. What kind of information a block contains and other settings (i.e. cache settings).
+2. How this information is displayed on a view.
+
+Block settings are configured in the file `config/initializers/nocms/blocks.rb`. In that file we declare all the available layouts for a block.
+
+The following code
+
+```ruby
+NoCms::Blocks.configure do |config|
+
+  config.block_layouts = {
+    'default' => {
+      template: 'default',
+      fields: {
+        title: :string,
+        body: :text
+      }
+    },
+    'title-3_columns' => {
+      template: 'title_3_columns',
+      fields: {
+        title: :string,
+        column_1: :text,
+        column_2: :text,
+        column_3: :text
+      },
+    },
+    'logo-caption' => {
+      template: 'logo_caption',
+      fields: {
+        caption: :string,
+        logo: TestImage
+      }
+    }
+  }
+
+end
+```
+
+declares 3 layouts ('default', 'title-3_columns' and 'logo-caption'). Each layout has a template and some declared fields. These fields will be available in the ruby object for that block. As an example, if `@block` is an instance of the NoCms::Blocks::Block model which layout attribute is set to 'default' you will be able to do `@block.title`
+
+```ruby
+block = NoCms::Blocks::Block.new
+block.layout = 'default'
+
+block.title = 'a title'
+block.title # => 'a title'
+
+block.column_1 = 'a column' # => NoMethodError
+block.column_1 # => NoMethodError
+
+
+block.layout = 'title-3_columns'
+
+block.title # => 'a title'
+block.column_1 = 'a column'
+block.column_1 # => 'a column'
+block.body # => NoMethodError
+
+block.layout = 'logo_caption'
+block.title # => NoMethodError
+block.logo = { name: 'testing logo' } # Currently this is the way to assign objects
+block.logo.name # => 'testing logo'
+block.logo.class # => TestImage
+block.logo = TestImage.new name: 'testing logo' # Error! Currently assigning the object is not allowed :(
+```
+
+### Block templates
+
+Blocks are rendered using the `render_block` helper which controls all the logic related with renderinf a block, including fragment cache control.
+
+In the end a partial is rendered using the block as a local variable to obtain the information. This partial must be found at `no_cms/blocks/blocks` views folder and have the name configured in the `template` setting of the block. This way, rendering a 'title-3_columns' would render the partial `/no_cms/blocks/blocks/title_3_columns`.
+
+This partial is a regular Rails partial (nothing special here). As an example, this could be the content of our  `/no_cms/blocks/blocks/title_3_columns.html.erb` partial:
+
+```html
+<div class='columns_block'>
+  <h2 class="title"><%= block.title %></h2>
+  <p class="column_1"><%= block.column_1 %></p>
+  <p class="column_2"><%= block.column_2 %></p>
+  <p class="column_3"><%= block.column_3 %></p>
+</div>
+```
+
+As you can see, the partial has a `block` variable containing the block object you are rendering.
+
+Since this is plain old rails you can do everything you can do with a partial (e.g. having a `/no_cms/blocks/blocks/title_3_columns.en.html.erb` for the english version and a `/no_cms/blocks/blocks/title_3_columns.es.html.erb` for the spanish one).
+
+### Block Cache
+
+Since blocks are independent units of content, the standard Rails fragment cache seemed to fit well with them. That's why the `render_block` helper decides wether Rails cache should be used for rendering an individual block.
+
+Cache for the blocks are configured at 3 levels:
+
+1. The `render_block` helper may be called with a `cache_enabled` option set to true or false. This option will enable/disable the cache. This allow us to render a block without using the cache (maybe on a preview action).
+
+  ```ruby
+    render_block block, cache: false
+  ```
+
+2. In the blocks configuration we can enable/disable the cache for all the blocks of a kind. We just have to add the `cache_enabled` setting.
+
+  ```ruby
+  NoCms::Blocks.configure do |config|
+
+    config.block_layouts = {
+      'default' => {
+        template: 'default',
+        fields: {
+          title: :string,
+          body: :text
+        },
+        cache_enabled: false
+      }
+    }
+  end
+  ```
+
+3. In the blocks configuration file we can enable/disable cache for all the blocks that doesn't have a cache_enabled setting. This configuration will be stored at `NoCms::Blocks.cache_enabled`
+
+  ```ruby
+  NoCms::Blocks.configure do |config|
+
+    config.cache_enabled = true
+
+  end
+  ```
+
+As a summary:
+
+```ruby
+
+  b = NoCms::Blocks::Block.new layout: 'default', title: 'Foo', description: 'Bar'
+  NoCms::Blocks.cache_enabled # => true
+  b.cache_enabled # => false, since the block configuration sets it to false
+  render_block b # => This won't use fragment cache since this block layout have cache disabled
+
+  b = NoCms::Blocks::Block.new layout: 'title-3_columns', title: 'Foo', description: 'Bar'
+  NoCms::Blocks.cache_enabled # => true
+  b.cache_enabled # => true, since this block configuration doesn't override NoCms::Block.cache_enabled
+  render_block b # => This will use fragment cache since, by default, it's enabled for all blocks
+
+  render_block b, cache_enabled: false # => This won't use fragment cache as the option in the helper overrides the block configuration
+
+```
+
+## Where is the admin interface?
+
+Since blocks are always attached to another object there ¡s no separate admin interface for them.
+
+Instead of a separate admin interface this engine includes a set of partials that can be used to render it as a basic admin interface attachable to any edit view of any object that has blocks attached.
+
+```ruby
+  <%= render 'no_cms/admin/blocks/blocks/index', f: f %>
+```
+
+### NoCms Admin
+
+This partial is fully compatible with `nocms-admin` gem and works with the JS in that engine that handles creation or modification of blocks.
+
+To enable it just add the following code to your form view.
+
+```ruby
+<% content_for :ready_js do %>
+  NoCMS.Admin.BlockHandler();
+<% end %>
+```
+
+### Block admin templates
+
+Same way that a block has a partial that gets rendered in the public views it has another partial to be rendered inside the admin views if you use the no_cms/admin/blocks/blocks/index partial.
+
+This partial must be found at `no_cms/admin/blocks/blocks` views folder and have the name configured in the `template` setting of the block. This way, rendering a 'title-3_columns' would render the partial `/no_cms/admin/blocks/blocks/title_3_columns`.
+
+This partial is a regular Rails partial (nothing special here). As an example, this could be the content of our  `/no_cms/admin/blocks/blocks/title_3_columns.html.erb` partial:
+
+```html
+<div class="row">
+  <%= f.label :title %>
+  <%= f.text_field :title %>
+</div>
+
+<div class="row">
+  <%= f.label :column_1 %>
+  <%= f.text_area :column_1 %>
+</div>
+
+<div class="row">
+  <%= f.label :column_2 %>
+  <%= f.text_area :column_2 %>
+</div>
+
+<div class="row">
+  <%= f.label :column_3 %>
+  <%= f.text_area :column_3 %>
+</div>
+```

data/Rakefile

@@ -0,0 +1,22 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'NoCMS Blocks'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+task :default => [:"app:spec"]

data/app/assets/javascripts/no_cms/blocks/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/stylesheets/no_cms/blocks/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/controllers/no_cms/blocks/application_controller.rb

@@ -0,0 +1,4 @@
+module NoCms::Blocks
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/decorators/models/no_cms/blocks/block_decorator.rb

@@ -0,0 +1,3 @@
+NoCms::Blocks::Block.class_eval do
+  attr_accessor :no_cms_admin_template
+end

data/app/helpers/no_cms/blocks/application_helper.rb

@@ -0,0 +1,4 @@
+module NoCms::Blocks
+  module ApplicationHelper
+  end
+end

data/app/helpers/no_cms/blocks/blocks_helper.rb

@@ -0,0 +1,28 @@
+module NoCms
+  module Blocks
+    module BlocksHelper
+      def render_block block, options = {}
+        return if block.draft && !options[:force_render_draft]
+        # If we don't have any option about cache enabled then we ask the block
+        options[:cache_enabled] = block.cache_enabled unless options.has_key? :cache_enabled
+
+        block_template = "no_cms/blocks/blocks/#{block.template}"
+
+        # And now decide if we use cache or not
+        if options[:cache_enabled]
+          Rails.cache.fetch cache_key_for_blocks(block, block_template, options) do
+            render block_template, block: block
+          end
+        else
+          render block_template, block: block
+        end
+
+      end
+
+      def cache_key_for_blocks block, block_template, options = {}
+        "#{block_template}/#{block.id}/#{block.updated_at.to_i}#{"/#{options[:initial_cache_key]}" unless options[:initial_cache_key] }"
+      end
+
+    end
+  end
+end

data/app/models/no_cms/blocks/block.rb

@@ -0,0 +1,160 @@
+module NoCms::Blocks
+  class Block < ActiveRecord::Base
+
+    include  NoCms::Blocks::Concerns::TranslationScopes
+
+    acts_as_nested_set
+
+    scope :drafts, ->() { where_with_locale(draft: true) }
+    scope :no_drafts, ->() { where_with_locale(draft: false) }
+    scope :roots, ->() { where parent_id: nil }
+
+    accepts_nested_attributes_for :children, allow_destroy: true
+
+    attr_reader :cached_objects
+
+    translates :layout, :fields_info, :draft
+    accepts_nested_attributes_for :translations
+
+    class Translation
+      serialize :fields_info, Hash
+    end
+
+    after_initialize :set_blank_fields
+    before_save :save_related_objects
+
+    validates :fields_info, presence: { allow_blank: true }
+    validates :layout, presence: true
+
+    def cache_enabled
+      layout_config.has_key?(:cache_enabled) ? layout_config[:cache_enabled] : NoCms::Blocks.cache_enabled
+    end
+
+
+    def layout_config
+      NoCms::Blocks.block_layouts.stringify_keys[layout]
+    end
+
+    def template
+      layout_config[:template] if layout_config
+    end
+
+    def has_field? field
+      # We have the field if...
+      !layout_config.nil? && # We have a layout configuration AND
+        (
+          !layout_config[:fields].symbolize_keys[field.to_sym].nil? || # We have this field OR
+          !layout_config[:fields].symbolize_keys[field.to_s.gsub(/\_id$/, '').to_sym].nil? # we remove the final _id and then we have the field
+        )
+    end
+
+    def field_type field
+      return nil unless has_field?(field)
+      layout_config[:fields].symbolize_keys[field.to_sym]
+    end
+
+    def read_field field
+      return nil unless has_field?(field)
+
+      value = fields_info[field.to_sym] || # first, we get the value
+                @cached_objects[field.to_sym] # or we get it from the cached objects
+
+      # If value is still nil, but the field exists we must get the object from the database
+      if value.nil?
+        field_type = field_type(field)
+        field_id = fields_info["#{field}_id".to_sym]
+        value = @cached_objects[field.to_sym] = field_type.find(field_id) unless field_id.nil?
+      end
+
+      # If value is still nil, and the field_type is an ActiveRecord class, then we
+      if value.nil? && field_type.is_a?(Class)
+        value = @cached_objects[field.to_sym] = field_type.new
+      end
+      value
+    end
+
+    def write_field field, value
+      return nil unless has_field?(field)
+      field_type = field_type field
+      # If field type is a model then we update the cached object
+      if field_type.is_a?(Class) && field_type < ActiveRecord::Base
+        # First, we initialize the object if we don't read the object (it loads it into the cached objects)
+        @cached_objects[field.to_sym] = field_type.new if read_field(field).nil?
+        # Then, assign attributes
+        @cached_objects[field.to_sym].assign_attributes value
+      else # If it's a model then  a new object or update the previous one
+        self.fields_info = fields_info.merge field.to_sym => value # when updating through an object (i.e. the page updates through nested attributes) fields_info[field.to_sym] = value doesn't work. Kudos to Rubo for this fix
+      end
+    end
+
+    # In this missing method we check wether we're asking for one field
+    # in which case we will read or write ir
+    def method_missing(m, *args, &block)
+      # We get the name of the field stripping out the '=' for writers
+      field = m.to_s
+      write_accessor = field.ends_with? '='
+      field.gsub!(/\=$/, '')
+
+      # If this field actually exists, then we write it or read it.
+      if has_field?(field)
+        write_accessor ?
+          write_field(field, args.first) :
+          read_field(field.to_sym)
+      else
+        super
+      end
+    end
+
+    # When we are assigning attributes (this method is called in new, create...)
+    # we must split those fields from our current layout and those who are not
+    # (they must be attributes).
+    # Attributes are processed the usual way and fields are written later
+    def assign_attributes new_attributes
+      fields = []
+
+      set_blank_fields
+
+      # We get the layout
+      new_layout = new_attributes[:layout] || new_attributes['layout']
+      self.layout = new_layout unless new_layout.nil?
+
+      Rails.logger.info "Searching #{new_attributes.keys.inspect} fields in #{self.layout} layout"
+
+      # And now separate fields and attributes
+      fields = new_attributes.select{|k, _| has_field? k }.symbolize_keys
+      new_attributes.reject!{|k, _| has_field? k }
+
+      super(new_attributes)
+
+      Rails.logger.info "Writing #{fields.inspect} to #{self.layout} block"
+
+      fields.each do |field_name, value|
+        self.write_field field_name, value
+      end
+    end
+
+    def reload *args
+      @cached_objects = {}
+      super
+    end
+
+    private
+
+    def set_blank_fields
+      self.fields_info ||= {}
+      @cached_objects ||= {}
+    end
+
+    def save_related_objects
+      # Now we save each activerecord related object
+      cached_objects.each do |field, object|
+        # Notice that we don't care if the object is actually saved
+        # We don't care because there may be some cases where no real information is sent to an object but something is sent (i.e. the locale in a new Globalize translation) and then the object is created empty
+        # When this happens if we save! the object an error is thrown and we can't leave the object blank
+        if object.is_a?(ActiveRecord::Base) && object.save
+          fields_info["#{field}_id".to_sym] = object.id
+        end
+      end
+    end
+  end
+end