From 7118354c00c6263cad9632aeba53c215c89f9320 Mon Sep 17 00:00:00 2001 From: Kyle Florence Date: Tue, 6 Mar 2012 21:52:51 -0800 Subject: [PATCH] Provide better examples of usage in the README. --- readme.md | 167 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 129 insertions(+), 38 deletions(-) diff --git a/readme.md b/readme.md index a15942f..d9f2a33 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,6 @@ # jQuery.autosave - $("form").autosave({...}); + $("form").autosave(); The jQuery.autosave plugin automatically and unobtrusively saves form data based on a set of critera. Saving can be broken down into a simple five step process: @@ -87,24 +87,70 @@ If you use this plugin as is (without providing any options), this is what you c ## Callbacks -Several of the properties above are composed of **callback methods**. These methods are invoked by the plugin during the autosave process. If an Array of methods is found, they will be invoked in the order they were defined in the Array. Any of the following are valid ways of defining a callback method: - -* **"callbackMethod"** _String_, **{ method: "callbackMethod"[, options: {}] }** _Object_ - Calls a built-in callback method, optionally passing an options object to merge with the default options as defined in the plugin. -* **function() {}** _function_, **{ method: function() {}[, options: {}] }** _Object_ - Calls a custom, user-defined callback method, optionally passing an options object into that function. - -You may also define multiple callback methods for any property by simply putting them into an array. - -## Built-in Callbacks - -There are several built-in callback methods that provide you an easy way to set up the most common saving processes. The names of these methods are detailed below along with the arguments that will be passed in when the methods are invoked. Every callback method is called with the current instance as the context of the keyword _this_ making it easy to call any class property or function from within the callback method. +Callback methods are invoked by the plugin during the autosave process. There are several built-in callback methods that provide you an easy way to set up the most common saving processes, but you can also write your own. + + $("form").autosave({ + + // In all of these cases, "callbackName" refers to any of the callback + // options outlined above (trigger, scope, data, condition, save). + callbacks: { + // The simplest way to use a built-in callback is to pass in the + // method name as a string. Default callback options will be used. + callbackName: "callbackMethod", + + // You may also pass in the method name as a string and provide + // custom options by using an object. + callbackName: { + method: "callbackMethod", + options: { + // ... + } + }, + + // An array of callbacks may also be provided. + callbackName: [ + "callbackMethod1", + { + method: "callbackMethod2", + options: { + // ... + } + } + ], + + // The simplest way to use a custom callback method is to pass + // in a function. The arguments provided to this function vary + // depending on the callback used. + callbackName: function() { + // ... + }, + + // You may also pass in the method and custom options by using + // an object. + callbackName: { + method: function(options) { + // ... + }, + options: { + // ... + } + } + } + }); + +The names of these methods are detailed below along with the arguments that will be passed in when the methods are invoked. If an Array of callback methods is provided, they will be invoked in the order they were defined in the Array. Every callback method is called with the current instance as the context of the keyword _this_ making it easy to call any class property or function from within the callback method. --- ### Triggers - trigger([options]); + $("form").autosave({ + callbacks: { + trigger: function(options) { + // ... + } + } + }); #### Methods @@ -119,7 +165,7 @@ The built-in callback methods for triggering an autosave. #### Arguments -These are the arguments that are passed to triggering callback methods. +These are the arguments that are passed to trigger callback methods. * **options** _Object_ An object of key/value pairs that may be used to configure the callback method. @@ -132,7 +178,15 @@ Trigger methods do not require a return value. ### Scope - scope(options, $inputs); + $("form").autosave({ + callbacks: { + scope: function(options, $inputs) { + // ... + // Must return a jQuery Object. + return $inputs; + } + } + }); #### Methods @@ -147,7 +201,7 @@ The built-in callback methods for narrowing the scope of inputs we will gather d #### Arguments -These are the arguments that are passed to scoping callback methods. +These are the arguments that are passed to scope callback methods. * **options** _Object_ An object of key/value pairs that may be used to configure the callback method. @@ -162,25 +216,37 @@ Scope methods should **return a jQuery object** containing the filtered inputs. ### Data - data(options, $inputs, data); + $("form").autosave({ + callbacks: { + data: function(options, $inputs, formData) { + // ... + // Must return some kind of dataset. + return formData; + } + } + }); #### Methods The built-in callback methods for generating data from the inputs. +* **serialize** + Serializes a set of form elements as a String using jQuery's [.serialize()](http://api.jquery.com/serialize/) function. +* **serializeArray** + Serializes a set of form elements as an Array using jQuery's [.serializeArray()](http://api.jquery.com/serializeArray/) function. * **serializeObject** - Encodes a set of form elements as an object of names and values using Ben Alman's [.serializeObject()](http://benalman.com/projects/jquery-misc-plugins/#serializeobject) function. + Serializes a set of form elements as an Object of names and values using Ben Alman's [.serializeObject()](http://benalman.com/projects/jquery-misc-plugins/#serializeobject) function. #### Arguments -These are the arguments that are passed to scoping callback methods. +These are the arguments that are passed to data callback methods. * **options** _Object_ An object of key/value pairs that may be used to configure the callback method. * **$inputs** _jQuery_ A jQuery object containing the current scope of inputs. -* **data** _String, Object, Array_ - Any data that has already been created from the inputs. +* **formData** _String, Object, Array_ + Any data that has already been generated from previous data methods, or undefined if none have been called. #### Return Value @@ -190,7 +256,16 @@ Data methods should **return some kind of dataset**, most likely containing the ### Conditions - condition(options, $inputs, formData[, caller]); + $("form").autosave({ + callbacks: { + condition: function(options, $inputs, formData, caller) { + // ... + // Should return a boolean value. + // Returning boolean 'false' will cancel the save. + return false; + } + } + }); #### Methods @@ -205,14 +280,14 @@ The built-in callback methods for determining whether or not to save. #### Arguments -These are the arguments that are passed to conditional callback methods. +These are the arguments that are passed to condition callback methods. * **options** _Object_ An object of key/value pairs that may be used to configure the callback method. * **$inputs** _jQuery_ A jQuery object containing the current scope of inputs. The inputs given here have already been filtered. -* **data** _Array_ - An array of objects containing the data gathered from the inputs. +* **formData** _String, Array, Object_ + The data gathered from the scoped form elements and returned from the data callback method. * **caller** _String, Number_ Used to denote who called the save method. This is generally undefined, but may contain the ID of the current interval timer or an event name. @@ -224,7 +299,17 @@ Condition methods should **return a Boolean value (true or false)**. Returning a ### Save - method(options, data); + $("form").autosave({ + callbacks: { + save: function(options, formData) { + // ... + // If your save function contains asynchronous code, + // you should return a Boolean 'false' here and call + // this.next("save") when your method has finished. + return false; + } + } + }); #### Methods @@ -235,12 +320,12 @@ The built-in callback methods for determining how to save the input data. #### Arguments -These are the arguments that are passed to saving callback methods. +These are the arguments that are passed to save callback methods. * **options** _Object_ An object of key/value pairs that may be used to configure the callback method. Everything supported by the [jQuery.ajax()](http://api.jquery.com/jQuery.ajax/) function is supported here. Additionally, you may pass a function to the `options.data` parameter to allow your callback method to take dynamically generated data (new data will be gathered upon every save attempt). -* **data** _Object_ - The data gathered from the inputs. +* **formData** _Object_ + The data gathered from the scoped form elements and returned from the data callback method. #### Return value @@ -248,13 +333,13 @@ Saving methods do not require a return value. However, **if your callback method ## Events - event(event[, ...]); - For convenience, the plugin automatically binds or fires events on certain elements under certain circumstances. These events are listed below. Some of these events need to be triggered using jQuery's [.triggerHandler()](http://api.jquery.com/triggerHandler/) function on the element the event is bound to. Other events will be fired automatically and may be caught and handled using jQuery's [.bind()](http://api.jquery.com/bind/) function on the element firing the event. The jQuery [Event Object](http://api.jquery.com/category/events/event-object/) will **always** be the first argument passed to handler methods. Also, keep in mind that these events will be [namespaced](http://docs.jquery.com/Namespaced_Events) according to the _namespace_ option above ("autosave" by default). ### Save - save(event, $inputs); + $("form").autosave().bind("save", function(event, $inputs) { + // ... + }).triggerHandler("save"); When triggered, this event will attempt to save form data. @@ -271,7 +356,9 @@ This event is bound to each form autosave is attached to. ### Saved - saved(event); + $("form").autosave().bind("saved", function(event) { + // ... + }); Triggered whenever autosave finishes saving form data. @@ -288,7 +375,9 @@ This event is fired for each form autosave is attached to. ### Changed - changed(event, input); + $("form").autosave().bind("changed", function(event, input) { + // ... + }); Triggered whenever an input value changes ("change" event is fired). @@ -307,7 +396,9 @@ This event is fired on the form containing the input. ### Modified - modified(event, input); + $("form").autosave().bind("modified", function(event, input) { + // ... + }); Triggered whenever an input value is modified ("keyup" event is fired). @@ -346,6 +437,6 @@ Inspired by the jQuery.autosave plugin written by [Raymond Julin](https://github ## License -Copyright (C) 2011 -Kyle Florence, Raymond Julin, Mads Erik Forberg and Simen Graaten. +Copyright (C) 2012 +Kyle Florence, Raymond Julin, Mads Erik Forberg and Simen Graaten. jQuery.autosave is dual licensed under the BSD and MIT licenses. \ No newline at end of file