Permalink
Browse files

document new methods, revise some core methods

  • Loading branch information...
1 parent 1519d15 commit aa0400470fb31802772225b712ed67d5e310e11c @mislav mislav committed Apr 9, 2012
@@ -7,7 +7,7 @@ signature: |
Extend target object with properties from each of the source objects,
overriding the properties on target.
-{% highlight js %}
+{% highlight js hl_lines=4 %}
var target = { one: 'patridge' },
source = { two: 'turtle doves' }
@@ -1,5 +1,6 @@
---
title: $.inArray
+version: 1.0
signature: |
$.inArray(element, array, [fromIndex]) ⇒ number
---
@@ -1,16 +1,17 @@
---
title: $.isPlainObject
+version: 1.0
signature: |
$.isPlainObject(object) ⇒ boolean
---
-True if the object is a "plain" JavaScript object;
-which is true for object literals and objects created with `new Object` only.
+True if the object is a "plain" JavaScript object, which is only true for object
+literals and objects created with `new Object`.
{% highlight js %}
-$.isPlainObject({}) // => true
+$.isPlainObject({}) // => true
$.isPlainObject(new Object) // => true
-$.isPlainObject(new Date) // => false
-$.isPlainObject(window) // => false
+$.isPlainObject(new Date) // => false
+$.isPlainObject(window) // => false
{% endhighlight %}
@@ -0,0 +1,9 @@
+---
+title: $.trim
+version: 1.0
+signature: |
+ $.trim(string) ⇒ string
+---
+
+Remove whitespace from beginning and end of a string; just like
+String.prototype.trim().
@@ -8,39 +8,32 @@ signature: |
Zepto(function($){ ... })
---
-Obtain a Zepto collection object by performing a CSS selector, wrapping DOM
+Create a Zepto collection object by performing a CSS selector, wrapping DOM
nodes, or creating elements from an HTML string. If context for the selector is
given, perform CSS selector only on descendants of context nodes.
-The returned Zepto collection object is an array-like object,
-containing references to all the matched or newly created DOM nodes.
+A Zepto collection is an array-like object that has chainable methods for
+manipulating contents of the page. All of the methods in this documentations are
+collection methods, except ones whose names start with `$.*`.
-If a function is given, attach it as a handler for the `DOMContentLoaded` event,
-making it execute after the DOM on the page is ready. If the page is already
-loaded, executes the function immediately.
+If a function is given, attach it as a handler for the `DOMContentLoaded` event.
+If the page is already loaded, executes the function immediately.
{% highlight js %}
-// Selectors
-$('div') // => collection of all `div` elements on the page
-$('#foo') // => collection containing the element with id=foo
+$('div') //=> all DIV elements on the page
+$('#foo') //=> element with ID "foo"
-// Contexts
-$('a', '#sidebar')
-// => collection of all `a` elements within the id=sidebar element
-var sidebar = $('#sidebar')
-$('a', sidebar)
-// => collection of all `a` elements within the id=sidebar element
+// generate elements from HTML
+$("<p>Hello</p>") //=> the orphaned P element
-// Node generation from HTML
-$("<p>Hello Zepto!</p>") // => collection containing a `p` element
-
-// execute JavaScript when the page DOM is ready
+// execute function when the page is ready
Zepto(function($){
alert('Ready to Zepto!')
})
{% endhighlight %}
<p class=compat>
-Zepto supports CSS selectors as per the <a href="http://www.w3.org/Style/CSS/">CSS specification</a> only.
-<a href="http://api.jquery.com/category/selectors/jquery-selector-extensions/">Proprietary jQuery CSS extensions</a> are not supported.
+ <a href="http://api.jquery.com/category/selectors/jquery-selector-extensions/">jQuery
+ CSS extensions</a> are not supported. The optional "selector" module provides
+ limited support for few of the most used pseudo-selectors.
</p>
@@ -12,6 +12,8 @@ from the first element in the collection. When value is given, sets the
attribute to that value on each element in the collection. Multiple attributes
can be set in the same call by passing an Object to the method.
+To read DOM properties such as `checked` or `selected`, use [prop](#prop).
+
{% highlight js %}
var form = $('form')
form.attr('action') //=> read value
@@ -0,0 +1,13 @@
+---
+title: clone
+version: 1.0
+signature: |
+ clone() ⇒ collection
+---
+
+Duplicate all elements in the collection via deep clone.
+
+<p class=compat>
+ This method doesn't have an option for copying data and event handlers over to
+ the new elements, as it has in jQuery.
+</p>
@@ -11,12 +11,15 @@ property from the first element in the collection. When a value is given, sets t
property to that value on each element of the collection. Multiple properties
can be set by passing an object to the method.
-When a unitless number value is given, "px" is appended to it for properties
-that require units.
+When a value for a property is empty, that property is removed. When a unitless
+number value is given, "px" is appended to it for properties that require units.
{% highlight js %}
var elem = $('h1')
-elem.css('background-color') //=> read property
-elem.css('background-color', '#369') //=> set property
+elem.css('background-color') // read property
+elem.css('background-color', '#369') // set property
+elem.css('background-color', '') // remove property
+
+// set multiple properties:
elem.css({ backgroundColor: '#8EE', fontSize: 28 })
{% endhighlight %}
@@ -5,9 +5,12 @@ signature: |
---
Check if the first element of the current collection matches the CSS selector.
+For basic support of jQuery's non-standard pseudo-selectors such as `:visible`,
+include the optional "selector" module.
<p class=compat>
<a href="http://api.jquery.com/category/selectors/jquery-selector-extensions/">jQuery
- proprietary pseudo-selectors</a> such as <code>:visible</code> are not supported.
+ CSS extensions</a> are not supported. The optional "selector" module only
+ provides limited support for few of the most used ones.
</p>
@@ -0,0 +1,12 @@
+---
+title: prop
+version: 1.0
+signature: |
+ prop(name) ⇒ value
+ prop(name, value) ⇒ self
+ prop(name, function(index, oldValue){ ... }) ⇒ self
+---
+
+Read or set properties of DOM elements. This should be preferred over [attr](#attr) in
+case of reading values of properties that change with user interaction over
+time, such as `checked` and `selected`.
@@ -0,0 +1,19 @@
+---
+title: $.proxy
+version: 1.0
+signature: |
+ $.proxy(fn, context) ⇒ function
+ $.proxy(context, property) ⇒ function
+---
+
+Get a function that ensures that the value of `this` in the original function
+refers to the context object. In the second form, the original function is read
+from the specific property of the context object.
+
+{% highlight js hl_lines=5 %}
+var obj = {name: 'Zepto'},
+ handler = function(){ console.log("hello from + ", this.name) }
+
+// ensures that the handler will be executed in the context of `obj`:
+$(document).on('click', $.proxy(obj, handler))
+{% endhighlight %}
@@ -8,7 +8,7 @@ Trigger the specified event on elements of the collection. Event can either be a
string type, or a full event object obtained with [$.Event](#$.Event). If a data
array is given, it is passed as additional arguments to event handlers.
-{% highlight js %}
+{% highlight js hl_lines=6 %}
// add a handler for a custom event
$(document).on('mylib:change', function(e, from, to){
console.log('change on %o with data %s, %s', e.target, from, to)
@@ -18,5 +18,5 @@ $(document.body).trigger('mylib:change', ['one', 'two'])
{% endhighlight %}
<p class=compat>
-Zepto supports triggering events on DOM elements only.
+ Zepto only supports triggering events on DOM elements.
</p>

0 comments on commit aa04004

Please sign in to comment.