Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace utils

The object with various utilities needed by PrimeFaces.

Index

Functions

Functions

addModal

  • Creates a new (empty) container for a modal overlay. A modal overlay is an overlay that blocks the content below it. To remove the modal overlay, use PrimeFaces.utils.removeModal.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      An overlay widget instance.

    • overlay: JQuery<HTMLElement>

      The modal overlay element should be a DIV.

    • tabbablesCallback: (() => JQuery<HTMLElement>)

      A supplier function that return a list of tabbable elements. A tabbable element is an element to which the user can navigate to via the tab key.

    Returns JQuery

    The DOM element for the newly added modal overlay container.

appendDynamicOverlay

  • An overlay widget is moved in the DOM to the position as specified by the appendTo attribute. This function moves the widget to its position in the DOM and removes old elements from previous AJAX updates.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      The overlay widget instance.

    • overlay: JQuery<HTMLElement>

      The DOM element for the overlay.

    • overlayId: string

      ID of the overlay, usually the widget ID.

    • appendTo: JQuery<HTMLElement>

      The container to which the overlay is appended.

    Returns void

blockEnterKey

  • Blocks the enter key for an event like keyup or keydown. Useful in filter input events in many components.

    Parameters

    Returns boolean

    true if ENTER key was blocked, false if not.

calculateRelativeOffset

  • Calculates an element offset relative to the current scroll position of the window.

    Parameters

    • element: JQuery<HTMLElement>

      An element for which to calculate the scroll position.

    Returns Coordinates

    The offset of the given element, relative to the current scroll position of the window.

cleanupDynamicOverlay

  • Cleanup the detached overlay.

    If you update a component, the overlay is rendered as specified in the component tree (XHTML view), but moved to a different container via JavaScript.

    This means that after an AJAX update, we now have 2 overlays with the same id:

    1. The newly rendered overlay, as a child of the element specified by the component tree (XHTML view)
    2. The old, detached overlay, as a child of the element specified by appendTo attribute

    We now need to remove the detached overlay. This is done by this function.

    Parameters

    • widget: DynamicOverlayWidget<DynamicOverlayWidgetCfg>

      The (old) overlay widget instance.

    • overlay: JQuery<HTMLElement>

      The DOM element for the overlay.

    • overlayId: string

      ID of the overlay, usually the widget ID.

    • appendTo: JQuery<HTMLElement>

      The container to which the overlay is appended.

    Returns void

countBytes

  • countBytes(text: string): number

  • Count the bytes of the inputtext. borrowed from the ckeditor wordcount plugin

    Parameters

    • text: string

      Text to count bytes from.

    Returns number

    the byte count

decodeXml

  • decodeXml(input: undefined | string): string | undefined

  • Decode escaped XML into regular string.

    Parameters

    • input: undefined | string

      the input to check if filled

    Returns string | undefined

    either the original string or escaped XML

defaultNumeric

  • defaultNumeric(value: undefined | number, defaultValue: number): number

  • When configuring numeric value like 'showDelay' and the user wants '0' we can't treat 0 as Falsey so we make the value 0. Otherwise Falsey returns the default value.

    Parameters

    • value: undefined | number

      the original value

    • defaultValue: number

      the required default value if value is not set

    Returns number

    the calculated value

disableAnimations

  • disableAnimations(): void

  • Disables CSS and jQuery animation.

    Returns void

disableButton

  • disableButton(jq: JQuery<HTMLElement>): void

  • Disables a button from being clicked.

    Parameters

    • jq: JQuery<HTMLElement>

      a required jQuery button to disable

    Returns void

disableInputWidget

  • disableInputWidget(jq: JQuery<HTMLElement>, input: undefined | null | JQuery<HTMLElement>): void

  • Disables a widget from editing and sets it style as disabled.

    Parameters

    • jq: JQuery<HTMLElement>

      a required jQuery element to disable

    • input: undefined | null | JQuery<HTMLElement>

      an optional jQuery input to disable (will use jq if null)

    Returns void

enableAnimations

  • enableAnimations(): void

  • Enables CSS and jQuery animation.

    Returns void

enableButton

  • enableButton(jq: JQuery<HTMLElement>): void

  • Enables a button.

    Parameters

    • jq: JQuery<HTMLElement>

      a required jQuery element to enable

    Returns void

enableInputWidget

  • enableInputWidget(jq: JQuery<HTMLElement>, input: undefined | null | JQuery<HTMLElement>): void

  • Enables a widget for editing and sets it style as enabled.

    Parameters

    • jq: JQuery<HTMLElement>

      a required jQuery element to enable

    • input: undefined | null | JQuery<HTMLElement>

      an optional jQuery input to enable (will use jq if null)

    Returns void

enableScrolling

  • enableScrolling(): void

  • Enables scrolling again if previously disabled via PrimeFaces.utils.preventScrolling.

    Returns void

enableTabbing

  • Enables navigating to an element via the tab key outside an overlay widget. Usually called when a modal overlay is removed. This reverts the changes as made by PrimeFaces.utils.preventTabbing.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      A modal overlay widget instance.

    • id: string

      ID of a modal overlay, usually the widget ID.

    Returns void

excludedSwipeElements

  • excludedSwipeElements(): string

  • Exclude elements such as buttons, links, inputs from being touch swiped. Users can always add class="noSwipe" to any element to exclude it as well.

    Returns string

    A CSS selector for the elements to be excluded from being touch swiped.

formatAllowTypes

  • formatAllowTypes(allowTypes: string): string

  • Formats the allowTypes regex pattern in a more human-friendly format.

    Parameters

    • allowTypes: string

      The allowTypes regex pattern to format

    Returns string

    The allowTypes formatted in a more human-friendly format.

formatBytes

  • formatBytes(bytes: number): string

  • Formats the given data size in a more human-friendly format, e.g., 1.5 MB etc.

    Parameters

    • bytes: number

      File size in bytes to format

    Returns string

    The given file size, formatted in a more human-friendly format.

getScrollableParents

  • getScrollableParents(element: Element): Element[]

  • Finds scrollable parents (not the document).

    Parameters

    • element: Element

      An element used to find its scrollable parents.

    Returns Element[]

    the list of scrollable parents.

hasFloatLabel

  • hasFloatLabel(jq: undefined | null | JQuery<HTMLElement>): boolean

  • Is this component wrapped in a float label?

    Parameters

    • jq: undefined | null | JQuery<HTMLElement>

      An element to check if wrapped in float label.

    Returns boolean

    true this this JQ has a float label parent

ignoreFilterKey

  • Ignores unprintable keys on filter input text box. Useful in filter input events in many components.

    Parameters

    Returns boolean

    true if the one of the keys to ignore was pressed, or false otherwise.

isActionKey

  • Is this SPACE or ENTER key. Used throughout codebase to trigger and action.

    Parameters

    Returns boolean

    true if the key is an action key, or false otherwise.

isClipboardKey

  • Checks if the key pressed is cut, copy, or paste.

    Parameters

    Returns boolean

    true if the key is cut/copy/paste, or false otherwise.

isMetaKey

  • Is this CMD on MacOs or CTRL key on other OSes.

    Parameters

    Returns boolean

    true if the key is a meta key, or false otherwise.

isModalActive

  • isModalActive(id: string): boolean

  • Checks if a modal with the given ID is currently displayed.

    Parameters

    • id: string

      The base ID of a modal overlay, usually the widget ID.

    Returns boolean

    Whether the modal with the given ID is displayed.

isPrintableKey

  • Checks if the key pressed is a printable key like 'a' or '4' etc.

    Parameters

    Returns boolean

    true if the key is a printable key, or false otherwise.

isScrollParentWindow

  • isScrollParentWindow(jq: undefined | null | JQuery<HTMLElement>): boolean

  • Is this scrollable parent a type that should be bound to the window element.

    Parameters

    • jq: undefined | null | JQuery<HTMLElement>

      An element to check if should be bound to window scroll.

    Returns boolean

    true this this JQ should be bound to the window scroll event

killswitch

  • killswitch(): void

  • Killswitch that kills all AJAX requests, running Pollers and IdleMonitors.

    see

    GitHub Issue 10299

    Returns void

openLink

  • Helper to open a new URL and if CTRL is held down open in new browser tab.

    Parameters

    • event: TriggeredEvent<any, any, any, any>

      The click event that occurred.

    • link: JQuery<HTMLElement>

      The URL anchor link that was clicked.

    Returns void

preventScrolling

  • preventScrolling(): void

  • Prevents the user from scrolling the document BODY element. You can enable scrolling again via PrimeFaces.utils.enableScrolling.

    Returns void

preventTabbing

  • Given a modal overlay, prevents navigating via the tab key to elements outside of that modal overlay. Use PrimeFaces.utils.enableTabbing to restore the original behavior.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      An overlay widget instance.

    • id: string

      ID of a modal overlay widget.

    • zIndex: number

      The z-index of the modal overlay.

    • tabbablesCallback: (() => JQuery<HTMLElement>)

      A supplier function that return a list of tabbable elements. A tabbable element is an element to which the user can navigate to via the tab key.

    Returns void

queueTask

  • queueTask(fn: (() => void), delay: undefined | number): number | undefined

  • Queue a microtask if delay is 0 or less and setTimeout if > 0.

    Parameters

    • fn: (() => void)

      the function to call after the delay

        • (): void

        • Returns void

    • delay: undefined | number

      the optional delay in milliseconds

    Returns number | undefined

    the id associated to the timeout or undefined if no timeout used

registerCSSTransition

  • registerCSSTransition(element: undefined | null | JQuery<HTMLElement>, className: undefined | null | string): CssTransitionHandler | null

  • CSS Transition method for overlay panels such as SelectOneMenu/SelectCheckboxMenu/Datepicker's panel etc.

    Parameters

    • element: undefined | null | JQuery<HTMLElement>

      An element for which to execute the transition.

    • className: undefined | null | string

      Class name used for transition phases.

    Returns CssTransitionHandler | null

    Two handlers named show and hide that should be invoked when the element gets shown and hidden. If the given element or className property is undefined or null, this function returns null.

registerConnectedOverlayScrollHandler

  • Registers a callback that is invoked when a scroll event is triggered on The DOM element for the widget that has a connected overlay.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      A widget instance for which to register a scroll handler.

    • scrollNamespace: string

      A scroll event with a namespace, such as scroll.widgetId.

    • element: undefined | JQuery<HTMLElement>

      A DOM element used to find scrollable parents.

    • scrollCallback: ((event: TriggeredEvent<any, any, any, any>) => void)

      A callback that is invoked when a scroll event occurs on the widget.

    Returns UnbindCallback

    unbind callback handler

registerDynamicOverlay

  • Sets up an overlay widget. Appends the overlay widget to the element as specified by the appendTo attribute. Also makes sure the overlay widget is handled properly during AJAX updates.

    Parameters

    Returns JQuery

    The overlay that was passed to this function.

registerHideOverlayHandler

  • Registers a callback on the document that is invoked when the user clicks on an element outside the overlay widget.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      An overlay widget instance.

    • hideNamespace: string

      A click event with a namespace to listen to, such as mousedown.widgetId.

    • overlay: JQuery<HTMLElement>

      The DOM element for the overlay.

    • resolveIgnoredElementsCallback: undefined | ((event: TriggeredEvent<any, any, any, any>) => JQuery<HTMLElement>)

      The callback which resolves the elements to ignore when the user clicks outside the overlay. The hideCallback is not invoked when the user clicks on one those elements.

    • hideCallback: ((event: TriggeredEvent<any, any, any, any>, eventTarget: JQuery<HTMLElement>) => void)

      A callback that is invoked when the user clicks on an element outside the overlay widget.

    Returns UnbindCallback

    Unbind callback handler

registerResizeHandler

  • Registers a callback that is invoked when the window is resized.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      A widget instance for which to register a resize handler.

    • resizeNamespace: string

      A resize event with a namespace to listen to, such as resize.widgetId.

    • element: undefined | JQuery<HTMLElement>

      An element that prevents the callback from being invoked when it is not visible, usually a child element of the widget.

    • resizeCallback: ((event: TriggeredEvent<any, any, any, any>) => void)

      A callback that is invoked when the window is resized.

    • Optional params: string

      Optional CSS selector. If given, the callback is invoked only when the resize event is triggered on an element the given selector.

    Returns UnbindCallback

    Unbind callback handler

registerScrollHandler

  • Registers a callback that is invoked when a scroll event is triggered on the DOM element for the widget.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      A widget instance for which to register a scroll handler.

    • scrollNamespace: string

      A scroll event with a namespace, such as scroll.widgetId.

    • scrollCallback: ((event: TriggeredEvent<any, any, any, any>) => void)

      A callback that is invoked when a scroll event occurs on the widget.

    Returns UnbindCallback

    unbind callback handler

removeDynamicOverlay

  • Removes the overlay from the overlay container as specified by the appendTo attribute.

    Parameters

    • widget: DynamicOverlayWidget<DynamicOverlayWidgetCfg>

      The overlay widget instance.

    • overlay: JQuery<HTMLElement>

      The (new) DOM element of the overlay.

    • overlayId: string

      ID of the the overlay, usually the widget ID.

    • appendTo: JQuery<HTMLElement>

      The container to which the overlay is appended.

    Returns void

removeModal

  • Given a modal overlay widget, removes the modal overlay element from the DOM. This reverts the changes as made by PrimeFaces.utils.addModal.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      A modal overlay widget instance.

    • Optional overlay: null | JQuery<HTMLElement>

      The modal overlay element should be a DIV.

    Returns void

resolveAppendTo

  • Finds the element to which the overlay panel should be appended. If none is specified explicitly, append the panel to the body.

    Parameters

    Returns string | null

    The search expression for the element to which the overlay panel should be appended.

resolveDynamicOverlayContainer

  • Finds the container element to which an overlay widget should be appended. This is either the element specified by the widget configurations's appendTo attribute, or the document BODY element otherwise.

    Parameters

    Returns JQuery

    The container DOM element to which the overlay is to be appended.

styleClass

  • styleClass(): string

  • This method concatenates the classes into a string according to the condition of the arguments and returns it.

    Returns string

    class

unbindScrollHandler

  • Removes a scroll handler as registered by PrimeFaces.utils.registerScrollHandler.

    Parameters

    • widget: BaseWidget<BaseWidgetCfg>

      A widget instance for which a scroll handler was registered.

    • scrollNamespace: string

      A scroll event with a namespace, such as scroll.widgetId.

    Returns void

updateFloatLabel

  • updateFloatLabel(element: undefined | JQuery<HTMLElement>, inputs: undefined | JQuery<HTMLElement>, hasFloatLabel: undefined | boolean): void

  • Handles floating label CSS if wrapped in a floating label.

    Parameters

    • element: undefined | JQuery<HTMLElement>

      the to add the CSS classes to

    • inputs: undefined | JQuery<HTMLElement>

      the input(s) to check if filled

    • hasFloatLabel: undefined | boolean

      true if this is wrapped in a floating label

    Returns void

Generated using TypeDoc