MochiKit.Style - painless Style manipulation API

Back to docs index

# Name

MochiKit.Style - painless Style manipulation API

# Synopsis

    var messagePos = getElementPosition('message');
    var messageSize = getElementDimensions('message');

    var notifyPos = new MochiKit.Style.Coordinates(
         messagePos.x + messageSize.w + 10,
         messagePos.y);

    setElementPosition('notify', notifyPos);

# Description

Refactored from MochiKit.DOM.

# Dependencies

- MochiKit.Base
- MochiKit.DOM

# Overview

Refactored from MochiKit.DOM.

## Element Visibility

The hideElement and showElement functions are provided as a convenience, but only work for elements that are `display: block`. For a general solution to showing, hiding, and checking the explicit visibility of elements, we recommend using a solution that involves a little CSS. Here's an example:

    <style type="text/css">
        .invisible { display: none; }
    </style>

    <script type="text/javascript">
        function toggleVisible(elem) {
            toggleElementClass("invisible", elem);
        }

        function makeVisible(elem) {
            removeElementClass(elem, "invisible");
        }

        function makeInvisible(elem) {
            addElementClass(elem, "invisible");
        }

        function isVisible(elem) {
            // you may also want to check for
            // getElement(elem).style.display == "none"
            return !hasElementClass(elem, "invisible");
        };
    </script>

MochiKit doesn't ship with such a solution, because there is no reliable and portable method for adding CSS rules on the fly with JavaScript.

# API Reference

## Functions

getStyle(element, cssSelector):

> Looks up a CSS property for the given element. The element can be specified as either a string with the element's ID or the element object itself.

> `cssSelector`:
>   The CSS selector, e.g. `background-color`.
> Availability:
>   Available in MochiKit 1.4+

setStyle(element, styles):

> Set CSS properties on a the given element. The element can be specified as either a string with the element's ID or the element object itself.

> `styles`:
>   Dictionnary holding CSS properties to set, e.g. `{'background-color': 'red', 'opacity': 0.5}`.
> Availability:
>   Available in MochiKit 1.4+

setOpacity(element, opacity):

> Sets `opacity` for `element`. Valid `opacity` values range from 0 (invisible) to 1 (opaque). `element` is looked up with getElement, so string identifiers are also acceptable.

> Availability:
>   Available in MochiKit 1.4+

getElementDimensions(element[, contentSize=false]):

> Return the absolute pixel width and height of `element` as an object with `w` and `h` properties, or `undefined` if `element` is not in the document. The size will include padding and border, but not margins, unless `contentSize` is set to true, in which case the size will be only the content size, without padding and border. `element` may be specified as a string to be looked up with getElement, a DOM element, or trivially as an object with `w` and/or `h` properties.

> Availability:
>   Available in MochiKit 1.4+

setElementDimensions(element, dimensions[, units='px']):

> Sets the dimensions of `element` in the document from an object with `w` and `h` properties.

> Warning: IE in quirks-mode seems to behave strange when you set the height off an element containing text to 0. You can workaround this by setting the value of visibly/display.

> `element`:
>   A reference to the DOM element to update (if a string is given, getElement(node) will be used to locate the node)
> `dimensions`:
>   An object with `w` and `h` properties. You can also specify only one property.
> `units`:
>   Optionally set the units to use, default is `px`
> Availability:
>   Available in MochiKit 1.4+

getElementPosition(element[, relativeTo={x: 0, y: 0}]):

> Return the absolute pixel position of `element` in the document as an object with `x` and `y` properties, or `undefined` if `element` is not in the document. `element` may be specified as a string to be looked up with getElement, a DOM element, or trivially as an object with `x` and/or `y` properties.

> If `relativeTo` is given, then its coordinates are subtracted from the absolute position of `element`, e.g.:

>     var elemPos = getElementPosition(elem);
>     var anotherElemPos = getElementPosition(anotherElem);
>     var relPos = getElementPosition(elem, anotherElem);
>     assert( relPos.x == (elemPos.x - anotherElemPos.x) );
>     assert( relPos.y == (elemPos.y - anotherElemPos.y) );

> `relativeTo` may be specified as a string to be looked up with getElement, a DOM element, or trivially as an object with `x` and/or `y` properties.

> Availability:
>   Available in MochiKit 1.4+

setElementPosition(element, position[, units='px']):

> Sets the absolute position of `element` in the document from an object with `x` and `y` properties.

> `element`:
>   A reference to the DOM element to update (if a string is given, getElement(node) will be used to locate the node)
> `position`:
>   An object with `x` and `y` properties. You can also specify only one property.
> `units`:
>   Optionally set the units to use, default is `px`
> Availability:
>   Available in MochiKit 1.4+

makePositioned(element):

> Ensure that `element.style.position` is set to `"relative"` if it is not set or is `"static"`. If `element` is a string, then it will be looked up with getElement.

> Availability:
>   Available in MochiKit 1.4.1+

undoPositioned(element):

> Restore the setting of `element.style.position` set by makePositioned(element). If `element` is a string, then it will be looked up with getElement.

> Availability:
>   Available in MochiKit 1.4.1+

makeClipping(element):

> Ensure that `element.style.overflow = 'hidden'`. If `element` is a string, then it will be looked up with getElement.

> Returns the original values of `overflow`, `overflow-y` and `overflow-y` so that they may be restored with undoClipping(element, overflow).

> Availability:
>   Available in MochiKit 1.4.1+

undoClipping(element, overflow):

> Restore the setting of `element.style.overflow` set by makeClipping(element). If `element` is a string, then it will be looked up with getElement.

> Availability:
>   Available in MochiKit 1.4.1+

setDisplayForElement(display, element[, ...]):

> Change the `style.display` for the given element(s). Usually used as the partial forms:

> - showElement(element, ...)
> - hideElement(element, ...)

> Elements are looked up with getElement, so string identifiers are acceptable.

> For information about the caveats of using a `style.display` based show/hide mechanism, and a CSS based alternative, see Element Visibility.

> Availability:
>   Available in MochiKit 1.4+

showElement(element, ...):

> Partial form of setDisplayForElement, specifically:

>     partial(setDisplayForElement, "block")

> For information about the caveats of using a `style.display` based show/hide mechanism, and a CSS based alternative, see Element Visibility.

> Availability:
>   Available in MochiKit 1.4+

hideElement(element, ...):

> Partial form of setDisplayForElement, specifically:

>     partial(setDisplayForElement, "none")

> For information about the caveats of using a `style.display` based show/hide mechanism, and a CSS based alternative, see Element Visibility.

> Availability:
>   Available in MochiKit 1.4+

getViewportDimensions():

> Return the pixel width and height of the viewport as an object with `w` and `h` properties.

> Availability:
>   Available in MochiKit 1.4+

getViewportPosition():

> Return the pixel position of the viewport inside the window, as a Coordinates object.

> Availability:
>   Available in MochiKit 1.4+

## Objects

Coordinates(x, y):

> Constructs an object with `x` and `y` properties. `obj.toString()` returns something like `{x: 0, y: 42}` for debugging.

> Availability:
>   Available in MochiKit 1.4+

Dimensions(w, h):

> Constructs an object with `w` and `h` properties. `obj.toString()` returns something like `{w: 0, h: 42}` for debugging.

> Availability:
>   Available in MochiKit 1.4+

# Authors

- Bob Ippolito <bob@redivi.com>
- Beau Hartshorne <beau@hartshornesoftware.com>

# Copyright

Copyright 2005-2006 Bob Ippolito <bob@redivi.com>, and Beau Hartshorne <beau@hartshornesoftware.com>. This program is dual-licensed free software; you can redistribute it and/or modify it under the terms of the MIT License or the Academic Free License v2.1.