rear 0.2.0

data/docs/Setup.md

@@ -0,0 +1,201 @@
+
+## Primary key
+
+**Rear** will do its best to correctly detect the primary key of managed model.
+
+In case it is failing to do so, you can set primary key manually by using `primary_key` method:
+
+```ruby
+  primary_key :ItemID
+```
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+## Ordering
+
+**Rear** will fetch items in the order specified by your model or db.
+
+It is also allow to set specific order by using `order_by` method:
+
+`DataMapper`:
+
+```ruby
+  order_by :name, :id.desc
+```
+
+`ActiveRecord`:
+
+```ruby
+  order_by 'name, id DESC'
+```
+
+Also, on pane pages it is possible to order items by a specific column by clicking on it.
+By default it will sort items in ascending order. To use descending order click on column one more time.
+
+When sorting items this way, "ORDER BY" statement will use only selected column,
+e.g. "ORDER BY name" or "ORDER BY date" etc.
+
+To make Rear to sort by multiple columns when clicking on a specific one, set custom `order_by` for that column:
+
+```ruby
+class News
+  include DataMapper::Resource
+
+  property :id, Serial
+  property :name, String
+  property :date, Date
+
+end
+
+Rear.register News do
+
+  # making Rear to order by both name and date when name clicked
+  input :name do
+    order_by :name, :date
+  end
+end
+```
+
+**Important!** do not pass ordering vector when setting costom `order_by` for columns. Vector will be added automatically, so pass only column names.
+
+**Example:** this will break ordering cause name specifies desc vector
+
+```ruby
+  input :name do
+    order_by :name.desc, :date
+  end
+```
+
+
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Items per page
+
+By default **Rear** will display 10 items per page.
+
+To have it displaying more or less, use `items_per_page` method or its alias - `ipp`:
+
+```ruby
+  items_per_page 50
+```
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Menu Label
+
+**Rear** will build a menu that will include all managed models.
+
+By default, model name will be used as label:
+
+```ruby
+class PageModel < ActiveRecord::Base
+  # ...
+end
+
+Rear.register PageModel
+```
+
+This will display "PageModel" in menu.
+
+To have a custom label displayed, use `menu_label` method:
+
+```ruby
+Rear.register PageModel do
+  menu_label :Pages
+  # ...
+end
+```
+
+Now it will display "Pages" in menu.
+
+It is also possible to use `label` alias to set menu label.
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Menu Positioning
+
+**Rear's** menu will display managed models in the the order they was defined.
+
+To have a model displayed upper, set its position higher.
+
+Or decrease position to have a model displayed lower.
+
+```ruby
+class City < ActiveRecord::Base
+  # ...
+end
+
+class Country < ActiveRecord::Base
+  # ...
+end
+
+class State < ActiveRecord::Base
+  # ...
+end
+
+Rear.register City, Country, State
+```
+
+This will build a menu like `City | Country | State`.
+
+```ruby
+Rear.register City, Country, State do |model|
+  menu_position({
+    Country  => 1000,
+    State    => 500,
+    City     => 100,
+  }[model])
+end
+```
+
+This will build a menu like `Country | State | City`.
+
+It is also possible to use `position` alias to set menu position.
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Menu Grouping
+
+By default **Rear** will build a "flat" menu.
+
+To have some models displayed under some group, use `menu_group` method:
+
+```ruby
+Rear.register City, Country, State do
+  menu_group :Location
+  # or
+  under :Location  # `under` is an alias for `menu_group`
+end
+```
+
+This will create "Location" group that will display "City", "Country" and "State" links on hover.
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**
+
+
+## ReadOnly Mode
+
+When you need to display a whole model in readonly mode, use `readonly!` method:
+
+```ruby
+class State < ActiveRecord::Base
+  # ...
+end
+
+Rear.register State do
+  readonly!
+end
+```
+
+In readonly mode items can not be created/updated nor deleted.
+
+Also all associations will be in readonly mode.
+
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**
+

data/lib/rear.rb

@@ -0,0 +1,13 @@
+require 'el'
+require 'slim'
+
+require 'rear/constants'
+require 'rear/utils'
+require 'rear/orm'
+require 'rear/actions'
+require 'rear/input'
+require 'rear/rear'
+require 'rear/setup'
+require 'rear/helpers'
+require 'rear/controller_setup'
+require 'rear/home_controller'

data/lib/rear/actions.rb

@@ -0,0 +1,98 @@
+module RearActions
+  include RearConstants
+
+  def get_index
+    reander_l(:layout) { reander_p 'pane/layout' }
+  end
+
+  def get_quickview
+    reander_p 'pane/quickview'
+  end
+
+  def get_edit id
+    reander_l(:layout) { reander_p 'editor/layout' }
+  end
+
+  def get_bulk_edit
+    @items = params[:items].to_s.gsub(/[^\d|\s]/, '')
+    self.item, self.item_id = model.new, 0
+    reander_p 'editor/bulk_edit'
+  end
+
+  def post_bulk_edit
+    data = Hash[params]
+    (columns = data.delete('rear-bulk_editor-crudifier_toggler')).is_a?(Array) ||
+      halt(400, 'Nothing to update. Please edit at least one column.')
+    items = data.delete('rear-bulk_editor-items').to_s.strip.split
+    items.empty? && halt(400, 'No items selected')
+
+    data.reject! {|k,v| !columns.include?(k)}
+    updated, failed = [], []
+    items.each do |id|
+      status, h, body = invoke_via_put(:crud, id, data)
+      status == 200 ? updated << id : failed << ['%s Failed' % id, *body]
+    end
+    failed.any? && styled_halt(500, failed)
+    "Successfully Updated Items:\n%s" % updated.join(', ')
+  end
+
+  def get_reverse_assoc source_ctrl, assoc_type, assoc_name, item_id, attached = nil
+    reander_p 'pane/assocs'
+  end
+
+  def post_reverse_assoc source_ctrl, assoc_type, assoc_name, item_id, attached = nil
+    case @reverse_assoc.type
+    when :belongs_to, :has_one
+      @reverse_assoc.source_item.send '%s=' % @reverse_assoc.name, @reverse_assoc.target_item
+    when :has_many
+      @reverse_assoc.source_item.send(@reverse_assoc.name).each do |ti|
+        ti[pkey] == @reverse_assoc.target_item[pkey] && halt(400, "Relation already exists")
+      end
+      if sequel?
+        m = 'add_' << orm.singularize(@reverse_assoc.name)
+        @reverse_assoc.source_item.send m, @reverse_assoc.target_item
+      else
+        @reverse_assoc.source_item.send(@reverse_assoc.name) << @reverse_assoc.target_item
+      end
+    end
+    @reverse_assoc.source_item.save
+  end
+
+  def delete_reverse_assoc source_ctrl, assoc_type, assoc_name, item_id, attached = nil
+    case @reverse_assoc.type
+    when :belongs_to, :has_one
+      @reverse_assoc.source_item.send '%s=' % @reverse_assoc.name, nil
+    when :has_many
+      if sequel?
+        (@reverse_assoc.source_item.send(@reverse_assoc.name)||[]).each do |ti|
+          next unless ti[pkey] == @reverse_assoc.target_item[pkey]
+          m = 'remove_' << orm.singularize(@reverse_assoc.name)
+          @reverse_assoc.source_item.send m, ti
+        end
+      else
+        target_items = Array.new(@reverse_assoc.source_item.send(@reverse_assoc.name)||[]).reject do |ti|
+          ti[pkey] == @reverse_assoc.target_item[pkey]
+        end
+        @reverse_assoc.source_item.send '%s=' % @reverse_assoc.name, target_items
+      end
+    end
+    @reverse_assoc.source_item.save
+  end
+
+  def delete_delete_selected
+    halt(400, '%s is in readonly mode' % model) if readonly?
+    if (ids = params[:items].to_s.split.map(&:to_i).select {|r| r > 0}).any?
+      orm.delete_multiple(*ids)
+    end
+  end
+
+  def html_filters partial = false
+    partial ? render_filters : reander_p('filters/layout')
+  end
+
+  def get_assets(*)
+    env['PATH_INFO'] = env['PATH_INFO'].to_s.sub(ASSETS__SUFFIX_REGEXP, '')
+    send_files @__rear__assets_fullpath ? @__rear__assets_fullpath :
+      (@__rear__assets_path ? File.join(app.root, @__rear__assets_path) : ASSETS__PATH)
+  end
+end

data/lib/rear/constants.rb

@@ -0,0 +1,61 @@
+module RearConstants
+
+  PATH__TEMPLATES = (File.expand_path('../templates', __FILE__) + '/').freeze
+  
+  ASSETS__PATH = (File.expand_path('../../../assets', __FILE__) + '/').freeze
+  ASSETS__SUFFIX = '-rear'.freeze
+  ASSETS__SUFFIX_REGEXP = /#{Regexp.escape ASSETS__SUFFIX}\Z/.freeze
+
+  COLUMNS__HANDLED_TYPES = [
+    :string, :text,
+    :date, :time, :datetime,
+    :radio, :checkbox, :select,
+    :boolean
+  ].freeze
+  COLUMNS__DEFAULT_TYPE  = :string
+  COLUMNS__BOOLEAN_MAP   = {true => 'Y', false => 'N'}.freeze
+  COLUMNS__PANE_MAX_LENGTH = 255
+  
+  PAGER__SIDE_PAGES = 5
+
+  FILTERS__HANDLED_TYPES   = COLUMNS__HANDLED_TYPES
+  FILTERS__DEFAULT_TYPE    = :string
+  FILTERS__DECORATIVE_CMP  = :decorative
+  FILTERS__STR_TO_BOOLEAN  = {"true" => true, "false" => false}.freeze
+  FILTERS__QUERY_MAP = lambda do |orm|
+    # using lambda will always return a new copy of Hash, so no need to deep copy it
+    default_query_map = {
+       gt: ['%s >  ?', '%s'],
+       lt: ['%s <  ?', '%s'],
+      gte: ['%s >= ?', '%s'],
+      lte: ['%s <= ?', '%s'],
+      not: ['%s <> ?', '%s'],
+      eql: ['%s =  ?', '%s'],
+      
+      # use left and right wildcards - '%VALUE%'
+      like:   ['%s LIKE ?', '%%%s%'],
+      unlike: ['%s NOT LIKE ?', '%%%s%'],
+
+      # use only left  wildcard - exact match for end of line - LIKE '%VALUE'
+      _like:   ['%s LIKE ?', '%%%s'],
+      _unlike: ['%s NOT LIKE ?', '%%%s'],
+
+      # use only right wildcard - exact match for beginning of line - LIKE 'VALUE%'
+      like_:   ['%s LIKE ?', '%s%'],
+      unlike_: ['%s NOT LIKE ?', '%s%'],
+
+      in:  ['%s IN ?'],
+      csl: ['%s IN ?'], # comma separated list
+      FILTERS__DECORATIVE_CMP => []
+    }
+    {
+      ar: default_query_map.merge(:in => ['%s IN (?)'], :csl => ['%s IN (?)']),
+      dm: default_query_map,
+      sq: default_query_map,
+    }[orm]
+  end
+
+  ASSOCS__STRUCT = lambda do
+    {belongs_to: {}, has_one: {}, has_many: {}}
+  end
+end

data/lib/rear/controller_setup.rb

@@ -0,0 +1,249 @@
+class RearControllerSetup
+  include RearConstants
+
+  class << self
+
+    def init(*args, &proc)
+      new.init(*args, &proc)
+    end
+
+    def crudify(*args, &proc)
+      new.crudify(*args, &proc)
+    end
+
+  end
+
+  def init ctrl
+    (@ctrl = ctrl).class_exec do
+      extend  RearSetup
+      extend  RearHelpers::ClassMixin
+      include RearConstants
+      include RearHelpers::InstanceMixin
+      import  RearActions
+
+      include EL::Ace if defined?(EL::Ace)
+      include EL::CKE if defined?(EL::CKE)
+
+      reject_automount!
+      EUtils.register_extra_engines!
+    end
+
+    define_setup_methods
+    define_error_handlers
+  end
+
+  def crudify ctrl, model, opts, &proc
+    (@ctrl = ctrl).class_exec do
+      @__rear__orm = RearUtils.orm(model)
+      @__rear__assocs = RearUtils.extract_assocs(model)
+      @__rear__real_columns, @__rear__pkey = RearUtils.extract_columns(model)
+      @__rear__real_columns.each do |c|
+        input(*c) unless @__rear__assocs[:belongs_to].any? {|a,s|
+          s[:belongs_to_keys][:source] == c.first
+        }
+      end
+    end
+
+    setup_crudifier(opts, &proc)
+    define_association_hooks
+    define_pane_hooks
+    define_editor_hooks
+    define_default_filters
+  end
+
+  def setup_crudifier opts, &proc
+    @ctrl.class_exec do
+
+      # use :destroy! on DataMapper
+      opts[:delete] ||= :destroy! if orm == :dm
+
+      # asking Espresso to define CRUD actions
+      crudify(model, :crud, opts, &proc)
+
+      alias_before :post_crud,   :create, :save
+      alias_before :put_crud,    :update, :save
+      alias_before :delete_crud, :destroy
+
+      before :create, :update, :destroy do
+        halt(400, '%s is in readonly mode' % model) if readonly?
+      end
+    end
+  end
+
+  def define_default_filters
+    @ctrl.class_exec do
+      # built-in filter for all controllers. it will search by primary key
+      filter(pkey, cmp: :csl, class: 'input-small search-query')
+    end
+  end
+
+  def define_setup_methods
+    @ctrl.class_exec do
+
+      # allow to set path to custom templates.
+      # to use custom templates install them via "$ rear i:t PATH"
+      # and use `rear_templates PATH` when mounting Rear controllers.
+      #
+      # @example
+      #   # install templates in views/ folder
+      #   $ rear i:t views/
+      #
+      #   # set path to custom templates when mounting Rear controllers
+      #   E.new do
+      #     mount Rear.controllers, '/admin' do
+      #       rear_templates 'views/rear/'
+      #     end
+      #   end
+      #
+      def rear_templates path
+        return @__rear__templates_fullpath = path.to_s if path =~ /\A(\w\:)?\// && @__rear__templates_fullpath.nil?
+        @__rear__templates_path = path.to_s if @__rear__templates_path.nil?
+      end
+      define_setup_method :rear_templates
+
+      # similar to `rear_templates` except it sets path to custom assets
+      def rear_assets path
+        return @__rear__assets_fullpath = path.to_s if path =~ /\A(\w\:)?\// && @__rear__assets_fullpath.nil?
+        @__rear__assets_path = path.to_s if @__rear__assets_path.nil?
+      end
+      define_setup_method :rear_assets
+
+    end
+  end
+
+  def define_error_handlers
+    @ctrl.class_exec do
+      error 500 do |e|
+        error = if e.respond_to?(:backtrace)
+          e.backtrace.inject([e.message]) {|bt,l| bt << l}
+        elsif e.is_a?(Array)
+          e
+        else
+          [e.to_s]
+        end
+        out = rq.xhr? ? error*"\n" : reander_l(:layout) {reander_p :error, error: error}
+        halt 500, out
+      end
+    end
+  end
+
+  def define_association_hooks
+    @ctrl.class_exec do
+      # all communications between associated models happens through primary keys.
+      # it does not matter what keys models using to associate one to each other,
+      # Rear will always use pkeys to display/update associated objects.
+      # this is achieved by using ORM setters for associated objects,
+      # like `state=` on `belongs_to :state` assocs
+      # or `cities<<` on `has_many :cities` etc.
+      # so it will basically fetch remote objects by pkey and feed them to that setters.
+      #
+      # hooks order is important. this one should always go first
+      before /reverse_assoc/ do
+        ctrl     = action_params[:source_ctrl].split('::').inject(Object) {|f,c| f.const_get(c)}
+        assoc    = ctrl.assocs[action_params[:assoc_type].to_sym][action_params[:assoc_name].to_sym]
+        readonly = ctrl.readonly_assocs.include?(assoc[:name]) || assoc[:readonly] || ctrl.readonly?
+        halt(400, '%s is in readonly mode' % model) if readonly && (post? || delete?)
+        struct   = {
+                 type: assoc[:type],
+                 name: assoc[:name],
+               dom_id: assoc[:dom_id] + (action_params[:attached] ? '' : '_detached'),
+             readonly: readonly ? true : false, # using true/false here cause it will be converted to string and fed to javascript
+             attached: action_params[:attached],
+                route: route(action, *action_params__array[0..3]),
+          source_item: RearORM.new(ctrl.model, ctrl.pkey)[action_params[:item_id].to_i],
+          target_item: orm[params[:target_item_id].to_i]||{},
+           source_key: nil,
+           target_key: nil,
+        }
+        if struct[:type] == :belongs_to && (struct[:attached] || struct[:source_item].nil?)
+          struct[:source_key], struct[:target_key] =
+            assoc[:belongs_to_keys].values_at(:source, :target)
+        end
+        @reverse_assoc = Struct.new(*struct.keys.map(&:to_sym)).new(*struct.values).freeze
+      end
+    end
+  end
+
+  def define_pane_hooks
+    @ctrl.class_exec do
+      before :get_index, :get_reverse_assoc, :get_quickview do
+        
+        conditions = filters_to_sql
+
+        source_item, source_assoc = nil
+        if @reverse_assoc && @reverse_assoc.attached
+          if source_item = @reverse_assoc.source_item
+            source_assoc = @reverse_assoc.name
+          else
+            conditions = {conditions: {pkey => 0}}
+          end
+        end
+
+        total_items = source_item ?
+          orm.assoc_count(source_assoc, source_item, conditions) :
+          orm.count(conditions)
+
+        total_pages = (total_items.to_f / __rear__.ipp.to_f).ceil
+        side_pages  = xhr? ? 2 : PAGER__SIDE_PAGES
+        
+        current_page = params[:page].to_i
+        current_page = 1 if current_page < 1
+        current_page = total_pages if current_page > total_pages
+
+        page_min = current_page  - side_pages
+        page_min = total_pages   - (side_pages * 2) if (current_page + side_pages) > total_pages
+        page_min = 1 if page_min < 1
+
+        page_max = current_page + side_pages
+        page_max = side_pages   * 2 if current_page < side_pages
+        page_max = total_pages  if page_max > total_pages
+
+        offset = (current_page - 1) * __rear__.ipp
+        offset = 0 if offset < 0
+
+        counter = [offset + 1, offset + __rear__.ipp, total_items]
+        counter[0] = offset if counter[0] > total_items
+        counter[1] = total_items if counter[1] > total_items
+
+        @pager_context = {
+           total_items: total_items,
+           total_pages: total_pages,
+          current_page: current_page,
+              page_min: page_min,
+              page_max: page_max,
+               counter: counter.map {|n| RearUtils.number_with_delimiter(n)}
+        }
+        @pager = total_pages > 1 ? reander_p(:pager, @pager_context) : ''
+        
+        conditions[:limit ] = __rear__.ipp
+        conditions[:offset] = offset
+        
+        if order = order_params_to_sql || __rear__.order_by
+          conditions[:order] = order
+        end
+
+        @items = if source_item
+          orm.assoc_filter(source_assoc, source_item, conditions)
+        else
+          orm.filter(conditions)
+        end
+      end
+    end
+  end
+
+  def define_editor_hooks
+    @ctrl.class_exec do
+      before :get_edit do
+        if (id = action_params[:id].to_i) > 0
+          @item = orm[id] || halt(400, "Item with ID %s not found" % id)
+          @item_id = id
+        else
+          @item = @brand_new_item = model.new
+          @item_id = 0
+        end
+      end
+
+    end
+  end
+  
+end