Expand all

abstract OO.ui.Element

Constructor

new OO.ui.Element([config])abstract #

Each Element represents a rendering in the DOM—a button or an icon, for example, or anything that is visible to a user. Unlike widgets, plain elements usually do not have events connected to them and can't be interacted with.

Parameters:

Name Type Attributes Description
config Object optional

Configuration options

Properties:
Name Type Attributes Description
classes Array.<string> optional

The names of the CSS classes to apply to the element. CSS styles are added to the top level (e.g., the outermost div) of the element. See the [OOUI documentation on MediaWiki][2] for an example. [2]: https://www.mediawiki.org/wiki/OOUI/Widgets/Buttons_and_Switches#cssExample
id string optional

The HTML id attribute used in the rendered tag.
text string optional

Text to insert
content Array optional

An array of content elements to append (after #text). Strings will be html-escaped; use an OO.ui.HtmlSnippet to append raw HTML. Instances of OO.ui.Element will have their $element appended.
$content jQuery optional

Content elements to append (after #text).
$element jQuery optional

Wrapper element. Defaults to a new element with #getTagName.
data any optional

Custom data of any type or combination of types (e.g., string, number, array, object). Data can also be specified with the #setData method.
Source:

Each Element represents a rendering in the DOM—a button or an icon, for example, or anything that is visible to a user.

Properties

tagNamestatic #

The name of the HTML tag used by the element.

The static value may be ignored if the #getTagName method is overridden.

Properties:

Type Description
string
Source:
The name of the HTML tag used by the element.

Methods

computeNativeScrollLeft(normalizedOffset, el) → {number}static #

Convert our normalized scrollLeft value to a value for current browser. See #getScrollLeft.

Parameters:

Name Type Description
normalizedOffset number

Normalized scrollLeft value
el HTMLElement | Window

Element on which the value will be set
Source:

Returns:

Type
number
Convert our normalized scrollLeft value to a value for current browser.

computeNormalizedScrollLeft(nativeOffset, el) → {number}static #

Convert native scrollLeft value to a value consistent between browsers. See #getScrollLeft.

Parameters:

Name Type Description
nativeOffset number

Native scrollLeft value
el HTMLElement | Window

Element from which the value was obtained
Source:

Returns:

Type
number
Convert native scrollLeft value to a value consistent between browsers.

gatherPreInfuseState(node, config) → {Object}protectedstatic #

Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of an HTML DOM node (and its children) that represent an Element of the same class and the given configuration, generated by the PHP implementation.

This method is called just before node is detached from the DOM. The return value of this function will be passed to #restorePreInfuseState after the newly created widget's #$element is inserted into DOM to replace node.

Parameters:

Name Type Description
node HTMLElement
config Object
Source:

Returns:

Type
Object

Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of an HTML DOM node (and its children) that represent an Element of the same class and the given configuration, generated by the PHP implementation.

getBorders(el) → {Object}static #

Get element border sizes.

Parameters:

Name Type Description
el HTMLElement

Element to measure
Source:

Returns:

Dimensions object with top, left, bottom and right properties

Type
Object
Get element border sizes.

getClosestScrollableContainer(el, [dimension]) → {HTMLElement}static #

Get closest scrollable container.

Traverses up until either a scrollable element or the root is reached, in which case the root scrollable element will be returned (see #getRootScrollableElement).

Parameters:

Name Type Attributes Description
el HTMLElement

Element to find scrollable container for
dimension string optional

Dimension of scrolling to look for; x, y or omit for either
Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

getDimensions(el) → {Object}static #

Get dimensions of an element or window.

Parameters:

Name Type Description
el HTMLElement | Window

Element to measure
Source:

Returns:

Dimensions object with borders, scroll, scrollbar and rect properties

Type
Object
Get dimensions of an element or window.

getDir(obj) → {string}static #

Get the direction of an element or document.

Parameters:

Name Type Description
obj jQuery | HTMLElement | HTMLDocument | Window

Context to get the direction for
Source:

Returns:

Text direction, either 'ltr' or 'rtl'

Type
string
Get the direction of an element or document.

getDocument(obj) → {HTMLDocument|null}static #

Get the document of an element.

Parameters:

Name Type Description
obj jQuery | HTMLElement | HTMLDocument | Window

Object to get the document for
Source:

Returns:

Document object

Type
HTMLDocument | null
Get the document of an element.

getFrameOffset(from, [to], [offset]) → {Object}static #

Get the offset between two frames.

TODO: Make this function not use recursion.

Parameters:

Name Type Attributes Default Description
from Window

Window of the child frame
to Window optional
 window

Window of the parent frame
offset Object optional

Offset to start with, used internally
Source:

Returns:

Offset object, containing left and top properties

Type
Object
Get the offset between two frames.

getRelativePosition($element, $anchor) → {Object}static #

Get the offset between two elements.

The two elements may be in a different frame, but in that case the frame $element is in must be contained in the frame $anchor is in.

Parameters:

Name Type Description
$element jQuery

Element whose position to get
$anchor jQuery

Element to get $element's position relative to
Source:

Returns:

Translated position coordinates, containing top and left properties

Type
Object
Get the offset between two elements.

getRootScrollableElement(el) → {HTMLBodyElement|HTMLHtmlElement}static #

Get the root scrollable element of given element's document.

Support: Chrome <= 60 On older versions of Blink, document.documentElement can't be used to get or set the scrollTop property; instead we have to use document.body. Changing and testing the value lets us use 'body' or 'documentElement' based on what is working.

https://code.google.com/p/chromium/issues/detail?id=303131

Parameters:

Name Type Description
el HTMLElement

Element to find root scrollable parent for
Source:

Returns:

Scrollable parent, <body> or <html>

Type
HTMLBodyElement | HTMLHtmlElement
Get the root scrollable element of given element's document.

getScrollLeft(el) → {number}static #

Get the number of pixels that an element's content is scrolled to the left.

This function smooths out browser inconsistencies (nicely described in the README at https://github.com/othree/jquery.rtl-scroll-type) and produces a result consistent with Firefox's 'scrollLeft', which seems the most sensible.

(Firefox's scrollLeft handling is nice because it increases from left to right, consistently with getBoundingClientRect().left and related APIs; because initial value is zero, so resetting it is easy; because adapting a hardcoded scroll position to a symmetrical RTL interface requires just negating it, rather than involving clientWidth and scrollWidth; and because if you mess up and don't adapt your code to RTL, it will scroll to the beginning rather than somewhere randomly in the middle but not where you wanted.)

Parameters:

Name Type Description
el HTMLElement | Window

Element to measure
Source:

Returns:

Scroll position from the left. If the element's direction is LTR, this is a positive number between 0 (initial scroll position) and el.scrollWidth - el.clientWidth (furthest possible scroll position). If the element's direction is RTL, this is a negative number between 0 (initial scroll position) and -el.scrollWidth + el.clientWidth (furthest possible scroll position).

Type
number
Get the number of pixels that an element's content is scrolled to the left.

getWindow(obj) → {Window}static #

Get the window of an element or document.

Parameters:

Name Type Description
obj jQuery | HTMLElement | HTMLDocument | Window

Context to get the window for
Source:

Returns:

Window object

Type
Window
Get the window of an element or document.

infuse(node, [config]) → {OO.ui.Element}static #

Reconstitute a JavaScript object corresponding to a widget created by the PHP implementation.

Parameters:

Name Type Attributes Description
node HTMLElement | jQuery

A single node for the widget to infuse.
config Object optional

Configuration options
Source:

Returns:

The OO.ui.Element corresponding to this (infusable) document node. For Tag objects emitted on the HTML side (used occasionally for content) the value returned is a newly-created Element wrapping around the existing DOM node.

Type
OO.ui.Element

Reconstitute a JavaScript object corresponding to a widget created by the PHP implementation.

reconsiderScrollbars(el)static #

Force the browser to reconsider whether it really needs to render scrollbars inside the element and reserve space for them, because it probably doesn't.

Workaround primarily for https://code.google.com/p/chromium/issues/detail?id=387290, but also similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need to first actually detach (or hide, but detaching is simpler) all children, then force a reflow, and then reattach (or show) them back.

Parameters:

Name Type Description
el HTMLElement

Element to reconsider the scrollbars on
Source:

Force the browser to reconsider whether it really needs to render scrollbars inside the element and reserve space for them, because it probably doesn't.

reusePreInfuseDOM(node, config) → {Object}protectedstatic #

Pick out parts of node's DOM to be reused when infusing a widget.

This method must not make any changes to the DOM, only find interesting pieces and add them to config (which should then be returned). Actual DOM juggling should then be done by the constructor, which will be given the enhanced config.

Parameters:

Name Type Description
node HTMLElement
config Object
Source:

Returns:

Type
Object
Pick out parts of node's DOM to be reused when infusing a widget.

scrollIntoView(elOrPosition, [config]) → {jQuery.Promise}static #

Scroll element into view.

Parameters:

Name Type Attributes Description
elOrPosition HTMLElement | Object

Element to scroll into view
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
animate string optional
 true

Animate to the new scroll offset.
duration string optional
 'fast'

jQuery animation duration value
direction string optional

Scroll in only one direction, e.g. 'x' or 'y', omit to scroll in both directions
alignToTop Object optional
 false

Aligns the top of the element to the top of the visible area of the scrollable ancestor.
padding Object optional

Additional padding on the container to scroll past. Object containing any of 'top', 'bottom', 'left', or 'right' as numbers.
scrollContainer Object optional

Scroll container. Defaults to getClosestScrollableContainer of the element.
Source:

Returns:

Promise which resolves when the scroll is complete

Type
jQuery.Promise
Scroll element into view.

setScrollLeft(el, scrollLeft)static #

Set the number of pixels that an element's content is scrolled to the left.

See #getScrollLeft.

Parameters:

Name Type Description
el HTMLElement | Window

Element to scroll (and to use in calculations)
scrollLeft number

Scroll position from the left. If the element's direction is LTR, this must be a positive number between 0 (initial scroll position) and el.scrollWidth - el.clientWidth (furthest possible scroll position). If the element's direction is RTL, this must be a negative number between 0 (initial scroll position) and -el.scrollWidth + el.clientWidth (furthest possible scroll position).
Source:
Set the number of pixels that an element's content is scrolled to the left.

getClosestScrollableElementContainer() → {HTMLElement} #

Get closest scrollable container.

Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

getData() → {any} #

Get element data.

Source:

Returns:

Element data

Type
any
Get element data.

getElementDocument() → {HTMLDocument} #

Get the DOM document.

Source:

Returns:

Document object

Type
HTMLDocument
Get the DOM document.

getElementGroup() → {OO.ui.mixin.GroupElement|null} #

Get group element is in.

Source:

Returns:

Group element, null if none

Type
OO.ui.mixin.GroupElement | null
Get group element is in.

getElementId() → {string} #

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

Source:

Returns:

Type
string

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

getElementWindow() → {Window} #

Get the DOM window.

Source:

Returns:

Window object

Type
Window
Get the DOM window.

getTagName() → {string} #

Get the HTML tag name.

Override this method to base the result on instance information.

Source:

Returns:

HTML tag name

Type
string
Get the HTML tag name.

isElementAttached() → {boolean} #

Check if the element is attached to the DOM

Source:

Returns:

The element is attached to the DOM

Type
boolean
Check if the element is attached to the DOM

isVisible() → {boolean} #

Check if element is visible.

Source:

Returns:

element is visible

Type
boolean
Check if element is visible.

restorePreInfuseState(state)protected #

Restore the pre-infusion dynamic state for this widget.

This method is called after #$element has been inserted into DOM. The parameter is the return value of #gatherPreInfuseState.

Parameters:

Name Type Description
state Object
Source:
Restore the pre-infusion dynamic state for this widget.

scrollElementIntoView([config]) → {jQuery.Promise} #

Scroll element into view.

Parameters:

Name Type Attributes Description
config Object optional

Configuration options
Source:

Returns:

Promise which resolves when the scroll is complete

Type
jQuery.Promise
Scroll element into view.

setData(data) → {OO.ui.Element}chainable #

Set element data.

Parameters:

Name Type Description
data any

Element data
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set element data.

setElementGroup(group) → {OO.ui.Element}chainable #

Set group element is in.

Parameters:

Name Type Description
group OO.ui.mixin.GroupElement | null

Group element, null if none
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set group element is in.

setElementId(id) → {OO.ui.Element}chainable #

Set the element has an 'id' attribute.

Parameters:

Name Type Description
id string
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set the element has an 'id' attribute.

supports(methods) → {boolean} #

Check if element supports one or more methods.

Parameters:

Name Type Description
methods string | Array.<string>

Method or list of methods to check
Source:

Returns:

All methods are supported

Type
boolean
Check if element supports one or more methods.

toggle([show]) → {OO.ui.Element}chainable #

Toggle visibility of an element.

Parameters:

Name Type Attributes Description
show boolean optional

Make element visible, omit to toggle visibility
Source:

Fires:

Returns:

The element, for chaining

Type
OO.ui.Element
Toggle visibility of an element.

updateThemeClasses() #

Update the theme-provided classes.

This is called in element mixins and widget classes any time state changes. Updating is debounced, minimizing overhead of changing multiple attributes and guaranteeing that theme updates do not occur within an element's constructor

Source:
Update the theme-provided classes.