Prototype JavaScript framework - Element

setOpacity

2008-01-08T23:14:00Z

Element.setOpacity(element, opacity) -> [HTMLElement...]
someElement.setOpacity(opacity) -> [HTMLElement...]

Sets the visual opacity of an element while working around inconsistencies in various browsers. The opacity argument should be a floating point number, where the value of 0 is fully transparent and 1 is fully opaque.

Element.setStyle method uses setOpacity internally when needed.

Examples

var element = $('myelement');
// set to 50% transparency
element.setOpacity(0.5);

// these are equivalent, but allow for setting more than
// one CSS property at once:
element.setStyle({ opacity: 0.5 });
element.setStyle("opacity: 0.5");

adjacent

2007-12-05T01:30:00Z

Element.adjacent(element[, selectors...]) -> [HTMLElement...]
someElement.adjacent([selectors...]) -> [HTMLElement...]

Finds all siblings of the current element that match the given selector(s).

Examples

<ul id="cities">
    <li class="us" id="nyc">New York</li>
    <li class="uk" id="lon">London</li>
    <li class="us" id="chi">Chicago</li>
    <li class="jp" id="tok">Tokyo</li>
    <li class="us" id="la">Los Angeles</li>
    <li class="us" id="aus">Austin</li>
  </ul>

$('nyc').adjacent('li.us');
//-> [<li#chi, li#la, li#aus>]

wrap

2007-11-27T20:18:00Z

Element.wrap(element, wrapper[, attributes]) -> HTMLElement
someElement.wrap(wrapper[, attributes]) -> HTMLElement

Wraps an element inside another, then returns the wrapper.

Using wrap as an instance method (e.g., $('foo').wrap('p')) causes errors in Internet Explorer when used on textarea elements. The wrap property is reserved on textareas as a proprietary extension to HTML. As a workaround, use the generic version instead (Element.wrap('foo', 'p')).

If the given element exists on the page, Element#wrap will wrap it in place — its position will remain the same.

The wrapper argument can be either an existing HTMLElement or a string representing the tag name of an element to be created. The optional attributes argument can contain a list of attribute/value pairs that will be set on the wrapper using Element#writeAttribute.

Examples

Original HTML

<table id="data">
  <tr>
    <th>Foo</th>
    <th>Bar</th>
  </tr>
  <tr>
    <td>1</td>
    <td>2</td>
  </tr>
</table>

JavaScript

// approach 1:
var div = new Element('div', { 'class': 'table-wrapper' });
$('data').wrap(div);

// approach 2:
$('data').wrap('div', { 'class': 'table-wrapper' });

// examples are equivalent. both return the DIV.

Resulting HTML

<div class="table-wrapper">
  <table id="data">
    <tr>
      <th>Foo</th>
      <th>Bar</th>
    </tr>
    <tr>
      <td>1</td>
      <td>2</td>
    </tr>
  </table>
</div>

viewportOffset

2007-11-08T01:04:00Z

viewportOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Returns the X/Y coordinates of element relative to the viewport.

Note that all values are returned as numbers only although they are expressed in pixels.

getOffsetParent

2007-11-08T01:01:00Z

getOffsetParent(element) -> HTMLElement

Returns element’s closest positioned ancestor. If none is found, the body element is returned.

The returned element is element’s CSS containing block.

positionedOffset

2007-11-08T00:54:00Z

positionedOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Returns element’s offset relative to its closest positioned ancestor (the element that would be returned by Element#getOffsetParent).

Calculates the cumulative offsetLeft and offsetTop of an element and all its parents until it reaches an element with a position of static.

Note that all values are returned as numbers only although they are expressed in pixels.

cumulativeScrollOffset

2007-11-08T00:50:00Z

cumulativeScrollOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Calculates the cumulative scroll offset of an element in nested scrolling containers.

Adds the cumulative scrollLeft and scrollTop of an element and all its parents.

Used for calculating the scroll offset of an element that is in more than one scroll container (e.g., a draggable in a scrolling container which is itself part of a scrolling document).

Note that all values are returned as numbers only although they are expressed in pixels.

cumulativeOffset

2007-11-08T00:41:00Z

cumulativeOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Returns the offsets of element from the top left corner of the document.

Adds the cumulative offsetLeft and offsetTop of an element and all its parents.

Note that all values are returned as numbers only although they are expressed in pixels.

clonePosition

2007-11-07T20:42:00Z

clonePosition(element, source[, options]) -> HTMLElement

Clones the position and/or dimensions of source onto element as defined by the optional argument options.

Note that target will be positioned exactly like source whether or not it is part of the same CSS containing block.

Options

Name	Default	Description
`setLeft`	`true`	clones `source`’s `left` CSS property onto `element`.
`setTop`	`true`	clones `source`’s `top` CSS property onto `element`.
`setWidth`	`true`	clones `source`’s `width` onto `element`.
`setHeight`	`true`	clones `source`’s `width` onto `element`.
`offsetLeft`	`0`	Number by which to offset `element`’s `left` CSS property.
`offsetTop`	`0`	Number by which to offset `element`’s `top` CSS property.

relativize

2007-11-07T20:38:00Z

relativize(element) -> HTMLElement

Turns element into an relatively-positioned element without changing its position in the page layout.

absolutize

2007-11-07T20:31:00Z

absolutize(element) -> HTMLElement

Turns element into an absolutely-positioned element without changing its position in the page layout.

select

2007-11-06T13:26:00Z

select(element, selector...) -> [HTMLElement...]

Takes an arbitrary number of CSS selectors (strings) and returns an array of extended descendants of element that match any of them.

This method is very similar to $$() but can be used within the context of one element, rather than the whole document. The supported CSS syntax is identical, so please refer to the $$() docs for details.

Examples

<ul id="fruits">
  <li id="apples">
    <h3 title="yummy!">Apples</h3>
    <ul id="list-of-apples">
      <li id="golden-delicious" title="yummy!" >Golden Delicious</li>
      <li id="mutsu" title="yummy!">Mutsu</li>
      <li id="mcintosh">McIntosh</li>
      <li id="ida-red">Ida Red</li>
    </ul>
    <p id="saying">An apple a day keeps the doctor away.</p>  
  </li>
</ul>

$('apples').select('[title="yummy!"]');
// -> [h3, li#golden-delicious, li#mutsu]

$('apples').select( 'p#saying', 'li[title="yummy!"]');
// -> [li#golden-delicious, li#mutsu,  p#saying]

$('apples').select('[title="disgusting!"]');
// -> []

Tip

Element#select can be used as a pleasant alternative to the native method getElementsByTagName:

var nodes  = $A(someUL.getElementsByTagName('li')).map(Element.extend);
var nodes2 = someUL.select('li');

In the first example, you must explicitly convert the result set to an Array (so that Prototype’s Enumerable methods can be used) and must manually call Element.extend on each node (so that custom instance methods can be used on the nodes). Element#select takes care of both concerns on its own.

If you’re using 1.6 or above (and the performance optimizations therein), the speed difference between these two examples is negligible.

identify

2007-11-06T12:59:00Z

identify(element) -> id

returns element’s id attribute if it exists, or sets and returns a unique, auto-generated id.

Examples

Original HTML


  <ul>
    <li id="apple">apple</li>
    <li>orange</li>
  </ul>

JavaScript


  $('apple').identify();
  // -> 'apple'

  $('apple').next().identify();
  // -> 'anonymous_element_1'

resulting HTML


  <ul>
    <li id="apple">apple</li>
    <li id="anonymous_element_1">orange</li>
  </ul>

insert

2007-11-06T12:40:00Z

insert(element, { position: content }) -> HTMLElement
insert(element, content) -> HTMLElement

Inserts content before, after, at the top of, or at the bottom of element, as specified by the position property of the second argument. If the second argument is the content itself, insert will append it to element.

insert accepts the following kind of content: text, HTML, DOM element, and any kind of object with a toHTML or toElement method.

Note that if the inserted HTML contains any <script> tag, these will be automatically evaluated after the insertion (insert internally calls String#evalScripts when inserting HTML).

fire

2007-11-06T02:40:00Z

fire(eventName[, memo]) -> Event

Fires a custom event with the current element as its target.

Element#fire creates a custom event with the given name, then triggers it on the given element. The custom event has all the same properties and methods of native events. Like a native event, it will bubble up through the DOM unless its propagation is explicitly stopped.

The optional second argument will be assigned to the memo property of the event object so that it can be read by event handlers.

Custom events are dispatched synchronously: Element#fire waits until the event finishes its life cycle, then returns the event itself.

Note

Element#fire does not support firing native events. All custom event names must be namespaced (using a colon). This is to avoid custom event names conflicting with non-standard native DOM events such as mousewheel and DOMMouseScroll.

Examples

document.observe("widget:frobbed", function(event) {
  console.log("Element with ID (" + event.target.id +
   ") frobbed widget #" + event.memo.widgetNumber + ".");
});

var someNode = $('foo');
someNode.fire("widget:frobbed", { widgetNumber: 19 });

//-> "Element with ID (foo) frobbed widget #19."

Tip

Events that have been stopped with Event#stop will have a boolean stopped property set to true. Since Element#fire returns the custom event, you can inspect this property to determine whether the event was stopped.