Skip to content
Permalink
Browse files

doc: Merge/update old TimedObserver docs into source [prototypejs#134

…state:fixed_in_branch]
  • Loading branch information...
Tim Walker authored and samleb committed Feb 7, 2010
1 parent 43c2e6c commit 6a1e11fa34a4e0c7b9c4002826d44ca611bef4b1
Showing with 84 additions and 16 deletions.
  1. +84 −16 src/dom/form.js
@@ -580,19 +580,42 @@ Form.Element.Serializers = {
/**
* class Abstract.TimedObserver
*
* An abstract DOM element observer class, subclasses of which can be used to periodically
* check a value and trigger a callback when the value has changed.
* An abstract DOM element observer class, subclasses of which can be used to
* periodically check a value and trigger a callback when the value has changed.
*
* A `TimedObserver` object will try to check a value using the `getValue()`
* instance method which must be defined by the subclass. There are two out-of-the-box subclasses:
* [[Form.Observer]], which serializes a form and triggers when the result has changed; and
* [[Form.Element.Observer]], which triggers when the value of a given form field changes.
* instance method which must be defined by the subclass. There are two
* out-of-the-box subclasses:
* [[Form.Observer]], which serializes a form and triggers when the result has
* changed; and [[Form.Element.Observer]], which triggers when the value of a
* given form field changes.
*
* <h5>Creating Your Own TimedObserver Implementations</h5>
*
* Using `TimedObserver` implementations is straightforward; simply instantiate
* them with appropriate arguments. For example:
*
* new Form.Element.Observer(
* 'myelement',
* 0.2, // 200 milliseconds
* function(el, value){
* alert('The form control has changed value to: ' + value)
* }
* )
*
* Now that we have instantiated an object, it will check the value of the form
* control every 0.2 seconds and alert us of any change. While it is useless to
* alert the user of his own input (like in the example), we could be doing
* something useful like updating a certain part of the UI or informing the
* application on server of stuff happening (over Ajax).
*
* The callback function is always called with 2 arguments: the element given
* when the observer instance was made and the actual value that has changed
* and caused the callback to be triggered in the first place.
* #####Creating Your Own TimedObserver Implementations
*
* It's easy to create your own `TimedObserver` implementations: Simply subclass `TimedObserver`
* and provide the `getValue()` method. For example, this is the complete source code for
* [[Form.Element.Observer]]:
* It's easy to create your own `TimedObserver` implementations: Simply subclass
* `TimedObserver` and provide the `getValue()` method. For example, this is the
* complete source code for [[Form.Element.Observer]]:
*
* Form.Element.Observer = Class.create(Abstract.TimedObserver, {
* getValue: function() {
@@ -629,10 +652,15 @@ Abstract.TimedObserver = Class.create(PeriodicalExecuter, {
/**
* class Form.Element.Observer < Abstract.TimedObserver
*
* An [[Abstract.TimedObserver]] subclass that watches for changes to a form field's value.
* This triggers the callback when the form field's value (according to
* [[Form.Element#getValue]]) changes. (Note that when the value actually changes can vary from
* browser to browser, particularly with `select` boxes.)
* An [[Abstract.TimedObserver]] subclass that watches for changes to a form
* field's value. This triggers the callback when the form field's value
* (according to [[Form.Element.getValue]]) changes. (Note that when the value
* actually changes can vary from browser to browser, particularly with
* `select` boxes.)
*
* Form.Element observer implements the `getValue()` method using
* [[Form.Element.getValue]] on the given element. See [[Abstract.TimedObserver]]
* for general documentation on timed observers.
**/
Form.Element.Observer = Class.create(Abstract.TimedObserver, {
/**
@@ -653,9 +681,49 @@ Form.Element.Observer = Class.create(Abstract.TimedObserver, {
* class Form.Observer < Abstract.TimedObserver
*
* An [[Abstract.TimedObserver]] subclass that watches for changes to a form.
* The callback is triggered when the form changes&nbsp;&mdash; e.g., when any of its fields' values
* changes, when fields are added/removed, etc.; anything that affects the serialized
* form of the form (see [[Form#serialize]]).
* The callback is triggered when the form changes&nbsp;&mdash; e.g., when any
* of its fields' values changes, when fields are added/removed, etc.; anything
* that affects the serialized form of the form (see [[Form#serialize]]).
*
* ##### Example
*
* In this example an `observer` is used to change the appearance of the form
* if any of the values had been changed. It returns to its initial state when
* the data is submitted (saved).
*
* <form id="example" action="#">
* <fieldset>
* <legend>Login Preferences</legend>
* <p id="msg" class="message">Current settings:</p>
* <p>
* <label for="greeting">Greeting message</label>
* <input id="greeting" type="text" name="greeting" value="Hello world!" />
* </p>
* <h4>Login options</h4>
* <p>
* <input id="login-visible" type="checkbox" name="login-visible" checked="checked" />
* <label for="login-visible">allow others to see my last login date</label>
* </p>
* <p>
* <input id="land-recent" type="checkbox" name="land-recent" />
* <label for="land-recent">land on recent changes overview instead of the Dashboard</label>
* </p>
* <input type="submit" value="save" />
* </fieldset>
* </form>
*
* <script type="text/javascript">
* new Form.Observer('example', 0.3, function(form, value){
* $('msg').update('Your preferences have changed. Resubmit to save').style.color = 'red'
* form.down().setStyle({ background:'lemonchiffon', borderColor:'red' })
* })
*
* $('example').onsubmit = function() {
* $('msg').update('Preferences saved!').style.color = 'green'
* this.down().setStyle({ background:null, borderColor:null })
* return false
* }
* </script>
**/
Form.Observer = Class.create(Abstract.TimedObserver, {
/**

0 comments on commit 6a1e11f

Please sign in to comment.
You can’t perform that action at this time.