sisyphus-rails/README.md

Sisyphus::Rails

A gem to add gmail like form saving through sisyphus.js

Installation

Add this line to your application's Gemfile:

gem 'sisyphus-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install sisyphus-rails

For a basic install include the following in your app/assets/javascripts/application.js file

//= require sisyphus

To support IE6/7 users include jStorage as well

//= require jstorage
//= require sisyphus

Create a Configuration File

You can use the built in generator to create a basic sisyphus.yml configuration file.

$ rails generate sisyphus:configuration

The file will be placed in config/

How it Works

Sisyphus uses an aliased form_tag method to automatically put a <script>...</script> tag infront of your forms to initialize Sisyphus. It also uses an aliased FormHelper form_for method to read options.

<script>$(document).ready(function() {$('#sampleform').sisyphus();});</script>
<form id="sampleform">
  ...
</form>

Usage

Sisyphus automatically works with all your forms, including custom form builders.

Exclude a form

To stop Sisyphus from initializing on a form include the with_sisyphus option in your form_for.

<%= form_for User.new, :with_sisyphus=>false do |f| %>
  ...
<% end %>

Exclude/Include a model

To exclude or include a specific model you can enter it in your ENV or the sisyphus.yml file. The configuration takes a comma (,) separated string of lower case model names.

exclude_models: user
include_models: comment,post

Include/Exclude everything

You can also set the sisyphus_enabled option to true/false in your ENV or the sisyphus.yml file to turn Sisyphus on or off by default.

sisyphus_enabled: false

Putting the switches together

The switches work together to see if a form should be protected by Sisyphus or not. The sisyphus_enabled switch will be used if no other switches are set. If the model is specifically excluded (when sisyphus_enabled = true) then it will not be protected. Conversley, if the model is specifically included and sisyphus_enabled = false it will be protected. The final say is taken by the form option. If with_sysphus is set it's value will be used to determine if the form should be protected or not.

Dependencies

• Rails >= 3.1
• Jquery 1.8+

TODO

• Tests

• Move away from form_tag_helper, should be able to do it all from form_helper? Script tag can go at the end anyhow. Why aren't we doing that right now? We don't seem to have access to the same variables that the regular form_for does. Also the options array gets muddied by the FormHelper form_for call -> it removes the [:html] section (we need the id of the form for sisyphus).

• conflict resolution... i.e. you have an object edit form, the fields are populated from the DB but if you have local browser changes they may get overridden. We need a way to resolve conflicts between local and remote data -> could use a jquery based modal dialog to present the diff?

• Model based exclusions/options via activerecord extension? We have config based exclude/includes now

• block based options (this would allow us to easily and neatly implement Sisyphus options)

  <%= form_for User.new do |f| %> <% :sisyphus => flase %> <% :sisyphus_customKeyPrefix => 'sisy' %> ... <% end %>

• implement all sisyphus options and any relevant ones in jStorage

Contributing

If you have time to tackle something off the TODO list before I manage to get around to it then please do!

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. Create new Pull Request

Included Libraries

https://github.com/rails/jquery-rails https://github.com/simsalabim/sisyphus https://github.com/andris9/jStorage

Resources

http://coding.smashingmagazine.com/2011/12/05/sisyphus-js-client-side-drafts-and-more/