From 60b9477c5b98459ff21afb5f2206429455e9425e Mon Sep 17 00:00:00 2001 From: Andrew Dupont Date: Tue, 24 Feb 2009 05:21:31 -0600 Subject: [PATCH] Added PDoc for dom.js. --- src/dom/dom.js | 501 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 493 insertions(+), 8 deletions(-) diff --git a/src/dom/dom.js b/src/dom/dom.js index 2e78d4f..859c3c5 100644 --- a/src/dom/dom.js +++ b/src/dom/dom.js @@ -1,3 +1,19 @@ +/** section: dom + * $(id) -> Element + * $(id...) -> [Element]... + * - id (String | Element): A DOM node or a string that references a node's + * ID. + * + * If provided with a string, returns the element in the document with + * matching ID; otherwise returns the passed element. + * + * Takes in an arbitrary number of arguments. Returns one `Element` if given + * one argument; otherwise returns an array of `Element`s. + * + * All elements returned by the function are "extended" with `Element` + * instance methods. +**/ + function $(element) { if (arguments.length > 1) { for (var i = 0, elements = [], length = arguments.length; i < length; i++) @@ -42,6 +58,18 @@ if (!Node.ELEMENT_NODE) { }); } +/** section: dom + * class Element +**/ + +/** + * new Element(tagName[, attributes]) + * - tagName (String): The name of the HTML element to create. + * - attributes (Object): A list of attribute/value pairs to set on the + * element. + * + * Creates an HTML element with `tagName` as the tag name. +**/ (function(global) { var element = global.Element; global.Element = function(tagName, attributes) { @@ -64,34 +92,70 @@ Element.cache = { }; Element.idCounter = 1; Element.Methods = { + /** + * Element.visible(@element) -> boolean + * + * Tells whether `element` is visible (i.e., whether its inline `display` + * CSS property is set to `none`. + **/ visible: function(element) { return $(element).style.display != 'none'; }, + /** + * Element.toggle(@element) -> Element + * + * Toggles the visibility of `element`. Returns `element`. + **/ toggle: function(element) { element = $(element); Element[Element.visible(element) ? 'hide' : 'show'](element); return element; }, - + + + /** + * Element.hide(@element) -> Element + * + * Sets `display: none` on `element`. Returns `element`. + **/ hide: function(element) { element = $(element); element.style.display = 'none'; return element; }, + /** + * Element.show(@element) -> Element + * + * Removes `display: none` on `element`. Returns `element`. + **/ show: function(element) { element = $(element); element.style.display = ''; return element; }, + /** + * Element.remove(@element) -> Element + * + * Completely removes `element` from the document and returns it. + **/ remove: function(element) { element = $(element); element.parentNode.removeChild(element); return element; }, + /** + * Element.update(@element[, newContent]) -> Element + * + * Replaces _the content_ of `element` with the `newContent` argument and + * returns `element`. + * + * If `newContent` is omitted, the element's content is blanked out (i.e., + * replaced with an empty string). + **/ update: function(element, content) { element = $(element); if (content && content.toElement) content = content.toElement(); @@ -102,6 +166,14 @@ Element.Methods = { return element; }, + /** + * Element.replace(@element[, newContent]) -> Element + * + * Replaces `element` _itself_ with `newContent` and returns `element`. + * + * Keep in mind that this method returns the element that has just been + * removed — not the element that took its place. + **/ replace: function(element, content) { element = $(element); if (content && content.toElement) content = content.toElement(); @@ -116,6 +188,20 @@ Element.Methods = { return element; }, + /** + * Element.insert(@element, content) -> Element + * - content (String | Object): The content to insert. + * + * Inserts content at a specific point relative to `element`. + * + * The `content` argument can be a string, in which case the implied + * insertion point is `bottom`. Or it can be an object that specifies + * one or more insertion points (e.g., `{ bottom: "foo", top: "bar" }`). + * + * Accepted insertion points are `before` (as `element`'s previous sibling); + * `after` (as `element's` next sibling); `top` (as `element`'s first + * child); and `bottom` (as `element`'s last child). + **/ insert: function(element, insertions) { element = $(element); @@ -152,6 +238,15 @@ Element.Methods = { return element; }, + /** + * 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. + **/ wrap: function(element, wrapper, attributes) { element = $(element); if (Object.isElement(wrapper)) @@ -163,7 +258,12 @@ Element.Methods = { wrapper.appendChild(element); return wrapper; }, - + + /** + * Element.inspect(@element) -> String + * + * Returns the debug-oriented string representation of `element`. + **/ inspect: function(element) { element = $(element); var result = '<' + element.tagName.toLowerCase(); @@ -175,6 +275,14 @@ Element.Methods = { return result + '>'; }, + /** + * Element.recursivelyCollect(element, property) -> [Element...] + * + * Recursively collects elements whose relationship to `element` is + * specified by `property`. `property` has to be a _property_ (a method + * won’t do!) of `element` that points to a single DOM node (e.g., + * `nextSibling` or `parentNode`). + **/ recursivelyCollect: function(element, property) { element = $(element); var elements = []; @@ -184,20 +292,47 @@ Element.Methods = { return elements; }, + /** + * Element.ancestors(@element) -> [Element...] + * + * Collects all of `element`’s ancestors and returns them as an array of + * elements. + **/ ancestors: function(element) { return $(element).recursivelyCollect('parentNode'); }, + /** + * Element.descendants(@element) -> [Element...] + * + * Collects all of element’s descendants and returns them as an array of + * elements. + **/ descendants: function(element) { return Element.select(element, "*"); }, + /** + * Element.firstDescendant(@element) -> Element + * + * Returns the first child that is an element. + * + * This is opposed to the `firstChild` DOM property, which will return + * any node, including text nodes. + **/ firstDescendant: function(element) { element = $(element).firstChild; while (element && element.nodeType != 1) element = element.nextSibling; return $(element); }, + /** alias of: Element.childElements + * + * Element.childElements(@element) -> [Element...] + * + * Collects all of `element`’s immediate descendants (i.e., children) and + * returns them as an array of elements. + **/ immediateDescendants: function(element) { if (!(element = $(element).firstChild)) return []; while (element && element.nodeType != 1) element = element.nextSibling; @@ -205,25 +340,58 @@ Element.Methods = { return []; }, + /** + * Element.previousSiblings(@element) -> [Element...] + * + * Collects all of `element`’s previous siblings and returns them as an + * array of elements. + **/ previousSiblings: function(element) { return $(element).recursivelyCollect('previousSibling'); }, + /** + * Element.nextSiblings(@element) -> [Element...] + * + * Collects all of `element`’s next siblings and returns them as an array + * of elements. + **/ nextSiblings: function(element) { return $(element).recursivelyCollect('nextSibling'); }, + /** + * Element.siblings(@element) -> [Element...] + * Collects all of element’s siblings and returns them as an array of + * elements. + **/ siblings: function(element) { element = $(element); return element.previousSiblings().reverse().concat(element.nextSiblings()); }, + /** + * Element.match(@element, selector) -> boolean + * - selector (String): A CSS selector. + * + * Checks if `element` matches the given CSS selector. + **/ match: function(element, selector) { if (Object.isString(selector)) selector = new Selector(selector); return selector.match($(element)); }, + /** + * 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 + * provided, all ancestors are considered. If no ancestor matches these + * criteria, `undefined` is returned. + **/ up: function(element, expression, index) { element = $(element); if (arguments.length == 1) return $(element.parentNode); @@ -232,6 +400,16 @@ Element.Methods = { Selector.findElement(ancestors, expression, index); }, + /** + * 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 + * provided, all descendants are considered. If no descendant matches these + * criteria, `undefined` is returned. + **/ down: function(element, expression, index) { element = $(element); if (arguments.length == 1) return element.firstDescendant(); @@ -239,6 +417,16 @@ Element.Methods = { Element.select(element, expression)[index || 0]; }, + /** + * 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 + * provided, all previous siblings are considered. If none matches these + * criteria, `undefined` is returned. + **/ previous: function(element, expression, index) { element = $(element); if (arguments.length == 1) return $(Selector.handlers.previousElementSibling(element)); @@ -247,6 +435,16 @@ Element.Methods = { Selector.findElement(previousSiblings, expression, index); }, + /** + * 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 + * provided, all following siblings are considered. If none matches these + * criteria, `undefined` is returned. + **/ next: function(element, expression, index) { element = $(element); if (arguments.length == 1) return $(Selector.handlers.nextElementSibling(element)); @@ -255,16 +453,37 @@ Element.Methods = { Selector.findElement(nextSiblings, expression, index); }, + + /** + * 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. + **/ select: function() { var args = $A(arguments), element = $(args.shift()); return Selector.findChildElements(element, args); }, + /** + * Element.adjacent(@element, selector...) -> [Element...] + * - selector (String): A CSS selector. + * + * Finds all siblings of the current element that match the given + * selector(s). + **/ adjacent: function() { var args = $A(arguments), element = $(args.shift()); return Selector.findChildElements(element.parentNode, args).without(element); }, + /** + * Element.identify(@element) -> String + * + * Returns `element`'s ID. If `element` does not have an ID, one is + * generated, assigned to `element`, and returned. + **/ identify: function(element) { element = $(element); var id = element.readAttribute('id'); @@ -274,6 +493,11 @@ Element.Methods = { return id; }, + /** + * Element.readAttribute(@element, attributeName) -> String | null + * + * Returns the value of `element`'s attribute with the given name. + **/ readAttribute: (function(){ var iframeGetAttributeThrowsError = (function(){ @@ -312,6 +536,13 @@ Element.Methods = { } })(), + /** + * 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. + **/ writeAttribute: function(element, name, value) { element = $(element); var attributes = { }, t = Element._attributeTranslations.write; @@ -332,18 +563,39 @@ Element.Methods = { return element; }, + /** + * Element.getHeight(@element) -> Number + * + * Returns the height of `element`. + **/ getHeight: function(element) { return $(element).getDimensions().height; }, + /** + * Element.getWidth(@element) -> Number + * + * Returns the width of `element`. + **/ getWidth: function(element) { return $(element).getDimensions().width; }, + /** + * Element.classNames(@element) -> [String...] + * + * Returns a new instance of [[Element.ClassNames]], an [[Enumerable]] + * object used to read and write CSS class names of `element`. + **/ classNames: function(element) { return new Element.ClassNames(element); }, + /** + * Element.hasClassName(@element, className) -> Boolean + * + * Checks whether `element` has the given CSS class name. + **/ hasClassName: function(element, className) { if (!(element = $(element))) return; var elementClassName = element.className; @@ -351,6 +603,11 @@ Element.Methods = { new RegExp("(^|\\s)" + className + "(\\s|$)").test(elementClassName))); }, + /** + * Element.addClassName(@element, className) -> Element + * + * Adds a CSS class to `element`. + **/ addClassName: function(element, className) { if (!(element = $(element))) return; if (!element.hasClassName(className)) @@ -358,6 +615,11 @@ Element.Methods = { return element; }, + /** + * Element.removeClassName(@element, className) -> Element + * + * Removes a CSS class from `element`. + **/ removeClassName: function(element, className) { if (!(element = $(element))) return; element.className = element.className.replace( @@ -365,13 +627,22 @@ Element.Methods = { return element; }, + /** + * Element.toggleClassName(@element, className) + * + * Toggles the presence of a CSS class on `element`. + **/ toggleClassName: function(element, className) { if (!(element = $(element))) return; return element[element.hasClassName(className) ? 'removeClassName' : 'addClassName'](className); }, - // removes whitespace-only text node children + /** + * Element.cleanWhitespace(@element) -> Element + * + * Removes whitespace-only text node children from `element`. + **/ cleanWhitespace: function(element) { element = $(element); var node = element.firstChild; @@ -384,10 +655,20 @@ Element.Methods = { return element; }, + /** + * Element.empty(@element) -> Element + * + * Tests whether `element` is empty (i.e., contains only whitespace). + **/ empty: function(element) { return $(element).innerHTML.blank(); }, + /** + * Element.descendantOf(@element, ancestor) -> Boolean + * + * Checks if `element` is a descendant of `ancestor`. + **/ descendantOf: function(element, ancestor) { element = $(element), ancestor = $(ancestor); @@ -403,6 +684,11 @@ Element.Methods = { return false; }, + /** + * Element.scrollTo(@element) -> Element + * + * Scrolls the window so that `element` appears at the top of the viewport. + **/ scrollTo: function(element) { element = $(element); var pos = element.cumulativeOffset(); @@ -410,6 +696,14 @@ Element.Methods = { return element; }, + /** + * 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 + * (`fontSize`). + **/ getStyle: function(element, style) { element = $(element); style = style == 'float' ? 'cssFloat' : style.camelize(); @@ -422,10 +716,23 @@ Element.Methods = { return value == 'auto' ? null : value; }, + /** + * Element.getOpacity(@element) -> String | null + * + * Returns the opacity of the element. + **/ getOpacity: function(element) { return $(element).getStyle('opacity'); }, + /** + * Element.setStyle(@element, styles) -> Element + * + * Modifies `element`’s CSS style properties. + * + * Styles are passed as an object of property-value pairs in which the + * properties are specified in their camelized form (e.g., `fontSize`). + **/ setStyle: function(element, styles) { element = $(element); var elementStyle = element.style, match; @@ -444,6 +751,11 @@ Element.Methods = { return element; }, + /** + * Element.setOpacity(@element, value) -> Element + * + * Sets the opacity of `element`. + **/ setOpacity: function(element, value) { element = $(element); element.style.opacity = (value == 1 || value === '') ? '' : @@ -451,6 +763,12 @@ Element.Methods = { return element; }, + /** + * Element.getDimensions(@element) -> Object + * + * Finds the computed width and height of `element` and returns them as + * key/value pairs of an object. + **/ getDimensions: function(element) { element = $(element); var display = element.getStyle('display'); @@ -475,6 +793,13 @@ Element.Methods = { return {width: originalWidth, height: originalHeight}; }, + /** + * 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`. + **/ makePositioned: function(element) { element = $(element); var pos = Element.getStyle(element, 'position'); @@ -490,7 +815,13 @@ Element.Methods = { } return element; }, - + + /** + * Element.undoPositioned(@element) -> Element + * + * Sets `element` back to the state it was in _before_ + * [[Element.makePositioned]] was applied to it. + **/ undoPositioned: function(element) { element = $(element); if (element._madePositioned) { @@ -504,6 +835,12 @@ Element.Methods = { return element; }, + /** + * Element.makeClipping(@element) -> Element + * + * Simulates the poorly-supported CSS `clip` property by setting `element`'s + * `overflow` value to `hidden`. + **/ makeClipping: function(element) { element = $(element); if (element._overflow) return element; @@ -513,6 +850,12 @@ Element.Methods = { return element; }, + /** + * Element.undoClipping(@element) -> Element + * + * Sets `element`’s CSS `overflow` property back to the value it had + * _before_ [[Element.makeClipping]] was applied. + **/ undoClipping: function(element) { element = $(element); if (!element._overflow) return element; @@ -521,6 +864,15 @@ Element.Methods = { return element; }, + /** + * Element.cumulativeOffset(@element) -> Array + * + * Returns the offsets of `element` from the top left corner of the + * document. + * + * Returns an array in the form of `[leftValue, topValue]`. Also accessible + * as properties: `{ left: leftValue, top: topValue }`. + **/ cumulativeOffset: function(element) { var valueT = 0, valueL = 0; do { @@ -531,6 +883,15 @@ Element.Methods = { return Element._returnOffset(valueL, valueT); }, + /** + * Element.positionedOffset(@element) -> Array + * + * Returns `element`’s offset relative to its closest positioned ancestor + * (the element that would be returned by [[Element.getOffsetParent]]). + * + * Returns an array in the form of `[leftValue, topValue]`. Also accessible + * as properties: `{ left: leftValue, top: topValue }`. + **/ positionedOffset: function(element) { var valueT = 0, valueL = 0; do { @@ -546,10 +907,15 @@ Element.Methods = { return Element._returnOffset(valueL, valueT); }, + /** + * Element.absolutize(@element) -> Element + * + * Turns `element` into an absolutely-positioned element _without_ changing + * its position in the page layout. + **/ absolutize: function(element) { element = $(element); if (element.getStyle('position') == 'absolute') return element; - // Position.prepare(); // To be done manually by Scripty when it needs it. var offsets = element.positionedOffset(); var top = offsets[1]; @@ -570,10 +936,17 @@ Element.Methods = { return element; }, + /** + * Element.relativize(@element) -> Element + * + * Turns `element` into a relatively-positioned element without changing + * its position in the page layout. + * + * Used to undo a call to [[Element.absolutize]]. + **/ relativize: function(element) { element = $(element); if (element.getStyle('position') == 'relative') return element; - // Position.prepare(); // To be done manually by Scripty when it needs it. element.style.position = 'relative'; var top = parseFloat(element.style.top || 0) - (element._originalTop || 0); @@ -586,6 +959,15 @@ Element.Methods = { return element; }, + /** + * Element.cumulativeScrollOffset(@element) -> Array + * + * Calculates the cumulative scroll offset of an element in nested + * scrolling containers. + * + * Returns an array in the form of `[leftValue, topValue]`. Also accessible + * as properties: `{ left: leftValue, top: topValue }`. + **/ cumulativeScrollOffset: function(element) { var valueT = 0, valueL = 0; do { @@ -596,6 +978,12 @@ Element.Methods = { return Element._returnOffset(valueL, valueT); }, + /** + * Element.getOffsetParent(@element) -> Element + * + * Returns `element`’s closest _positioned_ ancestor. If none is found, the + * `body` element is returned. + **/ getOffsetParent: function(element) { if (element.offsetParent) return $(element.offsetParent); if (element == document.body) return $(element); @@ -607,6 +995,14 @@ Element.Methods = { return $(document.body); }, + /** + * Element.viewportOffset(@element) -> Array + * + * Returns the X/Y coordinates of element relative to the viewport. + * + * Returns an array in the form of `[leftValue, topValue]`. Also accessible + * as properties: `{ left: leftValue, top: topValue }`. + **/ viewportOffset: function(forElement) { var valueT = 0, valueL = 0; @@ -631,7 +1027,19 @@ Element.Methods = { return Element._returnOffset(valueL, valueT); }, - + + /** + * Element.clonePosition(@element, source[, options]) -> Element + * + * Clones the position and/or dimensions of `source` onto `element` as + * defined by `options`. + * + * Valid keys for `options` are: `setLeft`, `setTop`, `setWidth`, and + * `setHeight` (all booleans which default to `true`); and `offsetTop` + * and `offsetLeft` (numbers which default to `0`). Use these to control + * which aspects of `source`'s layout are cloned and how much to offset + * the resulting position of `element`. + **/ clonePosition: function(element, source) { var options = Object.extend({ setLeft: true, @@ -673,7 +1081,14 @@ Element.Methods = { }; Object.extend(Element.Methods, { + /** alias of: Element.select + * Element.getElementsBySelector(@element, selector) -> [Element...] + **/ getElementsBySelector: Element.Methods.select, + + /** alias of: Element.immediateDescendants + * Element.childElements(@element) -> [Element...] + **/ childElements: Element.Methods.immediateDescendants }); @@ -1078,6 +1493,15 @@ Object.extend(Element, Element.Methods); })(document.createElement('div')) +/** + * Element.extend(element) -> Element + * + * Extends `element` with all of the methods contained in `Element.Methods` + * and `Element.Methods.Simulated`. + * If `element` is an `input`, `textarea`, or `select` tag, it will also be + * extended with the methods from `Form.Element.Methods`. If it is a `form` + * tag, it will also be extended with the methods from `Form.Methods`. +**/ Element.extend = (function() { if (Prototype.BrowserFeatures.SpecificElementExtensions) return Prototype.K; @@ -1122,6 +1546,16 @@ Element.hasAttribute = function(element, attribute) { return Element.Methods.Simulated.hasAttribute(element, attribute); }; +/** + * Element.addMethods(methods) -> undefined + * Element.addMethods(tagName, methods) -> undefined + * + * Takes a hash of methods and makes them available as methods of extended + * elements and of the `Element` object. + * + * The second usage form is for adding methods only to specific tag names. + * +**/ Element.addMethods = function(methods) { var F = Prototype.BrowserFeatures, T = Element.Methods.ByTag; @@ -1213,11 +1647,31 @@ Element.addMethods = function(methods) { Element.cache = { }; }; +/** section: dom + * document.viewport +**/ + document.viewport = { + + /** + * document.viewport.getDimensions() -> Object + * + * Returns the size of the viewport. + * + * Returns an object of the form `{ width: Number, height: Number }`. + **/ getDimensions: function() { return { width: this.getWidth(), height: this.getHeight() }; }, + /** + * document.viewport.getScrollOffsets() -> Array + * + * Returns the viewport’s horizontal and vertical scroll offsets. + * + * Returns an array in the form of `[leftValue, topValue]`. Also accessible + * as properties: `{ left: leftValue, top: topValue }`. + **/ getScrollOffsets: function() { return Element._returnOffset( window.pageXOffset || document.documentElement.scrollLeft || document.body.scrollLeft, @@ -1248,8 +1702,19 @@ document.viewport = { viewport['get' + D] = function() { return element[property[D]] }; return viewport['get' + D](); } - + + /** + * document.viewport.getWidth() -> Number + * + * Returns the width of the viewport. + **/ viewport.getWidth = define.curry('Width'); + + /** + * document.viewport.getHeight() -> Number + * + * Returns the height of the viewport. + **/ viewport.getHeight = define.curry('Height'); })(document.viewport); @@ -1259,6 +1724,11 @@ Element.Storage = { }; Element.addMethods({ + /** + * Element.getStorage(@element) -> Hash + * + * Returns the [[Hash]] object that stores custom metadata for this element. + **/ getStorage: function(element) { if (!(element = $(element))) return; @@ -1277,6 +1747,13 @@ Element.addMethods({ return Element.Storage[uid]; }, + /** + * Element.store(@element, key, value) -> Element + * + * Stores a key/value pair of custom metadata on the element. + * + * The metadata can later be retrieved with [[Element.retrieve]]. + **/ store: function(element, key, value) { if (!(element = $(element))) return; @@ -1290,6 +1767,14 @@ Element.addMethods({ return element; }, + /** + * Element.retrieve(@element, key[, defaultValue]) -> ? + * + * Retrieves custom metadata set on `element` with [[Element.store]]. + * + * If the value is `undefined` and `defaultValue` is given, it will be + * stored on the element as its new value for that key, then returned. + **/ retrieve: function(element, key, defaultValue) { if (!(element = $(element))) return; var hash = Element.getStorage(element), value = hash.get(key);