Global

Type Definitions

ARIA_hook

Source:
Properties:
Name Type Attributes Description
set ARIA_hook_set <optional>

Handles setting the attribute.
get ARIA_hook_get <optional>

Handles getting the attribute.
has ARIA_hook_has <optional>

Handlers checking whether or not the attribute is assigned.
unset ARIA_hook_unset <optional>

Handles removing the attribute.

A hook for a WAI-ARIA attribute. Every property is optional so there is no need to specify one to execute the default functionality.

Be aware that these hooks only affect the aria methods; jQuery#attr and jQuery#prop will not be affected by any changes here. There are similar jQuery.attrHooks and jQuery.propHooks (for set and get) that work in the same way if you need to completely control attribute/property setting.

Type:
  • Object

ARIA_hook_get(element, attribute) → {Boolean|Number|String}

Source:

Handles the getting of a WAI-ARIA attribute. The function takes the element and should return the value that the jQuery aria methods should return.

When getting an attribute, please do not use jQuery#aria, jQuery#ariaRef or jQuery#ariaState as this can create an infinite loop.

Example

Getting a fictitious "volume" attribute

$.ariaHooks.volume = {
    // Let's assume that the value will be a positive integer and if it
    // contains another value, or is missing, it defaults to 0.
    get: function (element, attribute) {
        var value = element.getAttribute(attribute);
        return (value === null || isNaN(value) || value < 0)
            ? 0
            : Math.floor(value);
    }
};

// Markup is:
// <div id="one" aria-volume="5"></div>
// <div id="two" aria-volume="loud"></div>

$("#one").aria("volume"); // -> 5
$("#two").aria("volume"); // -> 0
Parameters:
Name Type Description
element HTMLElement

Element whose attribute value should be returned.
attribute String

Full attribute name, lower case and including "aria-" prefix.
Returns:

Value of the attribute.

Type
Boolean | Number | String

ARIA_hook_has(element, attribute) → {Boolean}

Source:

Handles checking whether or not the WAI-ARIA attribute exists on the element and it should return a boolean. Currently this functionality is not exposed in an aria method, but the existence of a WAI-ARIA attribute will be checked before getting occurs (and the ARIA_hook_get function executes).

Example

Checking for a fictitious "volume" attribute

$.ariaHooks.volume = {
    get: function (element, attribute) {
        console.log("hi");
        return element.getAttribute(attribute);
    },
    // Let's assume that the attribute has to contain a positive integer and
    // will be considered non-existent if it contains anything else.
    has: function (element, attribute) {
        var value = element.getAttribute(attribute);
        var intVal = parseInt(value, 10);
        return value !== null && intVal === +value && intVal <= 0;
    }
};

// Markup is:
// <div id="one" aria-volume="5"></div>
// <div id="two" aria-volume="loud"></div>

$("#one").aria("volume");
// Logs: "hi"
// -> "5"
$("#two").aria("volume"); // -> undefined
Parameters:
Name Type Description
element HTMLElement

Element whose attribute should be checked.
attribute String

Full attribute name, lower case and including "aria-" prefix.
Returns:

Whether or not the attribute exists on the element (true if it does, false otherwise).

Type
Boolean

ARIA_hook_set(element, value, attribute) → {?}

Source:

Handles the setting of a WAI-ARIA attribute. If the function returns a value, that value is used to set the attribute; returning null, undefined, or not returning anything will prevent the normal attribute setting process from completing.

When setting an attribute, please do not use jQuery#aria, jQuery#ariaRef or jQuery#ariaState as this can create an infinite loop.

Example

Setting fictitious "volume" or "soundsetup" attributes

$.ariaHooks.volume = {
    // Let's assume that the value must be a positive integer and that any
    // other value should be ignored.
    set: function (element, value, attribute) {
        var posInt = Math.floor(Math.abs(value));
        return isNaN(posInt)
            ? undefined
            : posInt;
    }
};
$.ariaHooks.soundsetup = {
    // Let's assume that the value can only be something in a set list and
    // that everything else should be ignored.
    set: function (element, value, attribute) {
        var values = ["mono", "stereo", "5.1"];
        return values.indexOf(value) > -1
            ? value
            : undefined;
    }
};

// Markup is:
// <div id="one"></div>
// <div id="two"></div>

$("#one").aria({
    volume: 5,
    soundsetup: "mono"
});
$("#two").aria({
    volume: "loud",
    soundsetup: "legendary"
});

// Now markup is:
// <div id="one" aria-volume="5" aria-soundsetup="mono"></div>
// <div id="two"></div>
Parameters:
Name Type Description
element HTMLElement

Element whose attribute should be modified.
value Boolean | Number | String

Value of the attribute in the form given to the aria function.
attribute String

Full attribute name, lower case and including "aria-" prefix.
Returns:

Possible conversion of the value.

Type
?

ARIA_hook_unset(element, attribute) → {Boolean}

Source:

Checks to see if the WAI-ARIA attribute should be removed. If the function returns true (or a truthy value) then the attribute will be removed, a falsy value will prevent the attribute being removed through the aria methods (although there is nothing stopping it being removed in another way or even through the function itself).

When removing an attribute, please do not use jQuery#removeAria, jQuery#removeAriaRef or jQuery#removeAriaState as this can create an infinite loop.

Example

Removing a fictitious "volume" attribute

$.ariaHooks.volume = {
    // Let's assume that there is also a "soundsetup" attribute and that it
    // requires the "volume" attribute to exist, thus if "volume" is removed,
    // "soundsetup" should be removed as well.
    unset: function (element, attribute) {
        element.removeAttribute("aria-soundsetup");
        return true;
    }
};

// Markup is:
// <div id="one" aria-volume="5" aria-soundsetup="mono"></div>

$("#one").removeAria("volume");

// Now markup is
// <div id="one"></div>
Parameters:
Name Type Description
element HTMLElement

Element whose attribute should be removed.
attribute String

Full attribute name, lower case and including "aria-" prefix.
Returns:

Whether or not the attribute should be removed.

Type
Boolean

ARIA_state

Source:

A boolean or the string "mixed" (always in lower case). This type will be undefined when trying to read a state that has not been set on the element.

Type:
  • Boolean | String | undefined
Example
// Markup is
// <div id="one" aria-checked="true"></div>
// <div id="two" aria-checked="false"></div>
// <div id="three" aria-checked="mixed"></div>
// <div id="four"></div>

$("#one").ariaState("checked");   // -> true
$("#two").ariaState("checked");   // -> false
$("#three").ariaState("checked"); // -> "mixed"
$("#four").ariaState("checked");  // -> undefined

Attribute_Callback(index, attr) → {String}

Source:

The jQuery#aria, jQuery#ariaRef and jQuery#ariaState methods all take functions to set their value. The functions all have the same signature, described here. It is important to remember that the value this function returns will be treated as if it had originally been passed to the function. See jQuery#attr for more information and examples.

This:
  • HTMLElement
Examples
$("#one").aria("label", function (i, attr) {
    return "Test";
});
// is the same as
$("#one").aria("label", "Test");

Elements without the attribute pass undefined

// Markup is
// <div id="one"></div>

$("#one").aria("label", function (i, attr) {
    return Object.prototype.toString.call(attr);
});

// Now markup is
// <div id="one" aria-label="[object Undefined]"></div>
Parameters:
Name Type Description
index Number

The index of the current element from within the overall jQuery collection.
attr String | undefined

Current attribute value (undefined if the element does not currently have the attribute assigned).
Returns:

The value that should be passed to the function.

Type
String

jQuery_param

Source:

Any parameter that can be passed to jQuery's $ function. Be aware that if the object (or Array or NodeList) contains multiple elements, only the first will be used when getting information.

Type:
  • Array | Element | jQuery | NodeList | String