Permalink
Browse files

Docs! More Specs.

* Also added api.refreshAPI to reset cached results.
* Disabled the ability to pass a method that's already defined.
* Changed the storage value for returned values from filters to be a little more explicit.
  • Loading branch information...
1 parent 3c0a92a commit 2e1877c989d8230422fc2b30ce9cfce4dfa84bbe @anutron committed Apr 13, 2011
Showing with 473 additions and 118 deletions.
  1. +169 −0 Docs/Behavior.API.md
  2. +197 −75 Docs/Behavior.md
  3. +24 −12 README.md
  4. +19 −8 Source/Behavior.API.js
  5. +25 −18 Source/Behavior.js
  6. +15 −3 Specs/Behavior/Behavior.API.Specs.js
  7. +24 −2 Specs/Behavior/Behavior.Specs.js
  8. BIN layers.png
View
@@ -0,0 +1,169 @@
+Class: Behavior.API {#Behavior.API}
+==========================
+
+Provides methods to read values from annotated HTML configured for the [Behavior][] class and its associated [Filters](Behavior.md#Behavior.Filter).
+
+### Syntax
+
+ new Behavior.API(element[, prefix]);
+
+### Arguments
+
+1. element - (*element*) An element you wish to read.
+2. prefix - (*string*; optional) A prefix to all the properties; a namespace.
+
+### Notes
+
+Examples of the HTML expressions evaluated are as follows (all of the following produce the same output*):
+
+ <tag data-filters="Filter1 Filter2" data-Filter1-options="{opt1: 'foo', opt2: 'bar', selector: '.selector'}"> //prefered
+ <tag data-filters="Filter1 Filter2" data-Filter1-options="opt1: 'foo', opt2: 'bar', selector: '.selector'"> //no braces on JSON
+ <tag data-filters="Filter1 Filter2" data-Filter1-options="{opt1: 'foo', opt2: 'bar'}" data-Filter1-selector=".selector">
+ <tag data-filters="Filter1 Filter2" data-Filter1-opt1='foo' data-Filter1-opt2='false' data-Filter1-selector=".selector">
+
+The `-options` value is parsed as JSON first (it's slightly more permissive in that 1: you don't have to wrap it in `{}` just for convenience and 2: you don't have to quote all the names). Values defined here are read as defined allowing you to express arrays, numbers, booleans, etc. Functions / callbacks are generally not used by [Behavior][].
+
+If you attempt to read a value that isn't defined in this options object, the property name is attempted to be read from the property directly (e.g. `data-filtername-prop`). This value is *always* a string unless you specify a type. If a type is specified the value is run through the JSON parser and validated against that type.
+
+Behavior.API Method: get {#Behavior.API:getAs}
+------------------------------------------
+
+Gets a value for the specified name.
+
+### Syntax
+
+ api.get(name[, name, name, name])
+
+### Arguments
+
+1. name - (*string*) The name of the property you wish to retrieve. Pass more than one to get back multiple.
+
+### Example
+
+ var api = new Behavior.API(target, 'foo');
+ api.get('bar'); //returns the value of data-foo-bar or null
+ api.get('bar', 'baz'); //returns {bar: 'value', baz: 'value'}
+
+### Returns
+
+* (*mixed*) Values defined as strings will be returned as strings. Values defined in JSON will be returned as their
+ type is evaluated. When you expect anything other than a string it's better to use [getAs](#Behavior.API:getAs).
+ When more than one name is specified you'll receive an object response with key/value pairs for the name/property values.
+
+Behavior.API Method: getAs {#Behavior.API:getAs}
+------------------------------------------
+
+Gets a value for the specified name and runs it through [JSON.decode][] and verifies that the value is parsed as the specified type (specifically a MooTools Type: [String](http://mootools.net/docs/core/Types/String), [Function](http://mootools.net/docs/core/Types/Function), [Array](http://mootools.net/docs/core/Types/Array), [Date](http://mootools.net/docs/more/Types/Date), etc.).
+
+### Syntax
+
+ api.getAs(Type, name[, defaultValue]);
+
+### Arguments
+
+1. Type - (*Type*) A MooTools Type instance (a function) that the value, when run through [JSON.decode][], should return
+2. name - (*string*) The name of the value to read.
+3. defaultValue - (*mixed*) The value to set if there no value found.
+
+### Example
+
+ var api = new Behavior.API(target, 'foo');
+ api.getAs(Number, 'some-number');
+
+### Returns
+
+* (*mixed*) Either returns the value as the Type you specified, the default (if provided), or undefined.
+
+Behavior.API Method: require {#Behavior.API:require}
+------------------------------------------
+
+Validates that an element has a value set for a given name. Throws an error if the value is not found.
+
+### Syntax
+
+ api.require(name[, name, name]);
+
+### Arguments
+
+1. name - (*string*) The name of the property you wish to require. Pass more than one if needed.
+
+### Example
+
+ var api = new Behavior.API(target, 'foo');
+ api.require('foo'); //throws an error if data-foo-foo is not set
+ api.require('foo', 'bar'); //throws an error if data-foo-foo or data-foo-bar are not set
+
+### Returns
+
+* *object* - the instance of Behavior.API.
+
+Behavior.API Method: requireAs {#Behavior.API:requireAs}
+------------------------------------------
+
+Requires that an element has a value set for a given name that can be parsed into a given type (using [JSON.decode][]). If a value is not present or does not parse to the specified Type an error is thrown.
+
+### Syntax
+
+ api.requireAs(obj);
+
+### Arguments
+
+1. obj - (*object*) a set of name/Type pairs to require.
+
+### Example
+
+ api.requireAs({
+ option1: Number,
+ option2: Boolean
+ });
+
+### Returns
+
+* *object* - the instance of Behavior.API.
+
+Behavior.API Method: setDefault {#Behavior.API:setDefault}
+------------------------------------------
+
+Sets the default values. Note that setting defaults for required properties is not useful.
+
+### Syntax
+
+ api.setDefault(name, value);
+ api.setDefault(obj);
+
+### Arguments
+
+1. name - (*string*) The name of the property you wish to set.
+2. value - (*mixed*) The default value for the given name.
+
+OR
+
+1. obj - (*object*) a set of name/value pairs to use if the element doesn't have values present.
+
+### Example
+
+ api.setDefault('duration', 1000);
+ api.setDefault({
+ duration: 1000,
+ link: 'chain'
+ });
+
+### Returns
+
+* *object* - the instance of Behavior.API.
+
+Behavior.API Method: refreshAPI {#Behavior.API:refreshAPI}
+------------------------------------------
+
+The API class caches values read from the element to avoid the cost of DOM interaction. Once you read a value, it is never read from the element again. If you wish to refresh this to re-read the element properties, invoke this method. Note that default values are maintained.
+
+### Syntax
+
+ api.refreshAPI();
+
+### Returns
+
+* *object* - the instance of Behavior.API.
+
+[Behavior]: Behavior.md
+[JSON.decode]: http://mootools.net/docs/core/Utilities/JSON#JSON:decode
Oops, something went wrong.

0 comments on commit 2e1877c

Please sign in to comment.