/*
Namespace: Mindscape.dom
  A namespace that provides document object model helpers for the Mindscape JavaScript application architecture framework.
*/
Mindscape.dom = Mindscape.dom || {

    /*
    Function: find
    The function for finding DOM elements. Delegates to jQuery().find.

    Parameters:
    selector - The string that indentifies the DOM elements.
    context - The object that contains other elements to be found.
    */
    find: function (selector, context) {
        var self = this, elements;

        if (context && context.find) {
            elements = context.find(selector);
        } else {
            elements = $m.jQuery(selector);
        }

        var ret = elements.get();
        ret.length = elements.length;
        ret.find = function (selector) {
            return self.find(selector, elements);
        };
        return ret;
    },

    /*
    Function: bind
    The function for binding event functions to DOM elements. Delegates to jQuery().bind.

    Parameters:
    element - The DOM element to bind to.
    event - The event to bind to.
    func - The function to bind.

    See:
    <unbind>
    */
    bind: function (element, event, func) {
        if (element && event) {
            if (typeof event === 'function') {
                func = event;
                event = 'click';
            }
            $m.jQuery(element).bind(event, func);
        } else {
            // TODO: log wrong arguments
        }
    },

    /*
    Function: unbind
    The function for unbinding event functions from DOM elements. Delegates to jQuery().unbind.

    Parameters:
    element - The DOM element to unbind from.
    event - The event to unbind from.
    func - The function to unbind.

    See:
    <bind>
    */
    unbind: function (element, event, func) {
        if (element && event) {
            if (typeof event === 'function') {
                func = event;
                event = 'click';
            }
            $m.jQuery(element).unbind(event, func);
        } else {
            // TODO: log wrong arguments
        }
    },

    /*
    Function: createElement
    The function for creating a new DOM element.

    Parameters:
    tag - The HTML tag to be created as a DOM element.
    settings - The settings to be applied to the new DOM element.

    See:
    <applyAttributes>
    */
    createElement: function (tag, settings) {
        var element = document.createElement(tag);
        if (settings) {
            if (settings.children && Mindscape.util.isArray(settings.children)) {
                if (settings.children && Mindscape.util.isArray(settings.children)) {
                    var i, length = settings.children.length;
                    for (i = 0; i < length; i++) {
                        element.appendChild(settings.children[i]);
                    }
                    delete settings.children;
                }
            }
            if (settings.text) {
                element.appendChild(document.createTextNode(settings.text));
                delete settings.text;
            }
            Mindscape.dom.applyAttributes(element, settings);
        }
        return element;
    },

    /*
    Function: applyAttributes
    The function for applying attributes to a DOM element. Delegates to jQuery().attr.

    Parameters:
    element - The DOM element to apply attributes to.
    attributes - The attributes to appy to the DOM element.

    See:
    <createElement>
    */
    applyAttributes: function (element, attributes) {
        $m.jQuery(element).attr(attributes);
    },

    /*
    Function: getAttributes
    The function for applying attributes to a DOM element. Delegates to jQuery().attr.

    Parameters:
    element - The DOM element to apply attributes to.
    attribute - The attribute to get from the selected elelment.

    See:
    <createElement>
    */
    getAttribute: function (element, attribute) {
        return $m.jQuery(element).attr(attribute);
    },

    /*
    Function: hasClass
    The function for checking if DOM element has a css class.

    Parameters:
    element - The DOM element to be checked.
    className - The css class name to check for.

    See:
    <addClass>
    <removeClass>
    <toggleClass>
    */
    hasClass: function (element, className) {
        var classRegex = new RegExp('(\\s|^)' + className + '(\\s|$)');
        return element.className.match(classRegex);
    },

    /*
    Function: addClass
    The function for adding a css class to a DOM element.

    Parameters:
    element - The DOM element to be modified.
    className - The css class name to add.

    See:
    <hasClass>
    <removeClass>
    <toggleClass>
    */
    addClass: function (element, className) {
        if (!this.hasClass(element, className)) {
            element.className += ' ' + className;
        }
    },

    /*
    Function: removeClass
    The function for removing a css class from a DOM element.

    Parameters:
    element - The DOM element to be modified.
    className - The css class name to remove.

    See:
    <hasClass>
    <addClass>
    <toggleClass>
    */
    removeClass: function (element, className) {
        if (this.hasClass(element, className)) {
            var classRegex = new RegExp('(\\s|^)' + className + '(\\s|$)');
            element.className = element.className.replace(classRegex, ' ');
        }
    },

    /*
    Function: toggleClass
    The function for toggling (adding or removing) a css class from a DOM element.

    Parameters:
    element - The DOM element to be modified.
    className - The css class to toggle.

    See:
    <hasClass>
    <addClass>
    <removeClass>
    */
    toggleClass: function (element, className) {
        var classRegex = new RegExp('(\\s|^)' + className + '(\\s|$)');
        if (element.className.match(classRegex)) {
            element.className = element.className.replace(classRegex, ' ');
        } else {
            element.className += ' ' + className;
        }
    },

    /*
    Function: applyCSS
    The function for applying css to a DOM element. Delegates to jQuery().css.

    Parameters:
    element - The DOM element to be modified.
    cssProperty - The css property to be modified. (ie: background-color).
    cssValue - The value of the property to be modified. (ie: #ff0000);
    */
    applyCSS: function (element, cssProperty, cssValue) {

        $m.jQuery(element).css(cssProperty, cssValue);

    },

    /*
    Function: getChildren
    The function for getting the children of a DOM element. Delegates to jQuery().children().

    Parameters:
    element - The DOM elelment from which to select the children.
    selector - A string containing a selector expression to match elements against.
    */
    getChildren: function (element, selector) {

        return $m.jQuery(element).children(selector);

    },

    /*
    Function: fadeIn
    The function for fading in a DOM element. Delegates to jQuery().fadeIn().

    Parameters:
    element - The DOM element to fade in.
    duration - A string or number determining how long the animation will run.
    easing - A string indicating which easing function to use for the transition.
    callback - A function to call once the animation is complete.
    */
    fadeIn: function (element, duration, easing, callback) {

        $m.jQuery(element).fadeIn(duration, easing, callback);

    },

    /*
    Function: fadeOut
    The function for fading out a DOM element. Delegates to jQuery().fadeOut().

    Parameters:
    element - The DOM element to fade out.
    duration - A string or number determining how long the animation will run.
    easing - A string indicating which easing function to use for the transition.
    callback - A function to call once the animation is complete.
    */
    fadeOut: function (element, duration, easing, callback) {

        $m.jQuery(element).fadeOut(duration, easing, callback);

    },

    /*
    Function: animate
    The function for creating an animation for a DOM element. Delegates to jQuery().animate().

    Parameters:
    element - The DOM element to fade out.
    properties - A map of CSS properties that the animation will move toward.
    duration - A string or number determining how long the animation will run.
    easing - A string indicating which easing function to use for the transition.
    callback - A function to call once the animation is complete.
    */
    animate: function (element, properties, duration, easing, callback) {

        $m.jQuery(element).animate(properties, duration, easing, callback);

    },

    /*
    Function: not
    Removes elements from the set of matched elements. Delegates to jQuery().not().

    Parameters:
    element - The DOM element to fade out.
    selector - A string containing a selector expression to match elements against.
    This also can be one or more DOM elements to remove from the matched
    set or a function used as a test for each elelment in the set. 'this'
    is the current DOM element.
    */
    not: function (element, selector) {

        $m.jQuery(element).not(selector);

    },

    /*
    Function: next
    Get the immediately following sibling of each element in the set of matched elements. 
    If a selector is provided, it retrieves the next sibling only if it matches that selector. 
    
    Delegates to jQuery().next().

    Parameters:
    element - The DOM element to fade out.
    selector - A string containing a selector expression to match elements against.
    */
    next: function (element, selector) {

        return $m.jQuery(element).next(selector);

    },

    /*
    Function: getParent
    Get the imediate ancestor of each element in the current set of matched elements, optionally filtered by a selector. 
    
    Delegates to jQuery().parent().

    Parameters:
    element - The DOM element to fade out.
    selector - A string containing a selector expression to match elements against.
    */
    getParent: function (element, selector) {

        return $m.jQuery(element).parent(selector);

    },

    /*
    Function: getParents
    Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector. 
    
    Delegates to jQuery().parents().

    Parameters:
    element - The DOM element to fade out.
    selector - A string containing a selector expression to match elements against.
    */
    getParents: function (element, selector) {

        return $m.jQuery(element).parents(selector);

    },

    /*
    Function: getOffset
    Get the current coordinates of the first element in the set of matched elements, relative to the document. 
    
    Delegates to jQuery().offset().

    Parameters:
    element - The DOM element to get current coordinates.
    */
    getOffset: function (element) {

        return $m.jQuery(element).offset();

    },

    /*
    Function: getHeight
    Get the current computed height for the first element in the set of matched elements.
    
    Delegates to jQuery().height().

    Parameters:
    element - The DOM element to get current coordinates.
    value - The value to set the DOM elemlent height to
    */
    getHeight: function (element) {

        return $m.jQuery(element).height();

    },

    /*
    Function: getValue
    Get the current value of the first element in the set of matched elements.
    
    Delegates to jQuery().val().

    Parameters:
    element - The DOM element to set/get the value of.
    */
    getValue: function (element) {

        return $m.jQuery(element).val();

    },

    /*
    Function: setValue
    Set the current value of the first element in the set of matched elements.
    
    Delegates to jQuery().val().

    Parameters:
    element - The DOM element to set/get the value of.
    value = The value to set/get
    */
    setValue: function (element, value) {

        $m.jQuery(element).val(value);

    },

    /*
    Function: is
    Check the current matched set of elements against a selector, element, 
    or jQuery object and return true if at least one of these elements matches the given arguments.
    
    Delegates to jQuery().is().

    Parameters:
    element - The DOM element to set/get the value of.
    value = The value to set/get
    */
    is: function (element, value) {

        return $m.jQuery(element).is(value);

    },

    /*
    Function: hide
    Hide the matched elements.
    
    Delegates to jQuery().hide().

    Parameters:
    element - The DOM element to set/get the value of.
    duration - The amount of time the animation takes.  (milliseconds)
    easing - Specifies the type of easing for the animation.
    callback - Method to run when animation is complete.
    */
    hide: function (element, duration, easing, callback) {

        $m.jQuery(element).hide(duration, easing, callback);

    },

    /*
    Function: show
    Display the matched elements.
    
    Delegates to jQuery().show().

    Parameters:
    element - The DOM element to set/get the value of.
    duration - The amount of time the animation takes.  (milliseconds)
    easing - Specifies the type of easing for the animation.
    callback - Method to run when animation is complete.
    */
    show: function (element, duration, easing, callback) {

        $m.jQuery(element).show(duration, easing, callback);

    },

    /*
    Function: delay
    Set a timer to delay execution of subsequent items in the queue.
    
    Delegates to jQuery().delay().

    Parameters:
    duration - An integer indicating the number of milliseconds to delay execution of the next item in the queue.
    [queueName] - A string containing the name of the queue. Defaults to fx, the standard effects queue.

    */
    delay: function (element, duration, queueName) {

        $m.jQuery().delay(duration, queueName);

    },

    /*
    Function: getHtml
    Get the HTML contents of the first element in the set of matched elements.
    
    Delegates to jQuery().html().

    Parameters:
    element - The DOM element to set/get the value of.

    */
    getHtml: function (element) {

        return $m.jQuery(element).html();

    },

    /*
    Function: settHtml
    Sets the HTML contents of the first element in the set of matched elements.
    
    Delegates to jQuery().html(htmlString).

    Parameters:
    element - The DOM element to set/get the value of.
    htmlString

    */
    setHtml: function (element, htmlString) {

        $m.jQuery(element).html(htmlString);

    }
};