worth_saving 0.0.9

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZjlmNDY3YThhOGEwMzNjOTgzYzNiNTdjNDUyMDY0ODEwODU4NTE2OA==
+  data.tar.gz: !binary |-
+    MTgzZmQyN2E2MGNhNGFiNDM3YTE0OTZjYTJiYTZjNDRjNWQxMTRlNQ==
+SHA512:
+  metadata.gz: !binary |-
+    OTA2YTM1NTJlOTBkM2RhZGY1NzgxNDk2MjY4ZWE1MzJmZDQzMjg4NzBlM2Nh
+    NmU1MGYyYjZiZmU3ZDY4ZWNjY2EwMTE5MjVlYjI1Njk3NzA1ZjY0NTBiMzlh
+    NjQ1M2EwNTc3ZTVkMzk3MTNhMGZlYjQ4MjM3YjE3YzRiNTk3OWM=
+  data.tar.gz: !binary |-
+    NGRmY2QwNTU0YTI3ZGFkODcwYjJkMDY4MjYxZGY4NDI4ODJkNThjN2JhNWU4
+    ZGYwMjJjOWQ3NGM4NjA2OGUxYmVhM2IyNjYwZWJlYTM2ODgxNWI3M2M3YzYy
+    MWY5YzdiYTgwMDhhYjFhNGYzNGI5NmQwYWUxOGVjNWI4MzhmMTE=

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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 OR COPYRIGHT HOLDERS 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.md

@@ -0,0 +1,90 @@
+# worth_saving gem
+
+[![Build Status](https://travis-ci.org/johnnylaw/worth_saving.png)](http://travis-ci.org/johnnylaw/worth_saving)
+[![Code Climate](https://codeclimate.com/github/johnnylaw/worth_saving.png)](https://codeclimate.com/github/johnnylaw/worth_saving)
+[![Coverage Status](https://coveralls.io/repos/johnnylaw/worth_saving/badge.png)](https://coveralls.io/r/johnnylaw/worth_saving)
+
+
+### What is worth_saving?
+
+The worth_saving gem is a Rails engine intended for those creating web applications whose forms are long, where editing can sometimes go on for a long period without saving.  When recovery of these unsaved edits is important, the worth_saving gem's magic makes saving and recovering draft copies a cinch.
+
+### How to start?
+
+Install worth_saving as a gem:
+
+    gem install worth_saving
+
+Include worth_saving in your Gemfile with `gem 'worth_saving'`.
+
+To completely set up your application to work you will need to include the following in one of your javascript manifests that is included wherever you will use worth_saving:
+
+    //= require worth_saving
+
+You may also include the following in a stylesheet manifest, although you may find that you want to define your own CSS:
+
+    /*= require worth_saving
+
+By mounting the engine in your routes.rb file, you will provide the necessary routing for drafts to save automatically while editing objects whose classes use the worth_saving functionality:
+
+    mount WorthSaving::Engine => '/worth_saving'
+
+In any model whose edits you want to draft, place the following:
+
+    class Example < ActiveRecord::Base
+      is_worth_saving
+    end
+
+There are two options:
+
+    is_worth_saving scope: :user, except: :title
+
+#### The :scope option
+
+When working on a new record, the draft copy is saved without the benefit of an ID on the main record being drafted, but it is imperative for retrieving the draft later that some uniquely identifying information be saved in the draft.  In the example above, perhaps the Page class is_worth_saving.  If a page belongs_to :user, then a natural choice for scope would be user.  In this way you ensure that two different users with unsaved changes to new Page records cannot accidentally retrieve and see one another's drafts.
+
+#### The :except option
+
+Certain fields may contain sensitive information that should not be drafted.  Additionally any filter_parameters from your Rails app config will always be redacted from the WorthSaving::Draft records to maintain the privacy you would expect for your users.
+
+#### Creating a form that autosaves drafts
+
+To invoke the form that will automatically incorporate all the magic, use the following wherever you would use form_for:
+
+    worth_saving_form_for(@page, save_interval: 15, recovery_message: I18n.t("worth_saving.recovery_message")) do |f|
+      = f.label :title
+      br
+      = f.text_field :title
+
+      ...
+
+
+The :save_interval option is the number of seconds that will pass after the first unsaved change before firing a draft copy off to the engine.  It is not necessary to put this option here, and it defaults to whatever you set it in initialization or 60 seconds if you do nothing:
+
+    WorthSaving.configure do |config|
+      config.default_save_interval = <number of seconds to wait after changes occur before saving draft>
+    end
+
+The :recovery_message is a message that appears when a user visits a page where the record being edited has a draft copy.  It too has a default already built in, which can be overridden in the configure block or fed as an option to #worth_saving_form_for as above.
+
+#### Security
+
+Not just anyone should be able to save a draft copy of a record; only someone authorized to edit that record should.  Two methods can be implemented in your ApplicationController class to prevent people from saving drafts to records they do not have the authority to edit (or scopes they do have the authority to add records to).  The WorthSaving::DraftsController will defer to these methods when processing draft posts/patches/puts if they are defined in ApplicationController.  If you do not implement them here, it's assumed that anyone can create a draft for any record.  It is recommended you implement these if the records themselves require authorization.
+
+Example (How you might implement these methods if using CanCan; #authorized_to_draft_with_scope? will be called only if the record is not persisted):
+
+    class ApplicationController < ActionController::Base
+      def authorized_to_draft_record?(record)
+        can? :manage, record
+      end
+
+      def authorized_to_draft_with_scope?(scope)
+        can? :add_records, scope
+      end
+    end
+
+#### Upcoming changes
+* support for simple_form
+* support for TinyMCE and CKEditor (currently the values in the editor window can be overlooked, as the JS simply grabs the value of the textarea or input)
+* support for additional namespaced DraftsControllers that inherit from controllers in your application (e.g. class WorthSaving::Admin::DraftsController < AdminController accessed automatically when invoking worth_saving_form_for [:admin, @record] ...)
+

data/Rakefile

@@ -0,0 +1,29 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'WorthSaving'
+  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
+

data/app/assets/javascripts/worth_saving/application.js

@@ -0,0 +1,15 @@
+// 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
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require_self
+

data/app/assets/stylesheets/worth_saving/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/worth_saving/application_controller.rb

@@ -0,0 +1,4 @@
+module WorthSaving
+  class ApplicationController < ::ApplicationController
+  end
+end

data/app/controllers/worth_saving/drafts_controller.rb

@@ -0,0 +1,51 @@
+class WorthSaving::DraftsController < WorthSaving::ApplicationController
+  def create
+    @draft = WorthSaving::Draft.new draft_params
+    save_if_authorized_and_respond
+  end
+
+  def update
+    @draft = WorthSaving::Draft.find params[:id]
+    @draft.attributes = draft_params
+    save_if_authorized_and_respond
+  end
+
+  private
+
+  def draft_params
+    if WorthSaving::Info.attribute_whitelisting_required?
+      params[:draft]
+    else
+      params.require(:draft).permit :recordable_id, :recordable_type, :scopeable_id, :scopeable_type, :form_data
+    end
+  end
+
+  def save_if_authorized_and_respond
+    authorized? ? save_and_respond : render_forbidden_error
+  end
+
+  def save_and_respond
+    if @draft.save
+      render json: { message: 'Draft saved', worthSavingDraft: { action: worth_saving.draft_path(@draft) } }
+    else
+      render json: { error: 'Unable to save draft' }
+    end
+  end
+
+  def render_forbidden_error
+    render status: 403, text: "Not authorized to draft this #{@draft.recordable_type}"
+  end
+
+  def authorized?
+    return authorized_to_draft_record?(@draft.recordable) if @draft.recordable
+    authorized_to_draft_with_scope?(@draft.scopeable)
+  end
+
+  def authorized_to_draft_record?(recordable)
+    defined?(super) ? super : true
+  end
+
+  def authorized_to_draft_with_scope?(scopeable)
+    defined?(super) ? super : true
+  end
+end

data/app/helpers/worth_saving/application_helper.rb

@@ -0,0 +1,4 @@
+module WorthSaving
+  module ApplicationHelper
+  end
+end

data/app/models/worth_saving/draft.rb

@@ -0,0 +1,47 @@
+class WorthSaving::Draft < ActiveRecord::Base
+  if WorthSaving::Info.attribute_whitelisting_required?
+    attr_accessible :scopeable, :recordable_id, :recordable_type, :scopeable_id, :scopeable_type, :form_data
+  end
+
+  self.table_name = 'worth_saving_drafts'
+  belongs_to :recordable, polymorphic: true
+  belongs_to :scopeable, polymorphic: true
+
+  validates :recordable_type, presence: true
+  validate :uniquely_findable, if: ->{ recordable_type && scoped_record? }
+
+  def reconstituted_record
+    return unless recordable_class
+    record = recordable || recordable_class.new
+    record.attributes = recordable_params
+    record
+  end
+
+  private
+
+  def uniquely_findable
+    unless recordable || scopeable
+      errors.add :base, <<-EOS
+Cannot save draft for new record without scopeable record.
+Be sure to build draft from #{recordable_type} with a non-nil #{scope_name}.
+      EOS
+    end
+  end
+
+  def scope_name
+    recordable_class && recordable_class.worth_saving_info.scope
+  end
+
+  def scoped_record?
+    recordable_class.worth_saving_info.scope.present?
+  end
+
+  def recordable_class
+    @recordable_class ||= WorthSaving::Info.class_with_name recordable_type
+  end
+
+  def recordable_params
+    params = Rack::Utils.parse_nested_query(form_data)
+    params[recordable_type.underscore]
+  end
+end

data/app/views/layouts/worth_saving/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>WorthSaving</title>
+  <%= stylesheet_link_tag    "worth_saving/application", :media => "all" %>
+  <%= javascript_include_tag "worth_saving/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,3 @@
+WorthSaving::Engine.routes.draw do
+  resources :drafts, only: [:create, :update, :index]
+end

data/db/migrate/20130911055236_create_worth_saving_drafts.rb

@@ -0,0 +1,16 @@
+class CreateWorthSavingDrafts < ActiveRecord::Migration
+  def change
+    create_table :worth_saving_drafts do |t|
+      t.integer :recordable_id
+      t.string  :recordable_type
+      t.integer :scopeable_id
+      t.string  :scopeable_type
+      t.text    :form_data
+
+      t.timestamps
+    end
+
+    add_index :worth_saving_drafts, [:recordable_id, :recordable_type], name: :worth_saving_draft_recordable_index
+    add_index :worth_saving_drafts, [:recordable_type, :scopeable_id, :scopeable_type], name: :worth_saving_draft_scopeable_index
+  end
+end

data/lib/tasks/worth_saving_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :worth_saving do
+#   # Task goes here
+# end

data/lib/worth_saving.rb

@@ -0,0 +1,12 @@
+require "worth_saving/engine"
+require 'worth_saving/info'
+require 'worth_saving/active_record_ext'
+require 'worth_saving/form_builder'
+require 'worth_saving/form'
+require 'worth_saving/action_view_ext'
+
+module WorthSaving
+end
+
+ActiveRecord::Base.send :include, WorthSaving::ActiveRecordExt
+ActionView::Base.send :include, WorthSaving::ActionViewExt

data/lib/worth_saving/action_view_ext.rb

@@ -0,0 +1,11 @@
+module WorthSaving
+  module ActionViewExt
+    def self.included(base)
+      base.class_eval do
+        def worth_saving_form_for(record, options = {}, &proc)
+          WorthSaving::Form::Base.new(self, record, options, &proc).render
+        end
+      end
+    end
+  end
+end

data/lib/worth_saving/active_record_ext.rb

@@ -0,0 +1,39 @@
+module WorthSaving
+  module ActiveRecordExt
+    def self.included(base)
+      base.extend ClassMethods
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods
+      def is_worth_saving(opts = {})
+        class_eval do
+          has_one :worth_saving_draft, class_name: 'WorthSaving::Draft', as: :recordable
+          before_save :destroy_worth_saving_draft
+
+          @worth_saving_info = WorthSaving::Info.new self, opts
+
+          def self.worth_saving_info
+            @worth_saving_info
+          end
+
+          private
+
+          def destroy_worth_saving_draft
+            worth_saving_draft && worth_saving_draft.destroy
+          end
+        end
+      end
+
+      def worth_saving?(field_name = nil)
+        respond_to?(:worth_saving_info) && worth_saving_info.saves_field?(field_name)
+      end
+    end
+
+    module InstanceMethods
+      def worth_saving?(field_name = nil)
+        self.class.worth_saving? field_name
+      end
+    end
+  end
+end

data/lib/worth_saving/engine.rb

@@ -0,0 +1,15 @@
+module WorthSaving
+  class Engine < ::Rails::Engine
+    isolate_namespace WorthSaving
+    config.default_save_interval = 60
+    config.default_recovery_message = <<EOS
+It appears you were working on a draft that didn't get saved.
+It is recommended that you choose one now, as no more draft copies will be saved until you do.
+EOS
+  end
+
+  def self.configure(&block)
+    yield Engine.config if block
+    Engine.config
+  end
+end

data/lib/worth_saving/form.rb

@@ -0,0 +1,15 @@
+require 'worth_saving/form/record'
+require 'worth_saving/form/rendering'
+require 'worth_saving/form/base'
+
+module WorthSaving
+  module Form
+    WORTH_SAVING_DRAFT_FORM_BLOCK = proc { |f|
+      f.hidden_field(:recordable_id) +
+      f.hidden_field(:recordable_type) +
+      f.hidden_field(:scopeable_id) +
+      f.hidden_field(:scopeable_type) +
+      f.hidden_field(:form_data)
+    }
+  end
+end