github-migration/prototype
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Extensive PDoc changes.

Browse Source
This commit is contained in:
Andrew Dupont 2009-03-05 13:56:01 -06:00
parent e88f22e0c3
commit 00742ac153
19 changed files with 234 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/dom.js
View File

@ -1,3 +1,10 @@
/**
* == DOM ==
* Extensions to DOM elements, plus other utilities for DOM traversal
* and modification.
**/
//= require "dom/dom"
//= require "dom/selector"
//= require "dom/form"

168
src/dom/dom.js
View File

@ -1,4 +1,4 @@
/** section: dom
/** section: DOM, related to: Element
* $(id) -> Element
* $(id...) -> [Element]...
* - id (String | Element): A DOM node or a string that references a node's
@ -58,7 +58,7 @@ if (!Node.ELEMENT_NODE) {
});
}
/** section: dom
/** section: DOM
* class Element
**/
@ -93,7 +93,7 @@ Element.idCounter = 1;
Element.Methods = {
/**
* Element.visible(@element) -> boolean
* Element#visible(@element) -> boolean
*
* Tells whether `element` is visible (i.e., whether its inline `display`
* CSS property is set to `none`.
@ -103,7 +103,7 @@ Element.Methods = {
},
/**
* Element.toggle(@element) -> Element
* Element#toggle(@element) -> Element
*
* Toggles the visibility of `element`. Returns `element`.
**/
@ -115,7 +115,7 @@ Element.Methods = {
/**
* Element.hide(@element) -> Element
* Element#hide(@element) -> Element
*
* Sets `display: none` on `element`. Returns `element`.
**/
@ -126,7 +126,7 @@ Element.Methods = {
},
/**
* Element.show(@element) -> Element
* Element#show(@element) -> Element
*
* Removes `display: none` on `element`. Returns `element`.
**/
@ -137,7 +137,7 @@ Element.Methods = {
},
/**
* Element.remove(@element) -> Element
* Element#remove(@element) -> Element
*
* Completely removes `element` from the document and returns it.
**/
@ -148,7 +148,7 @@ Element.Methods = {
},
/**
* Element.update(@element[, newContent]) -> Element
* Element#update(@element[, newContent]) -> Element
*
* Replaces _the content_ of `element` with the `newContent` argument and
* returns `element`.
@ -167,7 +167,7 @@ Element.Methods = {
},
/**
* Element.replace(@element[, newContent]) -> Element
* Element#replace(@element[, newContent]) -> Element
*
* Replaces `element` _itself_ with `newContent` and returns `element`.
*
@ -189,8 +189,8 @@ Element.Methods = {
},
/**
* Element.insert(@element, content) -> Element
* - content (String | Object): The content to insert.
* Element#insert(@element, content) -> Element
* - content (String | Object): The content to insert.
*
* Inserts content at a specific point relative to `element`.
*
@ -239,11 +239,11 @@ Element.Methods = {
},
/**
* Element.wrap(@element, wrapper[, attributes]) -> Element
* - wrapper (Element | String): An element to wrap `element` inside, or
* else a string representing the tag name of an element to be created.
* - attributes (Object): A set of attributes to apply to the wrapper
* element. Refer to the [[Element]] constructor for usage.
* Element#wrap(@element, wrapper[, attributes]) -> Element
* - wrapper (Element | String): An element to wrap `element` inside, or
* else a string representing the tag name of an element to be created.
* - attributes (Object): A set of attributes to apply to the wrapper
* element. Refer to the [[Element]] constructor for usage.
*
* Wraps an element inside another, then returns the wrapper.
**/
@ -260,7 +260,7 @@ Element.Methods = {
},
/**
* Element.inspect(@element) -> String
* Element#inspect(@element) -> String
*
* Returns the debug-oriented string representation of `element`.
**/
@ -276,7 +276,7 @@ Element.Methods = {
},
/**
* Element.recursivelyCollect(element, property) -> [Element...]
* Element#recursivelyCollect(element, property) -> [Element...]
*
* Recursively collects elements whose relationship to `element` is
* specified by `property`. `property` has to be a _property_ (a method
@ -293,7 +293,7 @@ Element.Methods = {
},
/**
* Element.ancestors(@element) -> [Element...]
* Element#ancestors(@element) -> [Element...]
*
* Collects all of `element`’s ancestors and returns them as an array of
* elements.
@ -303,7 +303,7 @@ Element.Methods = {
},
/**
* Element.descendants(@element) -> [Element...]
* Element#descendants(@element) -> [Element...]
*
* Collects all of element’s descendants and returns them as an array of
* elements.
@ -313,7 +313,7 @@ Element.Methods = {
},
/**
* Element.firstDescendant(@element) -> Element
* Element#firstDescendant(@element) -> Element
*
* Returns the first child that is an element.
*
@ -327,7 +327,7 @@ Element.Methods = {
},
/**
* Element.childElements(@element) -> [Element...]
* Element#childElements(@element) -> [Element...]
*
* Collects all of `element`’s immediate descendants (i.e., children) and
* returns them as an array of elements.
@ -340,7 +340,7 @@ Element.Methods = {
},
/**
* Element.previousSiblings(@element) -> [Element...]
* Element#previousSiblings(@element) -> [Element...]
*
* Collects all of `element`’s previous siblings and returns them as an
* array of elements.
@ -350,7 +350,7 @@ Element.Methods = {
},
/**
* Element.nextSiblings(@element) -> [Element...]
* Element#nextSiblings(@element) -> [Element...]
*
* Collects all of `element`’s next siblings and returns them as an array
* of elements.
@ -360,7 +360,7 @@ Element.Methods = {
},
/**
* Element.siblings(@element) -> [Element...]
* Element#siblings(@element) -> [Element...]
* Collects all of element’s siblings and returns them as an array of
* elements.
**/
@ -370,8 +370,8 @@ Element.Methods = {
},
/**
* Element.match(@element, selector) -> boolean
* - selector (String): A CSS selector.
* Element#match(@element, selector) -> boolean
* - selector (String): A CSS selector.
*
* Checks if `element` matches the given CSS selector.
**/
@ -382,9 +382,9 @@ Element.Methods = {
},
/**
* Element.up(@element[, expression[, index = 0]]) -> Element
* Element.up(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
* Element#up(@element[, expression[, index = 0]]) -> Element
* Element#up(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
*
* Returns `element`’s first ancestor (or the Nth ancestor, if `index`
* is specified) that matches `expression`. If no `expression` is
@ -400,9 +400,9 @@ Element.Methods = {
},
/**
* Element.down(@element[, expression[, index = 0]]) -> Element
* Element.down(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
* Element#down(@element[, expression[, index = 0]]) -> Element
* Element#down(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
*
* Returns `element`’s first descendant (or the Nth descendant, if `index`
* is specified) that matches `expression`. If no `expression` is
@ -417,9 +417,9 @@ Element.Methods = {
},
/**
* Element.previous(@element[, expression[, index = 0]]) -> Element
* Element.previous(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
* Element#previous(@element[, expression[, index = 0]]) -> Element
* Element#previous(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
*
* Returns `element`’s first previous sibling (or the Nth, if `index`
* is specified) that matches `expression`. If no `expression` is
@ -435,9 +435,9 @@ Element.Methods = {
},
/**
* Element.next(@element[, expression[, index = 0]]) -> Element
* Element.next(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
* Element#next(@element[, expression[, index = 0]]) -> Element
* Element#next(@element[, index = 0]) -> Element
* - expression (String): A CSS selector.
*
* Returns `element`’s first following sibling (or the Nth, if `index`
* is specified) that matches `expression`. If no `expression` is
@ -454,8 +454,8 @@ Element.Methods = {
/**
* Element.select(@element, selector...) -> [Element...]
* - selector (String): A CSS selector.
* Element#select(@element, selector...) -> [Element...]
* - selector (String): A CSS selector.
*
* Takes an arbitrary number of CSS selectors and returns an array of
* descendants of `element` that match any of them.
@ -467,7 +467,7 @@ Element.Methods = {
/**
* Element.adjacent(@element, selector...) -> [Element...]
* - selector (String): A CSS selector.
* - selector (String): A CSS selector.
*
* Finds all siblings of the current element that match the given
* selector(s).
@ -478,7 +478,7 @@ Element.Methods = {
},
/**
* Element.identify(@element) -> String
* Element#identify(@element) -> String
*
* Returns `element`'s ID. If `element` does not have an ID, one is
* generated, assigned to `element`, and returned.
@ -493,7 +493,7 @@ Element.Methods = {
},
/**
* Element.readAttribute(@element, attributeName) -> String | null
* Element#readAttribute(@element, attributeName) -> String | null
*
* Returns the value of `element`'s attribute with the given name.
**/
@ -536,8 +536,8 @@ Element.Methods = {
})(),
/**
* Element.writeAttribute(@element, attribute[, value = true]) -> Element
* Element.writeAttribute(@element, attributes) -> Element
* Element#writeAttribute(@element, attribute[, value = true]) -> Element
* Element#writeAttribute(@element, attributes) -> Element
*
* Adds, changes, or removes attributes passed as either a hash or a
* name/value pair.
@ -563,7 +563,7 @@ Element.Methods = {
},
/**
* Element.getHeight(@element) -> Number
* Element#getHeight(@element) -> Number
*
* Returns the height of `element`.
**/
@ -572,7 +572,7 @@ Element.Methods = {
},
/**
* Element.getWidth(@element) -> Number
* Element#getWidth(@element) -> Number
*
* Returns the width of `element`.
**/
@ -581,7 +581,7 @@ Element.Methods = {
},
/**
* Element.classNames(@element) -> [String...]
* Element#classNames(@element) -> [String...]
*
* Returns a new instance of [[Element.ClassNames]], an [[Enumerable]]
* object used to read and write CSS class names of `element`.
@ -591,7 +591,7 @@ Element.Methods = {
},
/**
* Element.hasClassName(@element, className) -> Boolean
* Element#hasClassName(@element, className) -> Boolean
*
* Checks whether `element` has the given CSS class name.
**/
@ -603,7 +603,7 @@ Element.Methods = {
},
/**
* Element.addClassName(@element, className) -> Element
* Element#addClassName(@element, className) -> Element
*
* Adds a CSS class to `element`.
**/
@ -615,7 +615,7 @@ Element.Methods = {
},
/**
* Element.removeClassName(@element, className) -> Element
* Element#removeClassName(@element, className) -> Element
*
* Removes a CSS class from `element`.
**/
@ -627,7 +627,7 @@ Element.Methods = {
},
/**
* Element.toggleClassName(@element, className) -> Element
* Element#toggleClassName(@element, className) -> Element
*
* Toggles the presence of a CSS class on `element`.
**/
@ -638,7 +638,7 @@ Element.Methods = {
},
/**
* Element.cleanWhitespace(@element) -> Element
* Element#cleanWhitespace(@element) -> Element
*
* Removes whitespace-only text node children from `element`.
**/
@ -655,7 +655,7 @@ Element.Methods = {
},
/**
* Element.empty(@element) -> Element
* Element#empty(@element) -> Element
*
* Tests whether `element` is empty (i.e., contains only whitespace).
**/
@ -664,7 +664,7 @@ Element.Methods = {
},
/**
* Element.descendantOf(@element, ancestor) -> Boolean
* Element#descendantOf(@element, ancestor) -> Boolean
*
* Checks if `element` is a descendant of `ancestor`.
**/
@ -684,7 +684,7 @@ Element.Methods = {
},
/**
* Element.scrollTo(@element) -> Element
* Element#scrollTo(@element) -> Element
*
* Scrolls the window so that `element` appears at the top of the viewport.
**/
@ -696,8 +696,8 @@ Element.Methods = {
},
/**
* Element.getStyle(@element, style) -> String | null
* - style (String): The property name to be retrieved.
* Element#getStyle(@element, style) -> String | null
* - style (String): The property name to be retrieved.
*
* Returns the given CSS property value of `element`. The property can be
* specified in either its CSS form (`font-size`) or its camelized form
@ -716,7 +716,7 @@ Element.Methods = {
},
/**
* Element.getOpacity(@element) -> String | null
* Element#getOpacity(@element) -> String | null
*
* Returns the opacity of the element.
**/
@ -725,7 +725,7 @@ Element.Methods = {
},
/**
* Element.setStyle(@element, styles) -> Element
* Element#setStyle(@element, styles) -> Element
*
* Modifies `element`’s CSS style properties.
*
@ -751,7 +751,7 @@ Element.Methods = {
},
/**
* Element.setOpacity(@element, value) -> Element
* Element#setOpacity(@element, value) -> Element
*
* Sets the opacity of `element`.
**/
@ -763,7 +763,7 @@ Element.Methods = {
},
/**
* Element.getDimensions(@element) -> Object
* Element#getDimensions(@element) -> Object
*
* Finds the computed width and height of `element` and returns them as
* key/value pairs of an object.
@ -793,8 +793,8 @@ Element.Methods = {
},
/**
* Element.makePositioned(@element) -> Element
*
* Element#makePositioned(@element) -> Element
*
* Allows for the easy creation of a CSS containing block by setting
* `element`'s CSS `position` to `relative` if its initial position is
* either `static` or `undefined`.
@ -816,7 +816,7 @@ Element.Methods = {
},
/**
* Element.undoPositioned(@element) -> Element
* Element#undoPositioned(@element) -> Element
*
* Sets `element` back to the state it was in _before_
* [[Element.makePositioned]] was applied to it.
@ -835,7 +835,7 @@ Element.Methods = {
},
/**
* Element.makeClipping(@element) -> Element
* Element#makeClipping(@element) -> Element
*
* Simulates the poorly-supported CSS `clip` property by setting `element`'s
* `overflow` value to `hidden`.
@ -850,7 +850,7 @@ Element.Methods = {
},
/**
* Element.undoClipping(@element) -> Element
* Element#undoClipping(@element) -> Element
*
* Sets `element`’s CSS `overflow` property back to the value it had
* _before_ [[Element.makeClipping]] was applied.
@ -864,7 +864,7 @@ Element.Methods = {
},
/**
* Element.cumulativeOffset(@element) -> Array
* Element#cumulativeOffset(@element) -> Array
*
* Returns the offsets of `element` from the top left corner of the
* document.
@ -883,7 +883,7 @@ Element.Methods = {
},
/**
* Element.positionedOffset(@element) -> Array
* Element#positionedOffset(@element) -> Array
*
* Returns `element`’s offset relative to its closest positioned ancestor
* (the element that would be returned by [[Element.getOffsetParent]]).
@ -907,7 +907,7 @@ Element.Methods = {
},
/**
* Element.absolutize(@element) -> Element
* Element#absolutize(@element) -> Element
*
* Turns `element` into an absolutely-positioned element _without_ changing
* its position in the page layout.
@ -936,7 +936,7 @@ Element.Methods = {
},
/**
* Element.relativize(@element) -> Element
* Element#relativize(@element) -> Element
*
* Turns `element` into a relatively-positioned element without changing
* its position in the page layout.
@ -978,7 +978,7 @@ Element.Methods = {
},
/**
* Element.getOffsetParent(@element) -> Element
* Element#getOffsetParent(@element) -> Element
*
* Returns `element`’s closest _positioned_ ancestor. If none is found, the
* `body` element is returned.
@ -995,7 +995,7 @@ Element.Methods = {
},
/**
* Element.viewportOffset(@element) -> Array
* Element#viewportOffset(@element) -> Array
*
* Returns the X/Y coordinates of element relative to the viewport.
*
@ -1028,7 +1028,7 @@ Element.Methods = {
},
/**
* Element.clonePosition(@element, source[, options]) -> Element
* Element#clonePosition(@element, source[, options]) -> Element
*
* Clones the position and/or dimensions of `source` onto `element` as
* defined by `options`.
@ -1081,12 +1081,12 @@ Element.Methods = {
Object.extend(Element.Methods, {
/** alias of: Element.select
* Element.getElementsBySelector(@element, selector) -> [Element...]
* Element#getElementsBySelector(@element, selector) -> [Element...]
**/
getElementsBySelector: Element.Methods.select,
/** alias of: Element.immediateDescendants
* Element.childElements(@element) -> [Element...]
* Element#childElements(@element) -> [Element...]
**/
childElements: Element.Methods.immediateDescendants
});
@ -1670,8 +1670,12 @@ Element.addMethods = function(methods) {
Element.cache = { };
};
/** section: dom
* document.viewport
/** section: DOM
* document.viewport
*
* The `document.viewport` namespace contains methods that return information
* about the viewport — the rectangle that represents the portion of a web
* page within view. In other words, it's the browser window minus all chrome.
**/
document.viewport = {
@ -1748,7 +1752,7 @@ Element.Storage = {
Element.addMethods({
/**
* Element.getStorage(@element) -> Hash
* Element#getStorage(@element) -> Hash
*
* Returns the [[Hash]] object that stores custom metadata for this element.
**/
@ -1771,7 +1775,7 @@ Element.addMethods({
},
/**
* Element.store(@element, key, value) -> Element
* Element#store(@element, key, value) -> Element
*
* Stores a key/value pair of custom metadata on the element.
*
@ -1791,7 +1795,7 @@ Element.addMethods({
},
/**
* Element.retrieve(@element, key[, defaultValue]) -> ?
* Element#retrieve(@element, key[, defaultValue]) -> ?
*
* Retrieves custom metadata set on `element` with [[Element.store]].
*

43
src/dom/event.js
View File

@ -1,6 +1,6 @@
(function() {
/** section: dom
/** section: DOM
* Event
**/
var Event = {
@ -46,7 +46,7 @@
}
/**
* Event.isLeftClick(@event) -> Boolean
* Event#isLeftClick(@event) -> Boolean
*
* Determines whether a button-related mouse event involved the left
* mouse button.
@ -58,7 +58,7 @@
function isLeftClick(event) { return _isButton(event, 0) }
/**
* Event.isMiddleClick(@event) -> Boolean
* Event#isMiddleClick(@event) -> Boolean
*
* Determines whether a button-related mouse event involved the middle
* mouse button.
@ -66,7 +66,7 @@
function isMiddleClick(event) { return _isButton(event, 1) }
/**
* Event.isRightClick(@event) -> Boolean
* Event#isRightClick(@event) -> Boolean
*
* Determines whether a button-related mouse event involved the right
* mouse button.
@ -78,7 +78,7 @@
function isRightClick(event) { return _isButton(event, 2) }
/**
* Event.element(@event) -> Element
* Event#element(@event) -> Element
*
* Returns the DOM element on which the event occurred.
**/
@ -107,7 +107,7 @@
}
/**
* Event.findElement(@event, expression) -> Element
* Event#findElement(@event, expression) -> Element
*
* Returns the first DOM element that matches a given CSS selector —
* starting with the element on which the event occurred, then moving up
@ -121,7 +121,7 @@
}
/**
* Event.pointer(@event) -> Object
* Event#pointer(@event) -> Object
*
* Returns the absolute position of the pointer for a mouse event.
*
@ -135,7 +135,7 @@
}
/**
* Event.pointerX(event) -> Number
* Event#pointerX(event) -> Number
*
* Returns the absolute horizontal position of the pointer for a mouse
* event.
@ -153,7 +153,7 @@
}
/**
* Event.pointerY(event) -> Number
* Event#pointerY(event) -> Number
*
* Returns the absolute vertical position of the pointer for a mouse
* event.
@ -172,7 +172,7 @@
/**
* Event.stop(@event) -> undefined
* Event#stop(@event) -> undefined
*
* Stops the event’s propagation and prevents its eventual default action
* from being triggered.
@ -430,7 +430,11 @@
return element;
}
var responders = registry.get(eventName);
var responders = registry.get(eventName);
// Fail gracefully if there are no responders assigned.
if (!responders) return;
var responder = responders.find( function(r) { return r.handler === handler; });
if (!responder) return element;
@ -507,36 +511,39 @@
Element.addMethods({
/** alias of: Event.fire
* Element.fire(@element, eventName[, memo[, bubble = true]]) -> Event
* Element#fire(@element, eventName[, memo[, bubble = true]]) -> Event
**/
fire: fire,
/** alias of: Event.observe
* Element.observe(@element, eventName, handler) -> Element
* Element#observe(@element, eventName, handler) -> Element
**/
observe: observe,
/** alias of: Event.observe
* Element.stopObserving(element[, eventName[, handler]]) -> Element
* Element#stopObserving(element[, eventName[, handler]]) -> Element
**/
stopObserving: stopObserving
});
/** section: dom
/** section: DOM
* document
*
* Prototype extends the built-in `document` object with several convenience
* methods related to events.
**/
Object.extend(document, {
/** related to: Event.fire
/**
* document.fire(eventName[, memo[, bubble = true]]) -> Event
**/
fire: fire.methodize(),
/** related to: Event.observe
/**
* document.observe(eventName, handler) -> Element
**/
observe: observe.methodize(),
/** related to: Event.observe
/**
* document.stopObserving([eventName[, handler]]) -> Element
**/
stopObserving: stopObserving.methodize(),

52
src/dom/form.js
View File

@ -1,4 +1,4 @@
/** section: dom
/** section: DOM
* Form
**/
@ -54,7 +54,7 @@ var Form = {
Form.Methods = {
/**
* Form.serialize(@form[, options]) -> String | Object
* Form#serialize(@form[, options]) -> String | Object
* - options (Object): A list of options that affect the return value
* of the method.
*
@ -68,7 +68,7 @@ Form.Methods = {
},
/**
* Form.getElements(@form) -> [Element...]
* Form#getElements(@form) -> [Element...]
*
* Returns a collection of all controls within a form.
**/
@ -83,7 +83,7 @@ Form.Methods = {
},
/**
* Form.getInputs(@form [, type [, name]]) -> [Element...]
* Form#getInputs(@form [, type [, name]]) -> [Element...]
* - type (String): A value for the `type` attribute against which to
* filter.
* - name (String): A value for the `name` attribute against which to
@ -111,7 +111,7 @@ Form.Methods = {
},
/**
* Form.disable(@form) -> Element
* Form#disable(@form) -> Element
*
* Disables the form as a whole. Form controls will be visible but
* uneditable.
@ -123,7 +123,7 @@ Form.Methods = {
},
/**
* Form.enable(@form) -> Element
* Form#enable(@form) -> Element
*
* Enables a fully- or partially-disabled form.
**/
@ -134,7 +134,7 @@ Form.Methods = {
},
/**
* Form.findFirstElement(@form) -> Element
* Form#findFirstElement(@form) -> Element
*
* Finds the first non-hidden, non-disabled control within the form.
**/
@ -152,7 +152,7 @@ Form.Methods = {
},
/**
* Form.focusFirstElement(@form) -> Element
* Form#focusFirstElement(@form) -> Element
*
* Gives keyboard focus to the first element of the form. Returns the form.
**/
@ -163,7 +163,7 @@ Form.Methods = {
},
/**
* Form.request([options]) -> Ajax.Request
* Form#request([options]) -> Ajax.Request
* - options (Object): Options to pass along to the `Ajax.Request`
* constructor.
*
@ -195,7 +195,7 @@ Form.Methods = {
/*--------------------------------------------------------------------------*/
/** section: dom
/** section: DOM
* Form.Element
**/
@ -224,7 +224,7 @@ Form.Element = {
Form.Element.Methods = {
/**
* Form.Element.serialize(@element) -> String
* Form.Element#serialize(@element) -> String
*
* Returns a URL-encoded string representation of a form control in the
* `name=value` format.
@ -243,7 +243,7 @@ Form.Element.Methods = {
},
/** alias of: $F
* Form.Element.getValue(@element) -> String | Array
* Form.Element#getValue(@element) -> String | Array
*
* Returns the current value of a form control.
*
@ -259,7 +259,7 @@ Form.Element.Methods = {
},
/**
* Form.Element.setValue(@element, value) -> Element
* Form.Element#setValue(@element, value) -> Element
*
* Sets `value` to be the value of the form control. Returns the element.
**/
@ -271,7 +271,7 @@ Form.Element.Methods = {
},
/**
* Form.Element.clear(@element) -> Element
* Form.Element#clear(@element) -> Element
*
* Clears the contents of a text input. Returns the element.
**/
@ -281,7 +281,7 @@ Form.Element.Methods = {
},
/**
* Form.Element.present(@element) -> Element
* Form.Element#present(@element) -> Element
*
* Returns `true` if a text input has contents, `false` otherwise.
**/
@ -290,7 +290,7 @@ Form.Element.Methods = {
},
/**
* Form.Element.activate(@element) -> Element
* Form.Element#activate(element) -> Element
*
* Gives focus to a form control and selects its contents if it is a text
* input.
@ -307,7 +307,7 @@ Form.Element.Methods = {
},
/**
* Form.Element.disable(@element) -> Element
* Form.Element#disable(@element) -> Element
*
* Disables a form control, effectively preventing its value from changing
* until it is enabled again.
@ -319,7 +319,7 @@ Form.Element.Methods = {
},
/**
* Form.Element.enable(@element) -> Element
* Form.Element#enable(@element) -> Element
*
* Enables a previously disabled form control.
**/
@ -334,7 +334,7 @@ Form.Element.Methods = {
var Field = Form.Element;
/** section: dom, alias of: Form.Element.getValue
/** section: DOM, alias of: Form.Element.getValue
* $F(element) -> String | Array
**/
var $F = Form.Element.Methods.getValue;
@ -406,11 +406,11 @@ Form.Element.Serializers = {
/*--------------------------------------------------------------------------*/
/** section: dom
/** section: DOM
* Abstract
**/
/** section: dom
/** section: DOM
* class Abstract.TimedObserver
**/
Abstract.TimedObserver = Class.create(PeriodicalExecuter, {
@ -430,7 +430,7 @@ Abstract.TimedObserver = Class.create(PeriodicalExecuter, {
}
});
/** section: dom
/** section: DOM
* class Form.Element.Observer < Abstract.TimedObserver
**/
Form.Element.Observer = Class.create(Abstract.TimedObserver, {
@ -444,7 +444,7 @@ Form.Element.Observer = Class.create(Abstract.TimedObserver, {
}
});
/** section: dom
/** section: DOM
* class Form.Observer < Abstract.TimedObserver
**/
Form.Observer = Class.create(Abstract.TimedObserver, {
@ -461,7 +461,7 @@ Form.Observer = Class.create(Abstract.TimedObserver, {
/*--------------------------------------------------------------------------*/
/** section: dom
/** section: DOM
* class Abstract.EventObserver
**/
Abstract.EventObserver = Class.create({
@ -503,7 +503,7 @@ Abstract.EventObserver = Class.create({
}
});
/** section: dom
/** section: DOM
* class Form.Element.EventObserver < Abstract.EventObserver
**/
Form.Element.EventObserver = Class.create(Abstract.EventObserver, {
@ -512,7 +512,7 @@ Form.Element.EventObserver = Class.create(Abstract.EventObserver, {
}
});
/** section: dom
/** section: DOM
* class Form.Element.EventObserver < Abstract.EventObserver
**/
Form.EventObserver = Class.create(Abstract.EventObserver, {

63
src/dom/selector.js
View File

@ -1,8 +1,20 @@
/* Portions of the Selector class are derived from Jack Slocum's DomQuery,
* part of YUI-Ext version 0.40, distributed under the terms of an MIT-style
* license. Please see http://www.yui-ext.com/ for more information. */
/** section: DOM
* class Selector
*
* A class that queries the document for elements that match a given CSS
* selector.
**/
var Selector = Class.create({
/**
* new Selector(expression)
* - expression (String): A CSS selector.
*
* Creates a `Selector` with the given CSS selector.
**/
initialize: function(expression) {
this.expression = expression.strip();
@ -138,6 +150,14 @@ var Selector = Class.create({
Selector._cache[this.expression] = this.xpath;
},
/**
* Selector#findElements(root) -> [Element...]
* - root (Element || document): A "scope" to search within. All results will
* be descendants of this node.
*
* Searches the document for elements that match the instance's CSS
* selector.
**/
findElements: function(root) {
root = root || document;
var e = this.expression, results;
@ -165,6 +185,11 @@ var Selector = Class.create({
}
},
/**
* Selector#match(element) -> Boolean
*
* Tests whether a `element` matches the instance's CSS selector.
**/
match: function(element) {
this.tokens = [];
@ -732,6 +757,15 @@ Object.extend(Selector, {
'-').include('-' + (v || "").toUpperCase() + '-'); }
},
/**
* Selector.split(expression) -> [String...]
*
* Takes a string of CSS selectors separated by commas; returns an array
* of individual selectors.
*
* Safer than doing a naive `Array#split`, since selectors can have commas
* in other places.
**/
split: function(expression) {
var expressions = [];
expression.scan(/(([\w#:.~>+()\s-]+|\*|\[.*?\])+)\s*(,|$)/, function(m) {
@ -740,6 +774,13 @@ Object.extend(Selector, {
return expressions;
},
/**
* Selector.matchElements(elements, expression) -> [Element...]
*
* Filters the given collection of elements with `expression`.
*
* The only nodes returned will be those that match the given CSS selector.
**/
matchElements: function(elements, expression) {
var matches = $$(expression), h = Selector.handlers;
h.mark(matches);
@ -749,6 +790,15 @@ Object.extend(Selector, {
return results;
},
/**
* Selector.findElement(elements, expression[, index = 0]) -> Element
* Selector.findElement(elements[, index = 0]) -> Element
*
* Returns the `index`th element in the collection that matches
* `expression`.
*
* Returns the `index`th element overall if `expression` is not given.
**/
findElement: function(elements, expression, index) {
if (Object.isNumber(expression)) {
index = expression; expression = false;
@ -756,6 +806,12 @@ Object.extend(Selector, {
return Selector.matchElements(elements, expression || '*')[index || 0];
},
/**
* Selector.findChildElements(element, expressions) -> [Element...]
*
* Searches beneath `element` for any elements that match the selector
* (or selectors) specified in `expressions`.
**/
findChildElements: function(element, expressions) {
expressions = Selector.split(expressions.join(','));
var results = [], h = Selector.handlers;
@ -786,6 +842,11 @@ if (Prototype.Browser.IE) {
});
}
/** related to: Selector
* $$(expression...) -> [Element...]
*
* Returns all elements in the document that match the provided CSS selectors.
**/
function $$() {
return Selector.findChildElements(document, $A(arguments));
}

7
src/lang.js
View File

@ -1,11 +1,12 @@
/**
* == lang ==
* Language extensions.
* == Language ==
* Additions to JavaScript's "standard library" and extensions to
* built-in JavaScript objects.
**/
var Abstract = { };
/** section: lang
/** section: Language
* Try
**/

8
src/lang/array.js
View File

@ -1,4 +1,4 @@
/** section: lang, alias of: Array.from
/** section: Language, alias of: Array.from
* $A(iterable) -> Array
*
* Accepts an array-like collection (anything with numeric indices) and returns
@ -29,7 +29,7 @@ if (Prototype.Browser.WebKit) {
};
}
/** section: lang
/** section: Language
* $w(string) -> Array
* - string (String): A string with zero or more spaces.
*
@ -45,8 +45,8 @@ function $w(string) {
Array.from = $A;
/** section: lang
* Array
/** section: Language
* class Array
**/
(function() {
var arrayProto = Array.prototype,

2
src/lang/class.js
View File

@ -1,6 +1,6 @@
/* Based on Alex Arnell's inheritance implementation. */
/** section: lang
/** section: Language
* Class
**/
var Class = (function() {

4
src/lang/date.js
View File

@ -1,5 +1,5 @@
/** section: lang
* Date
/** section: Language
* class Date
**/
/**

2
src/lang/enumerable.js
View File

@ -1,4 +1,4 @@
/** section: lang
/** section: Language
* mixin Enumerable
**/

4
src/lang/function.js
View File

@ -1,5 +1,5 @@
/** section: lang
* Function
/** section: Language
* class Function
**/
Object.extend(Function.prototype, (function() {
var slice = Array.prototype.slice;

4
src/lang/hash.js
View File

@ -1,4 +1,4 @@
/** section: lang
/** section: Language
* $H([object]) -> Hash
*
* Creates a Hash (which is synonymous to “map” or “associative array” for our purposes).
@ -9,7 +9,7 @@ function $H(object) {
return new Hash(object);
};
/** section: lang
/** section: Language
* class Hash
**/
var Hash = Class.create(Enumerable, (function() {

4
src/lang/number.js
View File

@ -1,5 +1,5 @@
/** section: lang
* Number
/** section: Language
* class Number
**/
Object.extend(Number.prototype, (function() {
/**

4
src/lang/object.js
View File

@ -1,5 +1,5 @@
/** section: lang
* Object
/** section: Language
* class Object
**/
(function() {

2
src/lang/periodical_executer.js
View File

@ -1,4 +1,4 @@
/** section: lang
/** section: Language
* class PeriodicalExecuter
**/
var PeriodicalExecuter = Class.create({

4
src/lang/range.js
View File

@ -1,8 +1,8 @@
/** section: lang
/** section: Language
* class ObjectRange
**/
/** section: lang
/** section: Language
* $R(start, end[, exclusive = false]) -> ObjectRange
*
* Creates a new ObjectRange object.

4
src/lang/regexp.js
View File

@ -1,5 +1,5 @@
/** section: lang
* RegExp
/** section: Language
* class RegExp
**/
/** alias of: RegExp#test

4
src/lang/string.js
View File

@ -1,5 +1,5 @@
/** section: lang
* String
/** section: Language
* class String
**/
Object.extend(String, {
/**

2
src/lang/template.js
View File

@ -1,4 +1,4 @@
/** section: lang
/** section: Language
* class Template
**/
var Template = Class.create({