Options
All
  • Public
  • Public/Protected
  • All
Menu

PrimeFaces Timeline Widget

Timeline is an interactive graph to visualize events in time. Currently uses vis-timeline.

Type parameters

Hierarchy

Index

Constructors

constructor

  • Creates a new instance of this widget. Please note that you should NOT override this constructor. Instead, override the init method, which is called at the end of the constructor once the instance is created.

    Type parameters

    Parameters

    • cfg: PartialWidgetCfg<TCfg>

      The widget configuration to be used for this widget instance. This widget configuration is usually created on the server by the javax.faces.render.Renderer for this component.

    Returns Timeline<TCfg>

Properties

addCallback

addCallback: AddCallbackCallback

Callback that is invoked when an event was added to this timeline.

cfg

cfg: PartialWidgetCfg<TCfg>

The configuration of this widget instance. Please note that no property is guaranteed to be present, you should always check for undefined before accessing a property. This is partly because the value of a property is not transmitted from the server to the client when it equals the default.

changedCallback

changedCallback: ChangedCallbackCallback

Callback for when an item of the timeline has changed or was moved.

deleteCallback

deleteCallback: DeleteCallbackCallback

Callback for when an item of the timeline was deleted.

destroyListeners

Array of registered listeners invoked when this widget is destroyed. You should normally not use modify this directly, use addDestroyListener instead.

id

id: string | string[]

The client-side ID of this widget, with all parent naming containers, such as myForm:myWidget. This is also the ID of the container HTML element for this widget. In case the widget needs multiple container elements (such as Paginator), this may also be an array if IDs.

Optional initiatedByUser

initiatedByUser?: boolean

When the timeline is move to the right or left, whether that move was initiated by the user.

instance

instance: Timeline

The current vis-timeline instance.

jq

The jQuery instance of the container element of this widget. In case id is an array, it will contain multiple elements. Please note that some widgets have got not DOM elements at all, in this case this will be an empty jQuery instance.

jqId

jqId: string

A CSS selector for the container element (or elements, in case id is an array) of this widget, This is usually an ID selector (that is properly escaped). You can select the container element or elements like this: $(widget.jqId).

lazy

lazy: boolean

Whether the lazy loading feature is enabled, which loads events dynamically via AJAX.

max

max: null | number

If restricting the timeline to a certain range, the upper bound.

min

min: null | number

If restricting the timeline to a certain range, the lower bound.

pFactor

pFactor: number

The current preload factor, see TimelineCfg.preloadFactor.

rangeLoadedEvents

rangeLoadedEvents: TimeRange

Time range of the events that were loaded.

refreshListeners

Array of registered listeners invoked when this widget is refreshed. You should normally not use modify this directly, use addRefreshListener instead.

widgetVar

widgetVar: string

The name of the widget variables of this widget. The widget variable can be used to access a widget instance by calling PF('myWidgetVar').

Methods

Private _bindItemsEvents

  • _bindItemsEvents(): void
  • Sets up all event listeners for the timeline items.

    Returns void

Private _bindTimelineEvents

  • Sets up all event listeners for the timeline's events.

    Parameters

    Returns void

Protected _render

  • _render(): void
  • Creates timeline widget with all initialization steps.

    (from super type DeferredWidget) This render method is called by this deferred widget once the widget container has become visible. You may now proceed with widget initialization.

    Must be overridden, or an error will be thrown.

    override

    Returns void

Protected addDeferredRender

  • addDeferredRender(widgetId: string, container: JQuery<HTMLElement>, callback: () => boolean): void
  • Adds a deferred rendering task for the given widget to the queue.

    Parameters

    • widgetId: string

      The ID of a deferred widget.

    • container: JQuery<HTMLElement>

      The container element that should be visible.

    • callback: () => boolean

      Callback that is invoked when the widget may possibly have become visible. Should return true when the widget was rendered, or false when the widget still needs to be rendered later.

        • (): boolean
        • Returns boolean

    Returns void

addDestroyListener

  • Lets you register a listener that is called before the component is destroyed.

    When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. When the element is removed from the DOM by the update, the DOM element is detached from the DOM and all destroy listeners are called. This makes it possible to add listeners from outside the widget code.

    If you call this method twice with the same listener, it will be registered twice and later also called twice.

    Note that for this to work, you must not override the destroy method; or if you do, call super.

    Also, after this widget was detached is done, all destroy listeners will be unregistered.

    since

    7.0

    Parameters

    Returns void

addEvent

  • Adds an event to the timeline.

    Parameters

    • properties: DataItem

      Properties for the event.

    Returns void

addRefreshListener

  • When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. However, no new instance of the widget is created. Instead, after the DOM element was replaced, all refresh listeners are called. This makes it possible to add listeners from outside the widget code.

    If you call this method twice with the same listener, it will be registered twice and later also called twice.

    Note that for this to work, you must not override the refresh method; or if you do, call super.

    Also, after the refresh is done, all refresh listeners will be deregistered. If you added the listeners from within this widget, consider adding the refresh listeners not only in the init method, but also again in the refresh method after calling super.

    since

    7.0.0

    Parameters

    Returns void

callBehavior

  • Each widget may have one or several behaviors attached to it. This method calls all attached behaviors for the given event name. In case no such behavior exists, this method does nothing and returns immediately.

    A behavior is a way for associating client-side scripts with UI components that opens all sorts of possibilities, including client-side validation, DOM and style manipulation, keyboard handling, and more. When the behavior is triggered, the configured JavaScript gets executed.

    Behaviors are often, but not necessarily, AJAX behavior. When triggered, it initiates a request the server and processes the response once it is received. This enables several features such as updating or replacing elements dynamically. You can add an AJAX behavior via <p:ajax event="name" actionListener="#{...}" onstart="..." />.

    since

    7.0

    Parameters

    • event: string

      The name of an event to call.

    • Optional ext: Partial<ConfigurationExtender>

      Additional configuration that is passed to the AJAX request for the server-side callback.

    Returns void

cancelAdd

  • cancelAdd(): void
  • Cancels event adding.

    Returns void

cancelChange

  • cancelChange(): void
  • Cancels event changing.

    Returns void

cancelDelete

  • cancelDelete(): void
  • Cancels event deleting.

    Returns void

changeEvent

  • changeEvent(properties: { className?: string; content?: string; editable?: boolean | { remove?: boolean | undefined; updateGroup?: boolean | undefined; updateTime?: boolean | undefined; }; end?: string | number | { toString?: (() => string) | undefined; toDateString?: (() => string) | undefined; toTimeString?: (() => string) | undefined; toLocaleString?: { (): string; (locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string; } | undefined; ... 42 more ...; [Symbol.toPrimitive]?: { ...; }...; group?: any; id?: IdType; selectable?: boolean; start?: string | number | { toString?: (() => string) | undefined; toDateString?: (() => string) | undefined; toTimeString?: (() => string) | undefined; toLocaleString?: { (): string; (locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string; } | undefined; ... 42 more ...; [Symbol.toPrimitive]?: { ...; }...; style?: string; subgroup?: IdType; title?: string; type?: string }): void
  • Changes properties of an existing item in the timeline. The provided parameter properties is an object, and can contain parameters "start" (Date), "end" (Date), "content" (String), "group" (String).

    Parameters

    • properties: { className?: string; content?: string; editable?: boolean | { remove?: boolean | undefined; updateGroup?: boolean | undefined; updateTime?: boolean | undefined; }; end?: string | number | { toString?: (() => string) | undefined; toDateString?: (() => string) | undefined; toTimeString?: (() => string) | undefined; toLocaleString?: { (): string; (locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string; } | undefined; ... 42 more ...; [Symbol.toPrimitive]?: { ...; }...; group?: any; id?: IdType; selectable?: boolean; start?: string | number | { toString?: (() => string) | undefined; toDateString?: (() => string) | undefined; toTimeString?: (() => string) | undefined; toLocaleString?: { (): string; (locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string; } | undefined; ... 42 more ...; [Symbol.toPrimitive]?: { ...; }...; style?: string; subgroup?: IdType; title?: string; type?: string }

      Properties for the event.

      • Optional className?: string
      • Optional content?: string
      • Optional editable?: boolean | { remove?: boolean | undefined; updateGroup?: boolean | undefined; updateTime?: boolean | undefined; }
      • Optional end?: string | number | { toString?: (() => string) | undefined; toDateString?: (() => string) | undefined; toTimeString?: (() => string) | undefined; toLocaleString?: { (): string; (locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string; } | undefined; ... 42 more ...; [Symbol.toPrimitive]?: { ...; }...
      • Optional group?: any
      • Optional id?: IdType
      • Optional selectable?: boolean
      • Optional start?: string | number | { toString?: (() => string) | undefined; toDateString?: (() => string) | undefined; toTimeString?: (() => string) | undefined; toLocaleString?: { (): string; (locales?: string | string[] | undefined, options?: DateTimeFormatOptions | undefined): string; } | undefined; ... 42 more ...; [Symbol.toPrimitive]?: { ...; }...
      • Optional style?: string
      • Optional subgroup?: IdType
      • Optional title?: string
      • Optional type?: string

    Returns void

deleteAllEvents

  • deleteAllEvents(): void
  • Deletes all events from the timeline.

    Returns void

deleteEvent

  • Deletes an existing event.

    Parameters

    • id: IdType

      Index of the event.

    Returns void

destroy

  • destroy(): void
  • Cleans up deferred render tasks. When you extend this class and override this method, make sure to call super.

    override

    Returns void

Private fireLazyLoading

  • fireLazyLoading(): void
  • Fires event for lazy loading.

    Returns void

getBehavior

  • getBehavior(name: string): null | Behavior
  • Each widget may have one or several behaviors attached to it. This method returns the callback function for the given event.

    Note: Do not call the method directly, the recommended way to invoke a behavior is via callBehavior.

    A behavior is a way for associating client-side scripts with UI components that opens all sorts of possibilities, including client-side validation, DOM and style manipulation, keyboard handling, and more. When the behavior is triggered, the configured JavaScript gets executed.

    Behaviors are often, but not necessarily, AJAX behavior. When triggered, it initiates a request the server and processes the response once it is received. This enables several features such as updating or replacing elements dynamically. You can add an AJAX behavior via <p:ajax event="name" actionListener="#{...}" onstart="..." />.

    Parameters

    • name: string

      The name of an event for which to retrieve the behavior.

    Returns null | Behavior

    The behavior with the given name, or null if no such behavior exists.

getData

  • getData(): string
  • Retrieves the array of current data (events) as an JSON string. This method is useful when you done some changes in timeline and want to send them to server to update the backing model (with pe:remoteCommand and pe:convertTimelineEvents).

    Returns string

    A JSON string with the current data.

getEditable

  • Is the event by given id editable?

    Parameters

    • id: number

      Index of the event to check.

    Returns TimelineItemEditableType

    An object with properties updateTime, updateGroup and remove.

getEvent

  • Retrieves the properties of a single event. The returned object can contain parameters start (Date), end (Date), content (String), group (String).

    Parameters

    • id: IdType

      0-based index of the item to retrieve.

    Returns null | FullItem<DataItem, "id">

    The event at the given index, or null when no such events exists at the index.

getInstance

  • Gets instance of the timeline object.

    Returns Timeline

    The current timeline instance.

getJQ

  • Each widget has got a container element, this method returns that container. This container element is usually also the element whose ID is the client-side ID of the JSF component.

    Returns JQuery<HTMLElement>

    The jQuery instance representing the main HTML container element of this widget.

Private getLazyLoadRange

  • Gets time range(s) for events to be lazy loaded.

    The internal time range for already loaded events will be updated.

    Returns null | TimelineBiRange

    The time range(s) for events to be lazy loaded.

getNumberOfEvents

  • getNumberOfEvents(): number
  • Gets number of events (items in the timeline).

    Returns number

    The number of event in the timeline.

getParentForm

  • Gets the closest parent form for this widget.

    since

    10.0.0

    Returns JQuery<HTMLElement>

    A JQuery instance that either contains the form when found, or an empty JQuery instance when the form could not be found.

getParentFormId

  • getParentFormId(): undefined | string
  • Gets the closest parent form ID for this widget lazily so it can be used in AJAX requests.

    since

    10.0.0

    Returns undefined | string

    Either the form ID or undefined if no form can be found.

getSelectedEvent

  • getSelectedEvent(): null | FullItem<DataItem, "id">
  • Finds the currently selected event.

    Returns null | FullItem<DataItem, "id">

    The currently selected event, or null when no event is selected.

getSelectedId

  • getSelectedId(): null | IdType
  • Gets id of the currently selected event.

    Returns null | IdType

    The index of the currently selected event, or null if no event is currently selected.

getVisibleRange

  • The currently visible time range of the timeline.

    Returns TimelineWindow

    The time range that is currently visible.

hasBehavior

  • hasBehavior(event: string): boolean
  • Each widget may have one or several behaviors attached to it. This method checks whether this widget has got at least one behavior associated with given event name.

    A behavior is a way for associating client-side scripts with UI components that opens all sorts of possibilities, including client-side validation, DOM and style manipulation, keyboard handling, and more. When the behavior is triggered, the configured JavaScript gets executed.

    Behaviors are often, but not necessarily, AJAX behavior. When triggered, it initiates a request the server and processes the response once it is received. This enables several features such as updating or replacing elements dynamically. You can add an AJAX behavior via <p:ajax event="name" actionListener="#{...}" onstart="..." />.

    Parameters

    • event: string

      The name of an event to check.

    Returns boolean

    true if this widget has the given behavior, false otherwise.

init

  • A widget class should not declare an explicit constructor, the default constructor provided by this base widget should be used. Instead, override this initialize method which is called after the widget instance was constructed. You can use this method to perform any initialization that is required. For widgets that need to create custom HTML on the client-side this is also the place where you should call your render method.

    Please make sure to call the super method first before adding your own custom logic to the init method:

    PrimeFaces.widget.MyWidget = PrimeFaces.widget.BaseWidget.extend({
    init: function(cfg) {
    this._super(cfg);
    // custom initialization
    }
    });
    override

    Parameters

    • cfg: PartialWidgetCfg<TCfg>

      The widget configuration to be used for this widget instance. This widget configuration is usually created on the server by the javax.faces.render.Renderer for this component.

    Returns void

isDetached

  • isDetached(): boolean
  • Checks if this widget is detached, ie whether the HTML element of this widget is currently contained within the DOM (the HTML body element). A widget may become detached during an AJAX update, and it may remain detached in case the update removed this component from the component tree.

    Returns boolean

    true if this widget is currently detached, or false otherwise.

move

  • Moves the timeline the given move factor to the left or right. Start and end date will be adjusted, and the timeline will be redrawn.

    For example, try a move factor of 0.1 or -0.1. The move factor is a number that determines the moving amount. A positive value will move right, a negative value will move left.

    The parameter options must include an animation property, which can be a boolean or an object of the form {duration: number, easingFunction: string}.

    If true (default) or an object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function.

    Default duration is 500 ms, and default easing function is easeInOutQuad.

    Available easing functions:

    • linear
    • easeInQuad
    • easeOutQuad
    • easeInOutQuad
    • easeInCubic,
    • easeOutCubic
    • easeInOutCubic
    • easeInQuart
    • easeOutQuart
    • easeInOutQuart
    • easeInQuint
    • easeOutQuint
    • easeInOutQuint.

    Parameters

    • moveFactor: number

      The amount to move by. A positive value will move right, a negative value will move left.

    • Optional options: TimelineAnimationOptions

      Optional settings.

    • Optional callback: () => void

      A callback function can be passed as an optional parameter. This function will be called at the end of move operation.

        • (): void
        • Returns void

    Returns void

Protected postRender

  • postRender(): void
  • Called after the widget has become visible and after it was rendered. May be overridden, the default implementation is a no-op.

    Returns void

refresh

  • Used in ajax updates, reloads the widget configuration.

    When an AJAX call is made and this component is updated, the DOM element is replaced with the newly rendered content. However, no new instance of the widget is created. Instead, after the DOM element was replaced, this method is called with the new widget configuration from the server. This makes it possible to persist client-side state during an update, such as the currently selected tab.

    Please note that instead of overriding this method, you should consider adding a refresh listener instead via addRefreshListener. This has the advantage of letting you add multiple listeners, and makes it possible to add additional listeners from code outside this widget.

    By default, this method calls all refresh listeners, then reinitializes the widget by calling the init method.

    override

    Parameters

    Returns void

    The value as returned by the init method, which is often undefined.

removeScriptElement

  • removeScriptElement(clientId: string | string[]): void
  • Removes the widget's script block from the DOM. Currently, the ID of this script block consists of the client-side ID of this widget with the prefix _s, but this is subject to change.

    Parameters

    • clientId: string | string[]

      The client-side ID of the widget.

    Returns void

render

  • This render method to check whether the widget container is visible. Do not override this method, or the deferred widget functionality may not work properly anymore.

    Returns ReturnOrVoid<undefined | boolean>

    true if the widget container is visible, false or undefined otherwise.

renderDeferred

  • renderDeferred(): void
  • Call this method in the init method if you want deferred rendering support. This method checks whether the container of this widget is visible and call _render only once it is.

    Returns void

renderTimeline

  • renderTimeline(): void
  • Force render the timeline component.

    Returns void

setSelection

  • setSelection(id: null | IdType): void
  • Selects an event by its ID. The visible range will be moved, so that the selected event is placed in the middle.

    To unselect all events, pass null as the parameter.

    Parameters

    • id: null | IdType

      Index of the event to select. When negative, unselects all events.

    Returns void

setVisibleRange

  • Set the current visible window. The parameters start and end can be a date, number, or string.

    If the parameter value of start or end is null, the parameter will be left unchanged.

    The parameter options must include an animation property, which can be a boolean or an object of the form {duration: number, easingFunction: string}.

    If true (default) or an object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function.

    Default duration is 500 ms, and default easing function is easeInOutQuad.

    Available easing functions:

    • linear
    • easeInQuad
    • easeOutQuad
    • easeInOutQuad
    • easeInCubic,
    • easeOutCubic
    • easeInOutCubic
    • easeInQuart
    • easeOutQuart
    • easeInOutQuart
    • easeInQuint
    • easeOutQuint
    • easeInOutQuint.

    Parameters

    • start: DateType

      Start of the time range.

    • end: DateType

      End of the time range.

    • Optional options: TimelineAnimationOptions

      Optional settings.

    • Optional callback: () => void

      Function A callback function can be passed as an optional parameter. This function will be called at the end of the setVisibleRange function.

        • (): void
        • Returns void

    Returns undefined

    Always returns undefined.

updateGroup

  • updateGroup(properties: { className?: string; content?: string | HTMLElement; id?: IdType; nestedGroups?: IdType[]; options?: { drawPoints?: (() => void) | { enabled?: boolean | undefined; onRender?: (() => boolean) | undefined; size?: number | undefined; style?: Graph2dDrawPointsStyle | undefined; } | undefined; ... 4 more ...; yAxisOrientation?: RightLeftEnumType | undefined; }; showNested?: boolean; style?: string; subgroupOrder?: string | ((a: any, b: any) => number); subgroupStack?: boolean | { [x: string]: boolean | undefined; }; subgroupVisibility?: { [x: string]: boolean | undefined; }; title?: string; visible?: boolean }): void
  • Updates a group of the timeline, adding it if it does not exists.

    The provided parameter properties is an object, containing the properties

    • id (string)
    • content (string)
    • style (string)
    • className (string)
    • order (number)

    Parameters style, className and order are optional.

    Parameters

    • properties: { className?: string; content?: string | HTMLElement; id?: IdType; nestedGroups?: IdType[]; options?: { drawPoints?: (() => void) | { enabled?: boolean | undefined; onRender?: (() => boolean) | undefined; size?: number | undefined; style?: Graph2dDrawPointsStyle | undefined; } | undefined; ... 4 more ...; yAxisOrientation?: RightLeftEnumType | undefined; }; showNested?: boolean; style?: string; subgroupOrder?: string | ((a: any, b: any) => number); subgroupStack?: boolean | { [x: string]: boolean | undefined; }; subgroupVisibility?: { [x: string]: boolean | undefined; }; title?: string; visible?: boolean }

      The event's properties.

      • Optional className?: string
      • Optional content?: string | HTMLElement
      • Optional id?: IdType
      • Optional nestedGroups?: IdType[]
      • Optional options?: { drawPoints?: (() => void) | { enabled?: boolean | undefined; onRender?: (() => boolean) | undefined; size?: number | undefined; style?: Graph2dDrawPointsStyle | undefined; } | undefined; ... 4 more ...; yAxisOrientation?: RightLeftEnumType | undefined; }
      • Optional showNested?: boolean
      • Optional style?: string
      • Optional subgroupOrder?: string | ((a: any, b: any) => number)
      • Optional subgroupStack?: boolean | { [x: string]: boolean | undefined; }
      • Optional subgroupVisibility?: { [x: string]: boolean | undefined; }
      • Optional title?: string
      • Optional visible?: boolean

    Returns void

zoom

  • Zooms the timeline the given zoom factor in or out.

    The parameter options must include an animation property, which can be a boolean or an object of the form {duration: number, easingFunction: string}.

    If true (default) or an object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function.

    Default duration is 500 ms, and default easing function is easeInOutQuad.

    Available easing functions:

    • linear
    • easeInQuad
    • easeOutQuad
    • easeInOutQuad
    • easeInCubic,
    • easeOutCubic
    • easeInOutCubic
    • easeInQuart
    • easeOutQuart
    • easeInOutQuart
    • easeInQuint
    • easeOutQuint
    • easeInOutQuint.

    Parameters

    • zoomFactor: number

      An number between -1 and +1. If positive zoom in, and if negative zoom out.

    • Optional options: TimelineAnimationOptions

      Optional settings.

    • Optional callback: () => void

      A callback function can be passed as an optional parameter. This function will be called at the end of the zooming operation.

        • (): void
        • Returns void

    Returns undefined

    Always returns undefined.

Generated using TypeDoc