== 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
{{{
<div class='phrase'>
      <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[attribute_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
* 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 https://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

Copyright (c) 2012 Blazing Cloud. See LICENSE.txt for
further details.