File: README — Documentation for simple_update

simple_update_field

Rails text field helper for inplace-editing of text with keybindings to move between each simple_update_field.

simple_update_field is implemented internally with jquery

Design Goals

Simple_update_field is designed to extend the browsers behaviour in a un-surprising manner.

Callback Guide

You may wish to be able to change the rules around when to, or when not to do an update.

A callback named 'before_update' is provided - you can install it when you invoke SimpleUpdateField.

For example you may wish to have a confirmation dialog:

var my_confirm_handler = function() {

var input = this
return confirm("Update the database with " + input.value +" ?")

$(document).ready(function() {

SimpleUpdateField('.phrase .text'
                  ,{ 
                     before_update:my_confirm_handler
                  })

})

}}}

Styling Guide

Use CSS as you normaly would along with the following classes

{{{ .editable-input { /*

this is the input that will be created 
on click use this class to change it's style

*/ } }}} {{{ .editable-hover { /*

this is the field that has a mouse-over 
use this to tell the user the field is clickable

*/ }

}}}

It is recommended to put a min-width on the element which contains your editable text. For example - if you use a span - if you remove all the text the element will collapse. Simple Update Field will not take responsiblity for lack of styling such an element as you have the power to adjust this via CSS!

Installation Guide for Rails 3+

If you are using a version of rails before JQuery became the default - please integrate the gem ‘jquery-rails’

In the installation guide you will see the following terms: phrase, PhrasesController, Phrase, text - my examples assume that I am working with a Phrase resource with a :string field named ‘text’. The PhrasesController handles rails rest based resource calls.

Edit your Gemfile to include the following

gem "simple_update_field"

}}

You will need to re-start a running server for the Gemfile change to take effect

View Side

There are 3 custom attributes on a span that will be used. An Example follows

<span editable-resource-attribute="text"
      editable-resource-model="<%=phrase.class.model_name.downcase%>"
      editable-resource-uri="<%=phrase_path(phrase,
                                             :authenticity_token => 
                                              form_authenticity_token)%>"
      class="text">
  <%= phrase.text %>
</span>

</div> }}

The 3 custom attributes are :

## editable-resource-attribute *** this is the name one of the model attributes that you want to change ie : ‘name’, ‘text’, ‘phone_number’ *** this will be used with the editable-resource-model to name the parameter ## editable-resource-model *** this is a lowercase name of the model class that you are planning on changing *** this will be sent to the server as part of the post-variable ie: model_name_here=VALUE ## editable-resource-uri *** this is the destination to send the post-variable that is described by the above. **** you will need to encode CRSF into this path if you are using typical rails protect_from_forgery

Example of all 3 attributes

With resources ‘Animals’ (Model : Animal & Controller : AnimalsController) with the attribute ‘name’ and an instance of Animal ‘animal’

<span editable-resource-attribute="name"
      editable-resource-model="animal"
      editable-resource-uri="<%= animal_path(animal,
                                             :authenticity_token => 
                                              form_authenticity_token)
                              %>"
      class="animal-name">
  <%= animal.name %>
</span>

}}

Resource Side

You will need a controller with an update action written in the typical rails resource-style

## The typical rails resource style tends towards having a the resource payload named by the model and as part of the general request params class PhrasesController < ApplicationController

def update
  Phrase.
    find(params[:id]).
    update_attributes(params[:phrase])
  head :ok # assume success
end

end }}

With an update action in your controller - you will also need a route for it

## edit your config/routes.rb file to specify that there is an update action *** in the example there are only two actions :

resources :phrases, :only => [:index,:update]

}} *** or simply use the default actions :

resources :phrases

}}

The combination of having a resource ‘end-point’, and telling the span what the end point is, and what the model, and attribute are will be enough to save changes to the database.
You can invoke the simple update field by clicking on the text you may wish to add CSS styling for hover to indicate to the user that this is an interactive part of the display

Javascript Integration

There are 2 steps to integration with javascript.

The first step is to modify application.js to include the name of the javascript file

//= require simple_update_field }}

The second step is to invoke the the Simple Update Field on the appropriate elements

** this can be done in application.js aswell or in a new file in the app/assets/javascript directory ** A CSS selector of the jQuery style is assumed. ## For the above Phrase view code this could work : $(document).ready(function() {

SimpleUpdateField('.phrase .text')

) }}} ## For the above Animals view code this could work : $(document).ready(function() {

SimpleUpdateField('.animal-name')

) }}}

Roadmap

form field helper
error handling of ajax call

Recent Changes

IE789 bug : focus() doesn’t work unless it is wrapped in a timeout :(
IE8 bug : $.trim() jquery helper must be used instead of String.trim()
Only one active simple update field at a time, even across select groups
before_update callback - return true to continue , false to stop
Only commit changed fields to the remote-resource-uri
Trim leading and trailng whitespace of entered data or original text data
Have it work for any element without modifying structure (ie needs no wrapper)
Reworked internal Design so that it can work without altering the layout done via css
Left out test harness github.com/blazingcloud/simple_update_field-jasmine-harness

Contributing to simple_update_field

# Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet. # Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it. # Fork the project. # Start a feature/bugfix branch. # Commit and push until you are happy with your contribution. # Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally. # Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Authored by Curtis Schofield

Contributors Judy Tuna Hollin Wilkins