RubyGems - effective_regions - Versions diffs - 1.0.0 - Mend

effective_regions 1.0.0

Files changed (63) hide show

checksums.yaml +7 -0
data/MIT-LICENSE +20 -0
data/README.md +580 -0
data/Rakefile +23 -0
data/app/assets/images/effective/templates/image_and_title.png +0 -0
data/app/assets/javascripts/effective/snippets/current_user_info.js.coffee +24 -0
data/app/controllers/effective/regions_controller.rb +154 -0
data/app/helpers/effective_regions_helper.rb +108 -0
data/app/models/concerns/acts_as_regionable.rb +34 -0
data/app/models/effective/access_denied.rb +17 -0
data/app/models/effective/region.rb +44 -0
data/app/models/effective/snippets/current_user_info.rb +12 -0
data/app/models/effective/snippets/snippet.rb +69 -0
data/app/models/effective/templates/image_and_title.rb +13 -0
data/app/models/effective/templates/template.rb +26 -0
data/app/views/effective/snippets/_current_user_info.html.haml +10 -0
data/app/views/effective/templates/_image_and_title.html.haml +5 -0
data/config/routes.rb +19 -0
data/db/migrate/01_create_effective_regions.rb.erb +23 -0
data/lib/effective_regions.rb +57 -0
data/lib/effective_regions/engine.rb +27 -0
data/lib/effective_regions/version.rb +3 -0
data/lib/generators/effective_regions/install_generator.rb +32 -0
data/lib/generators/templates/README +1 -0
data/lib/generators/templates/effective_regions.rb +71 -0
data/lib/tasks/effective_regions_tasks.rake +4 -0
data/spec/dummy/README.rdoc +261 -0
data/spec/dummy/Rakefile +7 -0
data/spec/dummy/app/assets/javascripts/application.js +15 -0
data/spec/dummy/app/assets/stylesheets/application.css +13 -0
data/spec/dummy/app/controllers/application_controller.rb +3 -0
data/spec/dummy/app/helpers/application_helper.rb +2 -0
data/spec/dummy/app/views/layouts/application.html.erb +14 -0
data/spec/dummy/config.ru +4 -0
data/spec/dummy/config/application.rb +59 -0
data/spec/dummy/config/boot.rb +10 -0
data/spec/dummy/config/database.yml +25 -0
data/spec/dummy/config/environment.rb +5 -0
data/spec/dummy/config/environments/development.rb +37 -0
data/spec/dummy/config/environments/production.rb +67 -0
data/spec/dummy/config/environments/test.rb +37 -0
data/spec/dummy/config/initializers/backtrace_silencers.rb +7 -0
data/spec/dummy/config/initializers/inflections.rb +15 -0
data/spec/dummy/config/initializers/mime_types.rb +5 -0
data/spec/dummy/config/initializers/secret_token.rb +7 -0
data/spec/dummy/config/initializers/session_store.rb +8 -0
data/spec/dummy/config/initializers/wrap_parameters.rb +14 -0
data/spec/dummy/config/locales/en.yml +5 -0
data/spec/dummy/config/routes.rb +58 -0
data/spec/dummy/db/development.sqlite3 +0 -0
data/spec/dummy/db/schema.rb +16 -0
data/spec/dummy/db/test.sqlite3 +0 -0
data/spec/dummy/log/development.log +20 -0
data/spec/dummy/log/test.log +2 -0
data/spec/dummy/public/404.html +26 -0
data/spec/dummy/public/422.html +26 -0
data/spec/dummy/public/500.html +25 -0
data/spec/dummy/public/favicon.ico +0 -0
data/spec/dummy/script/rails +6 -0
data/spec/effective_regions_spec.rb +7 -0
data/spec/spec_helper.rb +34 -0
data/spec/support/factories.rb +1 -0
metadata +199 -0

checksums.yaml ADDED

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3da3a25db0858892dedca323cbf867a7e9017961
+  data.tar.gz: c9ddf036366111755f3af12e9a748600256289b8
+SHA512:
+  metadata.gz: a72c5adc99f5cdc4711514efdcb461356962f97d51ee25496575b81798eaf750a7e27bf21eee61317375992e243f84af3cb9d041c19059be8b19717481f777ff
+  data.tar.gz: d57234452b3c5881ed25ba0c96edb822ba709c2ae862d1133a960035ce8d09c9ef8db1e9fafcb65b87f724d945e7576ea73ca659ffe82aa1ed92788fe2154735

data/MIT-LICENSE ADDED

@@ -0,0 +1,20 @@
+Copyright 2014 Code and Effect Inc.
+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 ADDED

@@ -0,0 +1,580 @@
+# Effective Regions
+Create editable content regions within your existing, ordinary ActionView::Base views, and update content with an actually-good full-screen WYSIWYG editor.
+Define and Insert Snippets (mini model-view components) that intelligently render content based on the user selected attributes.
+Specify and Insert pre-defined HTML-only templates for small pieces of common HTML.
+Uses the actually-good fullscreen editor [effective_ckeditor](https://github.com/code-and-effect/effective_ckeditor) to achieve near perfect WYSIWYG editting of content regions.
+## Getting Started
+Add to your Gemfile:
+```ruby
+gem 'effective_regions'
+```
+Run the bundle command to install it:
+```console
+bundle install
+```
+Then run the generator:
+```ruby
+rails generate effective_regions:install
+```
+The generator will install an initializer which describes all configuration options and creates a database migration.
+If you want to tweak the database table name (to use something other than the default 'regions'), manually adjust both the configuration file and the migration now.
+Then migrate the database:
+```ruby
+rake db:migrate
+```
+Add the following helper to your application layout in the `<head>..</head>` section.  This will have the effect of loading the appropriate javascript & stylesheets only when in 'edit mode'.
+```ruby
+effective_regions_include_tags
+```
+Do not add anything to your asset pipeline javascripts or stylesheets.
+## Usage
+### Regions
+Regions can be global, in which each is referenced by a unique name, or belong to a specific object.
+If desired, permissions can be configured such that some users may edit global regions but not object regions or vice versa.
+The regions can be created with or without default content.  The default content is displayed only when no editable content has been entered.
+The names for the regions are to be created on the fly, so you can just make up new names as you go along.
+It's super easy to add an effective_region into any regular view, anywhere you want a dynamic content area.
+The following is an example of a global region:
+```ruby
+%h2 This is a header
+%p= effective_region :footer_left
+```
+and another example of the same region with some default content:
+```ruby
+%h2 This is a header
+%p
+  = effective_region :footer_left do
+    %p Default content
+    %p to display when footer_left is empty
+```
+Anywhere in your application, in any layout or view, refering to `:footer_left` will render the same piece of content.
+Effective Regions can also belong to a specific object:
+```ruby
+%h2= effective_region(@event, :title)
+%p
+  = effective_region @event, :summary do
+    %p= truncate(@event.excerpt)
+    %small
+      created on
+      = @event.created_at
+%p= effective_region(@event, :body)
+```
+Here each `@event` will have a unique `:title`, `:summary` and `:body` regions.
+### Restricting Editable Content
+Using a regular `effective_region` tells the full-screen editor that any kind of HTML content and all available Snippets are allowed.
+This is not always desirable - sometimes you want to lock down the content available to a specific region.
+To allow text-only entry with no HTML or snippets, use `simple_effective_region`:
+```haml
+%h2
+  = simple_effective_region @event, :title do
+    Default Title
+```
+The above example ensures that the full-screen editor will only accept a simple title.  No HTML is allowed. No Snippets are allowed.  No newlines or ENTER keypresses are allowed.
+This gives the user full control of the content, and allows the design and presentation to remain entirely in the hands of the developer.
+Similarly, you may want to allow only Snippets to be inserted into a specific region:
+```haml
+%div
+  = snippet_effective_region :sidebar_mentions
+```
+only one type of snippet to be allowed:
+```haml
+%div
+  = snippet_effective_region(:sidebar_mentions, :snippets => [:mention])
+```
+or allow full content entry, but only a subset of the available Snippets:
+```haml
+%div
+  = effective_region(:sidebar_mentions, :snippets => [:mention])
+```
+### Before Save Callback
+Sometimes you may want to programmatically massage the content being assigned from the editor.
+One use case for this would be to replace a tweet `@someone` mention with a full url to the appropriate twitter page.
+Found in the `config/initializers/effective_regions.rb` file, the `config.before_save_method` hook exists for just such a purpose.
+This method is called when a User clicks the 'Save' button in the full screen editor.
+It will be called once for each region immediately before the regions are saved to the database.
+This is not an ActiveRecord `before_save` callback and there is no way to cancel the save.
+This method is run on the `controller.view_context`, so you have access to all your regular view helpers as well as the `request` object.
+The second argument, `parent`, will be the `Effective::Region`'s parent `regionable` object, or the symbol `:global`.
+If you are gsub'ing the `region.content` String value or altering the `region.snippets` Hash values, those changes will not be immediately visible on the front-end.
+If you need the User to immediately see these changes, have your Proc or function return the symbol `:refresh`.
+Returning the symbol `:refresh` will instruct javascript to perform a full page refresh after the Save is complete.
+Warning: Don't change the `region.title` value or the `region.regionable` parent object, as this will just orphan the region.
+Use via Proc:
+```ruby
+config.before_save_method = Proc.new do |region, parent|
+  region.content = region.content.gsub('force', 'horse') if region.title == 'body'
+  :refresh
+end
+```
+or to use via custom method:
+```ruby
+config.before_save_method = :my_region_before_save_method
+```
+And then in your application_controller.rb:
+```ruby
+def my_region_before_save_method(region, parent)
+  if region.title == 'body' && request.fullpath == posts_path
+    region.content = region.content.gsub('force', 'horse')
+    :refresh
+  end
+end
+```
+or to disable completely:
+```ruby
+config.before_save_method = false
+```
+## Authorization
+All authorization checks are handled via the config.authorization_method found in the effective_regions.rb initializer.
+It is intended for flow through to CanCan, but that is not required.
+The authorization method can be defined as:
+```ruby
+EffectiveRegions.setup do |config|
+  config.authorization_method = Proc.new { |controller, action, resource| can?(action, resource) }
+end
+```
+or as a method:
+```ruby
+EffectiveRegions.setup do |config|
+  config.authorization_method = :authorize_effective_regions
+end
+```
+and then in your application_controller.rb:
+```ruby
+def authorize_effective_regions(action, resource)
+  can?(action, resource)
+end
+```
+There are 3 different levels of permissions to be considered:
+1 - Can I use the editor at all?
+can :edit, Effective::Region
+2 - Can I update the Effective::Region global regions?
+can :update, Effective::Region
+3 - Can I update the individual objects which define `acts_as_regionable`
+can :update, ActsAsRegionableObject  # This would be your Event, Post, or Page, or whatever.
+If the method or proc returns false (user is not authorized) an `Effective::AccessDenied` exception will be raised
+You can rescue from this exception by adding the following to your application_controller.rb
+```ruby
+rescue_from Effective::AccessDenied do |exception|
+  respond_to do |format|
+    format.html { render 'static_pages/access_denied', :status => 403 }
+    format.any { render :text => 'Access Denied', :status => 403 }
+  end
+end
+```
+## Snippets
+Snippets are intelligent pieces of content that can be dropped into an effective_region through the full-screen editor's 'Insert Snippet' dropdown.
+They are based on [CKEditor Widgets](http://docs.ckeditor.com/#!/guide/dev_widgets) but override some of the Widget internals to instead use the server to render content, allowing us to render Rails objects based on the user selected options.
+To implement a Snippet, you must write 3 files: a model, a view, and a javascript options file.
+## Simple Snippet Example
+We are going to create a Snippet called `current_user_info`.
+When the snippet is inserted, the user may choose whether the `.email`, `.first_name` or `.last_name` methods will be called on the `current_user` object.
+These examples use HAML, but ERB or SLIM will work the same way.
+### The Model
+A model that extends from `Effective::Snippets::Snippet`
+Any snippet models defined in app/models/effective/snippets/*.rb will be automatically detected and usable.
+The models here are not ActiveRecord objects, and instead rely on [virtus](https://github.com/solnic/virtus) for the `attribute` functionality.
+Any number of configurable options can be specified, but in this example we only have one.
+This model file is defined in app/models/effective/snippets/current_user_info.rb
+```ruby
+module Effective
+  module Snippets
+    class CurrentUserInfo < Snippet
+      attribute :display_method, String
+    end
+  end
+end
+```
+### The View
+The view must be defined as a partial and should be placed in app/views/effective/snippets/_current_user_info.html.haml
+```haml
+- if current_user.blank?
+  = 'Not logged in'
+- elsif current_user_info.display_method == 'email'
+  = current_user.email
+- elsif current_user_info.display_method == 'first_name'
+  = current_user.first_name
+- elsif current_user_info.display_method == 'last_name'
+  = current_user.last_name
+```
+Or for the meta-programmers, instead of the above, we could:
+```haml
+= (current_user.send(current_user_info.display_method) rescue 'Not logged in')
+```
+In the above example, `current_user_info` is the snippet object, and `current_user` is the (probably Devise) User object.
+### The Javascript Options File
+This file defines the dialog that CKEditor will present when inserting a new Snippet.
+This must follow the CKEditor Widget Dialog Window Definition specification, which you can learn more about at:
+http://docs.ckeditor.com/#!/guide/widget_sdk_tutorial_2
+http://docs.ckeditor.com/#!/api/CKEDITOR.dialog.definition
+The javascript file must be placed in app/assets/javascripts/effective/snippets/current_user_info.js.coffee
+```Coffeescript
+CKEDITOR.dialog.add 'current_user_info', (editor) ->  # Must match the class name of the snippet
+  title: 'Current User Info',
+  minWidth: 200,
+  minHeight: 100,
+  contents: [
+    {
+      id: 'current_user_info',    # Just an html id, doesn't really matter what is here
+      elements: [
+        {                         # elements Array should contain one Hash for each Snippet attribute
+          id: 'display_method',
+          type: 'select',
+          label: 'Current User Info',
+          items: [
+            ['E-mail', 'email'],
+            ['First Name', 'first_name'],
+            ['Last Name', 'last_name']
+          ],
+          setup: (widget) -> this.setValue(widget.data.display_method),
+          commit: (widget) -> widget.setData('display_method', this.getValue())
+        }
+      ]
+    }
+  ]
+```
+Please note, this file should not be included into the asset pipeline.  It's a standalone javascript file that is read (just once, and then cached) by CKEditor when the Insert Snippet is triggered.
+You may be thinking that this file won't be available due to asset digesting, but there is a custom `assets:precompile` enhancement task in the [effective_ckeditor](https://github.com/code-and-effect/effective_ckeditor) gem (a dependency of this gem) that ensures these snippet options files are available at the non-digested file path.  This just works and is not something you need to worry about.
+### Summary
+We have created a simple Snippet to display the current_user's email, first_name or last_name.
+When any logged in user visits this page, their specific instance of current_user will be called, and they will see their own email, first or last name.
+Once the Snippet is inserted, the user editting the page can double-click the Snippet and set the display_method to something else.
+## Advanced Snippet Example
+The above, simple, example works great because `current_user` is something always available to the application.
+In this next example we are going to create a Snippet to insert a summary and link to a `Post` which is created using the standard Rails CRUD workflow.
+We must use an AJAX request to query all current Posts, rather than just the ones available at compile/deploy time.
+### The Model
+This snippet model is defined in app/models/effective/snippets/post.rb
+```ruby
+module Effective
+  module Snippets
+    class Post < Snippet
+      attribute :post_id, Integer
+      def post_object
+        # We're using ::Post to refer to the app/models/post.rb rather than the Effective::Snippets::Post
+        @post ||= ::Post.find_by_id(post_id)
+      end
+    end
+  end
+end
+```
+### The View
+This view partial is defined in app/views/effective/snippets/_post.html.haml
+Some advanced snippet partials work best with CKEditor when you can start them with a parent div.  This one isn't advanced enough to actually matter.
+```haml
+.post
+  %h3= post.post_object.title
+  %small
+    This is post number
+    = post.post_object.id
+    created on
+    = post.created_at
+  %p= post.post_object.summary
+```
+### The Javascript Options File
+The javascript file should be placed in app/assets/javascripts/effective/snippets/post.js.coffee
+```Coffeescript
+getPosts = ->
+  posts = []
+  $.ajax
+    url: '/effective/snippets/posts'
+    type: 'GET'
+    dataType: 'json'
+    async: false
+    complete: (data) -> posts = data.responseJSON
+  posts
+CKEDITOR.dialog.add 'post', (editor) ->
+  title: 'Post'
+  minWidth: 200,
+  minHeight: 100,
+  contents: [
+    {
+      id: 'post',
+      elements: [
+        {
+          id: 'post_id',
+          type: 'select',
+          label: 'Post',
+          items: getPosts(),  # This only runs once, when the Dialog is created.
+          setup: (widget) -> this.setValue(widget.data.post_id)
+          commit: (widget) -> widget.setData('post_id', this.getValue())
+        }
+      ]
+    }
+  ]
+```
+So when the Snippet dialog for an 'Insert Snippet' -> Post is opened, an AJAX request to the server is made, and the list of Posts is read.
+### The Controller
+This controller is in no way part of the effective_regions/effective_ckeditor magic.  It's just a one-off controller action.
+For consistency with the other file paths (which do matter), I have namespaced the action under effective/snippets/, but this could be any valid rails route.
+This controller is defined in app/controllers/effective/snippets/posts_controller.rb
+```ruby
+module Effective
+  module Snippets
+    class PostsController < ApplicationController
+      respond_to :json
+      def index
+        authorize! :index, Post  # CanCan authorization here
+        @posts = Post.order(:title).map { |post| [post.title, post.id] }.to_json
+        respond_with @posts
+      end
+    end
+  end
+end
+```
+and then in your routes.rb:
+```ruby
+get '/effective/snippets/posts', :to => 'effective/snippets/posts#index'
+```
+### Default Content
+We can pre-populate an effective_region's default content with some posts.  These posts will be displayed until a user edits that region and selects some specific posts.
+```haml
+%h2 Posts
+= snippet_effective_region :sidebar_posts, :snippets => [:post] do
+  - Post.order(:created_at).first(5).each do |post|
+    = render_snippet Effective::Snippets::Post.new(:post_id => post.id)
+```
+### Summary
+This Snippet makes an AJAX request to the server and receives a JSON response containing all the Posts.  The Posts are displayed in a select drop-down, and when one is chosen, inserted into the given region.
+## Templates
+Templates are small pieces of reusable HTML that can be inserted into an `effective_region` with just one or two clicks.
+Unlike snippets, there are no configurable options or anything.  They're just pieces of raw HTML that can be dropped in and then immediately editted.
+While handy, they were implemented as a bit of an after-thought, and will probably be refactored in future versions of effective_regions.
+They take the form of two files, a model and a view.
+### The Model
+A model extends from `Effective::Templates::Template`
+Any template models defined in app/models/effective/templates/*.rb will be automatically detected and usable.
+The model here is very minimalistic.  It's basically just to inform the full-screen editor that a View with the same name exists.
+This model is defined at app/models/effective/templates/two_column.rb
+```ruby
+module Effective
+  module Templates
+    class TwoColumn < Template
+      def description
+        'Two Column Area'
+      end
+    end
+  end
+end
+```
+### The View
+The view is defined at app/models/effective/templates/_two_column.html.haml
+```haml
+.row
+  .col-sm-6
+    %p Left Column
+  .col-sm-6
+    %p Right column
+```
+## License
+MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+Code and Effect is the product arm of [AgileStyle](http://www.agilestyle.com/), an Edmonton-based shop that specializes in building custom web applications with Ruby on Rails.
+## Testing
+The test suite for this gem is unfortunately not yet complete.
+Run tests by:
+```ruby
+rake spec
+```
+## Contributing
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request