on_the_spot¶ ↑
On-the-spot is a Rails3+ compliant unobtrusive javascript in-place-editing plugin, using jEditable, and depends on jQuery.
Features¶ ↑
-
built on proven jQuery plugin
jEditable
-
works on index-pages, nested objects, …
-
can generate simple edit-boxes, textareas, dropdown lists, checkboxes
-
will check your server-side validations and show the error
-
you can check the access-rights before doing any update (to check against tampering)
-
you can use custom display methods, e.g when using markdown
Installation¶ ↑
Inside your Gemfile
add the following:
gem "on_the_spot"
Run the installation task:
rails g on_the_spot:install
This will copy the default translation files, and for rails 3.0 it will also copy the needed assets (javascript files).
Rails 6¶ ↑
Add the componanion package
yarn add @nathanvda/on_the_spot
and then in your app/javascripts/packs/application.js
you should add
require("jquery") require("jquery-jeditable") require("@nathanvda/on_the_spot")
Rails 3.1+/4/5¶ ↑
Add the following to application.js so it compiles to the asset_pipeline
//= require on_the_spot
Or, inside your application.html.haml
you could still include the needed javascripts, using
= javascript_include_tag :on_the_spot
To use the default styling, add the following to application.css
so it compiles to the asset_pipeline
*= require on_the_spot
Or, inside your application.html.haml
you could still include the needed css, using
= stylesheet_link_tag :on_the_spot
Rails 3.x¶ ↑
Breaking changes: since rails 5 render :text is deprecated and removed, this means that starting from 1.1.0 this gem is no longer compatible with rails 3, but is compatible with rails 4 and 5. So if you are still using rails 3.x you need the fixate the version to
1.0.6
gem 'on_the_spot', '1.0.6'
Rails 3.0.x¶ ↑
Inside your application.html.haml
you will need to add below the default javascripts:
= javascript_include_tag :on_the_spot
or using erb, you write
<%= javascript_include_tag :on_the_spot %>
To use the default styling, inside your application.html.haml
you will need to add below the default CSS:
= stylesheet_link_tag :on_the_spot
or using erb, you write
<%= stylesheet_link_tag :on_the_spot %>
Routes (for all Rails versions)¶ ↑
Inside your routes.rb
you need to provide the following route :
resources :posts do collection do put :update_attribute_on_the_spot get :get_attribute_on_the_spot end end
You need to do this for each controller that uses the on-the-spot editing.
You only need to specify the route for get_attribute_on_the_spot
if you make use of the :display_method
option, and do not want to supply your own load-function.
That is all you need to do to start using it!
Usage¶ ↑
Inside your controller you write:
class YourController < ApplicationController can_edit_on_the_spot ... leave the rest of your controller alone ... end
And inside your view you will have to specify the fields you want to be “editable” :
Username: <%= on_the_spot_edit @user, :name %>
It should be as simple as that :)
Detailed options¶ ↑
The can_edit_on_the_spot
accepts options:
-
:is_allowed
: method-name to call to check if the update is allowed to be performed -
:on_success
: method-name that is called when the update was succesfully performed, this could be used for audit-logging a.o.
The on_the_spot_edit
also accepts options:
-
:type
::textarea
,:select
or:checkbox
(none means default edit) -
:ok_text
: the text for the ok-button -
:cancel_text
: the text for the cancel-button -
:display_text
: if you want to overrule the displayed text, especially useful when using your own:url
or:loadurl
-
:tooltip
: the tooltip-text -
:form_css
: the css class for the form -
:input_css
: the css class for the input itself -
:rows
: for textarea, the number of rows, defaults to 5 -
:columns
: for textarea, the number of columns, defaults to 40 -
:data
: for select, the lookup-data, should be in an array of id-value pairs. E.g.[[1, 'ok'], [2, 'not ok'], [3, 'not decided']]
. -
:loadurl
: for select, an url that will return the data in JSON format (use instead of:data
) -
:url
: URL to post to if you don't want to use the standard routes -
:selected
: Text selected by default on edit (boolean, default is false) -
:callback
: The name of a javascript function that is called after form has been submitted -
:display_method
: the name of a method that is used to get the value to display of a field. When you use this, we will automatically attempt to look up the raw value of the field to edit. This differs from the:display_text
option, as this will also be called after update. This supersedes the:display_text
option. -
:raw
: if set to true, evaluate the field value as raw HTML. -
:onblur
: acceptscancel
,submit
orignore
changes the behavior of the onblur handler accordingly
For the texts and css classes: if a text is not specified, the default is taken from the on_the_spot.en.yml
(or your current language).
E.g. in the translations file on_the_spot.en.yml
you could do the following to get the inline editor look good when using bootstrap:
en: on_the_spot: ok: <button class="btn btn-primary btn-sm">Ok</button> cancel: <button class="btn btn-sm">Cancel</button> tooltip: Click to edit ... access_not_allowed: Access is not allowed form_css: 'form form-inline' input_css: 'form-control'
Styling¶ ↑
Each element that is editable will have the on_the_spot_editing
class.
When an element is moused over, it will get the on_the_spot_over
class.
You can use these classes to style the elements.
Example Usages¶ ↑
Edit field¶ ↑
<%= on_the_spot_edit @user, :name %>
Textarea¶ ↑
<%= on_the_spot_edit @user, :description, :type => :textarea, :rows => 10, :columns => 55 %>
Select-box¶ ↑
<%= on_the_spot_edit @user, :rating, :type => :select, :data => [[1, 'good'], [2, 'mediocre'], [3, 'bad']] %>
Callback¶ ↑
Somewhere in a .js file: function testCallback(object, value, settings) { console.log(object); console.log(value); console.log(settings); } <%= on_the_spot_edit @user, :name, :callback => 'testCallback' %>
Using together with cancan
¶ ↑
When using on_the_spot
together with cancan
, you will have to explicitly exclude the on_the_spot method, like so:
load_and_authorize_resource :except => [:update_attribute_on_the_spot, :get_attribute_on_the_spot]
The load_and_authorize_resource
will try to find the object, based on the id in the parameters, but on_the_spot
uses a different encoding to store the object, field and id in one attribute. So if you exclude that, there will not be a problem.
Using together with an authorization system (e.g. Cancan)¶ ↑
If you want to test access-rights, you can do so by specifying a method which will be called
In your controller write:
can_edit_on_the_spot :check_access def check_access(object, field) # verify that the current user has access to edit/see the field of given object end
Note, there are two identical ways to add this: either you use the old format : can_edit_on_the_spot :method_name
or you could use the new format: can_edit_on_the_spot is_allowed: :check_access
. Both are identical
Performing an action upon succesful update¶ ↑
If you want to perform some action upon succesfully updating a field, you can specify a method to do just that.
In your controller write:
can_edit_on_the_spot on_success: :log_changes protected def log_changes(updated_object, field, value) Rails.logger.debug("We updated #{updated_object.name} and set #{field} to #{value}") end
Example project¶ ↑
There is an example rails3-project called on_the_spot_tester
Prerequisites¶ ↑
As jEditable depends on jQuery, your rails3 project needs to use jQuery. It will not work if you use Prototype instead, in your rails3 project. I have written an article here how to start a fresh rails3 project, using jQuery. In short, you add the following to your Gemfile
:
gem "jquery-rails"
and, after a bundle install
, you run
rails g jquery:install
That will download and install all the necessary files for you.
Note on Patches/Pull Requests¶ ↑
-
Fork the project.
-
Make your feature addition or bug fix.
-
Add tests for it. This is important so I don't break it in a future version unintentionally.
-
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-
Send me a pull request. Bonus points for topic branches.
Copyright¶ ↑
Copyright © 2010 nathanvda. See LICENSE for details.