autoforme 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6375a5b69141ffd6b2d499165407588b1e11154d
+  data.tar.gz: 24578636cda7918d7deb38dc24ccd44d4d2c5887
+SHA512:
+  metadata.gz: 83f29c0cf2764928f08d23c7b4e54b636a50670a1d75dee7698616e4f8828206b3c3adee93c75937cbd6d0d81b1aff4cfc2395e934429a5eb12c8b9b1a05a9bc
+  data.tar.gz: 869465f07383c25f289f39c143dacf978502a9af1f0c8d6c0cdc5f0b271ec5aa4cc2b8190680c0fcbd7c43968437075036221d1e84a9fb51511dc9979821d226

data/CHANGELOG

@@ -0,0 +1,3 @@
+=== 0.5.0 (2013-12-13)
+
+* Initial Public Release

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2013 Jeremy Evans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+  
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+   
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,226 @@
+= AutoForme
+
+AutoForme is an administrative web front end to an ORM that uses
+Forme [1] for building the HTML forms.  It is designed to
+integrate easily into web frameworks, and currently supports
+both Sinatra and Rails.
+
+AutoForme's UI and capabilities are modeled on
+scaffolding_extensions [2], though AutoForme is considerably more
+flexible in terms of configuration.
+
+1. https://github.com/jeremyevans/forme
+2. https://github.com/jeremyevans/scaffolding_extensions
+
+= Demo Site
+
+A demo site is available at http://autoforme-demo.jeremyevans.net
+
+= Source Code
+
+Source code is available on GitHub at https://github.com/jeremyevans/autoforme
+
+= Features
+
+* Create, update, edit, and view model objects
+* Browse and search model objects
+* Edit many-to-many relationships for model objects
+* Easily access associated objects
+* Support autocompletion for all objects
+* Allow customization for all likely configuration points, using
+  any parameters available in the request
+
+= Basic Configuration
+
+AutoForme is configured using a fairly simple DSL.  Here is an example:
+
+  class App < Sinatra::Base
+    AutoForme.for(:sinatra, self) do
+      model_type :sequel
+      order [:name]
+
+      model Artist do
+        columns [:name]
+      end
+      model Album do
+        columns [:artist, :name]
+      end
+    end
+  end
+
+Let's break down how this works.  You setup AutoForme using <tt>AutoForme.for</tt>,
+which takes 2 arguments, the controller type symbol (currently either :sinatra or :rails),
+and the controller class (either a Sinatra::Base or ActionController::Base subclass).  You
+pass <tt>AutoForme.for</tt> a block, which is instance evaled at the framework level.  This
+level sets the defaults.
+
+Inside the framework block, you first call model_type with a symbol representing the ORM you are
+using.  Currently, only Sequel is supported, so this should be :sequel.
+
+The order call in the framework block sets the default order for all models.
+
+The model calls in the framework block take a ORM model class.  As only Sequel is currently
+supported, this should be a Sequel::Model subclass.  The block passed to the model method is
+instance evaled at the model level, and sets the configuration for that model.  In this example,
+the Artist model will only show the name column, and the Album model will only show the artist
+association and the name column.
+
+In your application, you can then to go '/Artist/browse' or '/Album/browse' to get to the web
+UI exposed to AutoForme.
+
+= Design
+
+== Principles
+
+* Use Forme to generate the forms
+* Do not modify/extend model or controller classes
+* Assume that the web framework provides the layout
+* Do not use templates, render form objects to strings
+* Use a block-based DSL in the controller for configuration
+* Allow customization on a per-request basis for everything
+
+== Basic Implementation
+
+The web framework controllers call <tt>AutoForme.for</tt> to create
+AutoForme::Framework instances, which contain and set default values
+for AutoForme::Model instances.
+
+When a request comes in from the web framework, the AutoForme::Framework
+instance wraps request-level data in a AutoForme::Request.  Then it
+creates an AutoForme::Action to handle this request.  The
+AutoForme::Action either returns a string that the web framework then
+renders, or it redirects to another page.
+
+= Advanced Configuration
+
+AutoForme doesn't have all that many features compared to other admin
+frameworks, but the features it does have are extremely flexible.
+
+Most of the configuration you'll do in AutoForme is at the model
+level (in the context of an AutoForme::Model instance), so we'll start
+looking at the customization options there.  The most common options
+are probably:
+
+columns :: This is an array of column/association name symbols to use
+           for the model.
+column_options :: This is a hash of column options for the model,
+                  keyed by column symbol, with values that are hashes
+                  of column options.
+order :: This is an expression or an array of expressions by which
+         to order returned rows.
+
+Note that for each of the customization options, you can do per-request
+customization by using a proc which is called with the type symbol and
+request (AutoForme::Request instance), which should return an appropriate
+object.
+
+columns :: Proc called with type symbol and request, should return array
+           of column/association symbols
+column_options :: Proc called with column/association symbol, type symbol
+                  and request, should return hash of column options.
+order :: Proc called with type symbol and request, should return expression 
+         or array of expressions by which to order returned rows.
+
+Below is brief description of other available options.  Note that just like the above
+options you can use Procs with most of these options to do customization on a
+per-request basis.
+
+association_links :: Array of association symbols for associations to display on the show/edit pages,
+                     can also be set to :all for all associations or :all_except_mtm for all associations
+                     except many to many associations.
+autocomplete_options :: Enable autocompletion for this model, with the given
+                        options.  The following keys are respected:
+                        :callback :: Proc called with dataset and options hash containing :type, :request, and :query
+                        :display :: A SQL expression to search on and display in the result
+                        :limit :: The number of results to return
+                        :filter :: Similar to callback, but overriding the default filter
+                                   (a case insensitive substring search on display)
+eager :: Array of associations to eagerly load in separate queries
+eager_graph :: Array of associations to eager load in the same query
+               (necessary if order or filter refers to them)
+filter :: A Proc called with a dataset, type symbol, and request that
+          can be used to filter the available rows.  Can be used to
+          implement access control.
+redirect :: A Proc called with an object, type symbol, and request that can be used to override
+            the default redirecting after form submittal.
+inline_mtm_associations :: Array of many to many association symbols to allow editing on the edit page
+lazy_load_association_links :: Whether to show the association links directly on the show/edit pages,
+                               or to load them via ajax on request
+mtm_associations :: Array of many to many association symbols to support editing on a separate page 
+per_page :: Number of records to show per page on the browse and search pages
+session_value :: Sets up a filter and before_create hook that makes it so access is limited
+                 to objects where the object's column value is the same as the session value
+                 with the same name.
+supported_actions :: Array of action symbols to support for the model, should be a subset of
+                     [:browse, :new, :show, :edit, :delete, :search, :mtm_edit]
+
+These options are related to displayed output:
+
+form_attributes :: Hash of attributes to use for any form tags
+form_options :: Hash of Forme::Form options to pass for any forms created
+class_display_name :: The string to use when referring to the model class
+display_name :: The string to use when referring to a model instance.  Can either be a symbol
+                representing an instance method call, or a Proc called with the model object,
+                the model object and type symbol, or the model object, type symbol, and request,
+                depending on the arity of the Proc.
+link_name :: The string to use in links for the class
+page_footer :: Override the default footer used for pages
+page_header :: Override the default header used for pages
+table_class :: The html class string to use for the browse and search tables
+
+These hook options should be callable objects that are called with the model object and the request.
+
+after_create :: Called after creating the object
+after_destroy :: Called after destroy the object
+after_update :: Called after updating the object
+before_create :: Called before creating the object 
+before_destroy :: Called before destroy the object
+before_edit :: Called before displaying object on edit page
+before_new :: Called before displaying object on new page
+before_update :: Called before updating the object
+
+There's also an addition before_action hook that is called with the type symbol of the request, and
+the request before every page.
+
+In addition to being specified at the model level, almost all of these options can be specified at the
+framework level, where they operate as default values for models that don't specify the options. Just
+like the model level, the framework level also allows customization on a per request basis, though
+framework-level Procs generally take the model class as an initial argument (in addition to the type
+symbol and request).
+
+Additionally, AutoForme.for accepts a :prefix option that controls where the forms are mounted:
+
+  AutoForm.for(:sinatra, self, :prefix=>'/path/to') do
+    model Artist
+  end
+
+Means you can go to <tt>/path/to/Artist/browse</tt> to browse the artists.
+
+= Javascript
+
+By default, AutoForme requires no javascript.  The only optional
+part of AutoForme that requires javascript is the autocompleting.
+AutoForme also has javascript support for the progressive enhancement of the following:
+
+* Loading association links via ajax if lazy_load_association_links is true.
+* Adding and removing many-to-many associated objects via ajax for inline_mtm_associations
+
+AutoForme's javascript support is contained in the autoforme.js file in the root
+of the distribution.  AutoForme's autocompleting support also requires
+https://github.com/dyve/jquery-autocomplete
+
+= TODO
+
+* capybara-webkit tests for ajax behavior
+* read_only fields for edit page
+* one_to_many/many_to_many associations in columns
+* configurable searching
+* nested form objects
+
+= License
+
+MIT
+
+= Author
+
+Jeremy Evans <code@jeremyevans.net>

data/Rakefile

@@ -0,0 +1,79 @@
+require "rake"
+require "rake/clean"
+
+CLEAN.include ["autoforme-*.gem", "rdoc", "coverage"]
+
+desc "Build autoforme gem"
+task :package=>[:clean] do |p|
+  sh %{#{FileUtils::RUBY} -S gem build autoforme.gemspec}
+end
+
+### Specs
+
+begin
+  require "rspec/core/rake_task"
+
+  spec = lambda do |name, files, d|
+    lib_dir = File.join(File.dirname(File.expand_path(__FILE__)), 'lib')
+    ENV['RUBYLIB'] ? (ENV['RUBYLIB'] += ":#{lib_dir}") : (ENV['RUBYLIB'] = lib_dir)
+    desc d
+    RSpec::Core::RakeTask.new(name) do |t|
+      t.pattern= files
+    end
+  end
+
+  spec_with_cov = lambda do |name, files, d|
+    spec.call(name, files, d)
+    desc "#{d} with coverage"
+    task "#{name}_cov" do
+      ENV['COVERAGE'] = '1'
+      Rake::Task[name].invoke
+    end
+  end
+  
+  task :default => [:spec]
+  spec_with_cov.call("spec", Dir["spec/*_spec.rb"], "Run specs with sinatra/sequel")
+
+  desc "Run specs with rails/sequel"
+  task :rails_spec do
+    begin
+      ENV['FRAMEWORK'] = 'rails'
+      Rake::Task[:spec].invoke
+    ensure
+      ENV.delete('FRAMEWORK')
+    end
+  end
+
+rescue LoadError
+  task :default do
+    puts "Must install rspec >=2.0 to run the default task (which runs specs)"
+  end
+end
+
+### RDoc
+
+RDOC_DEFAULT_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', 'AutoForme: Web Adminstrative Console for Sinatra/Rails and Sequel']
+
+begin
+  gem 'rdoc', '= 3.12.2'
+  gem 'hanna-nouveau'
+  RDOC_DEFAULT_OPTS.concat(['-f', 'hanna'])
+rescue Gem::LoadError
+end
+
+rdoc_task_class = begin
+  require "rdoc/task"
+  RDoc::Task
+rescue LoadError
+  require "rake/rdoctask"
+  Rake::RDocTask
+end
+
+RDOC_OPTS = RDOC_DEFAULT_OPTS + ['--main', 'README.rdoc']
+
+rdoc_task_class.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.options += RDOC_OPTS
+  rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/**/*.rb"
+end
+

data/autoforme.js

@@ -0,0 +1,77 @@
+$(function() {
+  var autoforme = $('#autoforme_content');
+  var base_url = autoforme.data('url');
+
+  function autoforme_fix_autocomplete(e) {
+    $(e).find('.autoforme_autocomplete').each(function(){
+      $(this).val($(this).val().split(' - ', 2)[0]);
+    });
+  }
+
+  function autoforme_setup_autocomplete() {
+    autoforme.find('.autoforme_autocomplete').each(function(){
+      var e = $(this);
+      var column = e.data('column');
+      var exclude = e.data('exclude');
+      var url = base_url + '/autocomplete';
+      if (column) {
+        url += '/' + column;
+      }
+      url += '?type=' + e.data('type');
+      if (exclude) {
+        url += '&exclude=' + exclude;
+      }
+      e.autocomplete(url);
+    });
+  }
+
+  autoforme_setup_autocomplete();
+
+  autoforme.on('submit', 'form', function(e){
+    autoforme_fix_autocomplete(this);
+  });
+
+
+  $('#lazy_load_association_links').click(function(e){
+    var t = $(this);
+    t.load(base_url + "association_links/" + t.data('object') + "?type=" + t.data('type'), autoforme_setup_autocomplete);
+    t.unbind('click');
+    e.preventDefault();
+  });
+
+  autoforme.on('submit', '.mtm_add_associations', function(e){
+    var form = $(this);
+    if (form.find('.autoforme_autocomplete').length == 0) {
+      var select = form.find('select')[0];
+      $.post(this.action, form.serialize(), function(data, textStatus){
+        $(select).find('option:selected').remove();
+        select.selectedIndex = 0;
+        $(form.data('remove')).append(data);
+      });
+    } else {
+      autoforme_fix_autocomplete(form);
+      $.post(this.action, form.serialize(), function(data, textStatus){
+        var t = form.find('.autoforme_autocomplete');
+        t.val('');
+        t.data('autocompleter').cacheFlush();
+        $(form.data('remove')).append(data);
+      });
+    }
+    e.preventDefault();
+  });
+
+  autoforme.on('submit', '.inline_mtm_remove_associations form', function(e){
+    var form = $(this);
+    var parent = form.parent();
+    $.post(this.action, form.serialize(), function(data, textStatus){
+      var t = $(form.data('add'));
+      if (t[0].type == "text") {
+        t.data('autocompleter').cacheFlush();
+      } else {
+        t.append(data);
+      }
+      parent.remove();
+    });
+    e.preventDefault();
+  });
+});