API Reference
Namespaces
Classes
Events
Global
Externals

Class: SeriesEditDialog

WebComponents. SeriesEditDialog ()

This is a custom HtmlElement (Web Component). The tag name is the following:

<cq-series-edit-dialog>

The dialog inherits its open/close lifecycle from WebComponents.Dialog through CIQ.UI.DialogContentTag. It provides a basic color editing workflow using the shared swatch/color picker pattern from the series legend.

Emitters

A custom event will be emitted from the component when it modifies a series. See CIQ.UI.BaseComponent#emitCustomEvent for details on how to listen for this event. The details of the event contain the following:

property value
emitter this component
cause "useraction"
effect "modify"
action "change"
name series id
field field name being changed
value new value
oldValue previous value

cause and action are set only when the dialog is updated as a direct result of changing a form field.

<protected> new SeriesEditDialog()

Initializes component defaults and cached parameter references used by the dialog controls.

Since:

  • 10.2.0

Extends

Members

context :CIQ.UI.Context

Context

Type:
Inherited From:
Overrides:

Methods

addClaim()

Claim any keystrokes that come in. Once claimed, any keystrokes that come in are passed to the element. The element can then choose to capture or propagate the keystrokes. This enables an element to capture keystrokes even if it doesn't have mouse focus.

Inherited From:
Overrides:

addDefaultMarkup(component [, markup])

Adds default markup to a web component if the component does not have any child nodes.

Parameters:
Name Type Argument Description
component HTMLElement

The component to which the markup is added.
markup string <optional>

The markup to add to the web component. Unused if the component has a static markup property that specifies the markup; for example, MyComponent.markup.
Since:

  • 7.5.0

Inherited From:
Overrides:

adoptedCallback()

Re-registers inheritance helpers when the component moves between documents so shared methods remain available.

Since:

  • 10.2.0

Overrides:

buildAxisPayloadFromColor(colorValue)

Builds the payload required by modifySeries when a new axis color is chosen, merging existing axis parameters as needed.

Parameters:
Name Type Description
colorValue string

Axis color candidate.
Since:

  • 10.2.0

Returns:

Update payload describing axis changes.

Type
object

channelMergeObject(path, value, stx)

Merges an object in the chart engine communication channel.

Parameters:
Name Type Description
path string

The channel path.
value object

The value merged to the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:

channelRead(path [, stx])

Reads the current value in the chart engine communication channel.

Parameters:
Name Type Argument Description
path string

The channel path.
stx CIQ.ChartEngine <optional>

Unused.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The current value in channel.

Type
*

channelSubscribe(path, cb, stx)

Subscribes to the chart engine messaging channel.

Parameters:
Name Type Description
path *

The channel path.
cb *

A callback invoked upon subscribing and whenever a new message is posted in the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

A callback invoked when unsubscribing from the channel.

Type
function | undefined

channelWrite(path, value, stx)

Writes in the chart engine communication channel.

Parameters:
Name Type Description
path string

The channel path.
value *

The value written to the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:

clickFocusedItem(items, e)

Selects (clicks) the first element in items that has a cq-focused attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
e Event

The keystroke event.
Since:

  • 8.3.0

Inherited From:
Overrides:

close()

Closes the dialog.

Designed to be used as a helper method for the included WebComponents. A full tutorial on how to work with and customize the WebComponents can be found here: Web Component Interface.

Inherited From:
Overrides:

connectedCallback()

Handles DOM connection lifecycle to ensure the base dialog initialization runs only once per attachment.

Since:

  • 10.2.0

Overrides:
  • CIQ.UI.DialogContentTag#connectedCallback

deactivateItem(item)

Blurs and removes the cq-keyboard-active attribute from item.

Parameters:
Name Type Description
item HTMLElement
Since:

  • 8.4.0

Inherited From:
Overrides:

emitCustomEvent(params)

Emits a custom event from the webcomponent. The event type of the emitted event is determined by the particular user action taken. Up to two events are emitted when this function is executed. The first is an event with the type of action performed, if there is one. For example, events which are spawned without user action will not emit this first event. The second event will have a type derived from the component name. For example, the cq-study-legend component will emit a "StudyLegend" type event. The payload of the event will contain a detail section specifying the component which emitted the event as well as the effect - which more clearly defines the type of action causing the emittance. The detail section may also include custom fields further categorizing the event and providing additional information. These details are documented within the web component's documentation.

Parameters:
Name Type Description
params object
Properties
Name Type Argument Default Description
cause string <optional>

The cause of the event. e.g., useraction, timeout, alert. Defaults to "useraction" if not set and action parameter is set.
effect string <optional>

The effect of the user's action. Required if not provided in detail. e.g., open, help, toggle, select.
action string | null <optional>
 "click"

The action a user performed, if applicable. e.g. click, longpress, drag. Set to null if no user action was performed.
detail object <optional>
 {}

Optional extra parameters to include in the detail of the Custom Event.
Since:
  • 8.9.0
  • 9.1.0 Changed params object's property names.
Inherited From:
Overrides:
Example

Listening for a custom event using the standard addEventListener method.

document.addEventListener("DrawingPalette", (e) => {
	console.log(`Drawing Palette "view" is now: ${e.detail.view}`)
})

// For a given component tag we can find name of the event to listen using:

const componentEventName = CIQ.UI.components("cq-drawing-palette")[0].name;

// If the document might have multiple chart context elements (cq-context), add the listener to the specific context element instead of the document itself.

findFocused(items)

Finds the elements in items that have a cq-focused attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
Since:

  • 8.3.0

Inherited From:
Overrides:
Returns:

The elements in items that have a cq-focused attribute, or an empty array if no elements are found.

Type
Array

findKeyboardActive(items)

Finds the elements in items that have a cq-keyboard-active attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation
Since:

  • 8.4.0

Inherited From:
Overrides:
Returns:

The elements in items that have a cq-keyboard-active attribute, or an empty array if no elements are found.

Type
Array

focusItem(item)

Adds a cq-focused attribute to item and highlights item.

Parameters:
Name Type Description
item HTMLElement

Element that receives keyboard focus and is highlighted.
Since:

  • 8.3.0

Inherited From:
Overrides:

focusNextItem(items [, reverse] [, loop])

Focuses the next item in the tab order.

Locates the first element in items that has a cq-focused attribute. If an element is found, the attribute is removed from all elements in items, and cq-focused is applied to the element that follows (in the tab order) the element that was found.

If no elements are found with the cq-focused attribute, the attribute is applied to the first element in items (last element if reverse is true). If the last element in items (first element if reverse is true) is found to have the cq-focused attribute, focus remains on that element. Unless loop is set to true, then focus is applied to first element.

Parameters:
Name Type Argument Description
items NodeList

A list of elements that are selectable via keyboard navigation.
reverse boolean <optional>

If true, the operation is performed in reverse order; that is, from the last element in items to the first.
loop boolean <optional>

Loops back to the first item if the last element in items is selected.
Since:

  • 8.4.0 Added loop parameter. Return element, instead of true, if focus is changed.

Inherited From:
Overrides:
See:
Returns:

The newly focused element if a cq-focused attribute has changed.

Type
HTMLElement | undefined

getAxisMenuValue()

Derives the currently selected axis menu value from stored parameters.

Since:

  • 10.2.0

Returns:

The option key that should appear selected.

Type
string

getAxisOptions()

Builds the dropdown option map for y-axis selection using static entries.

Since:

  • 10.2.0

Returns:

Map of option values to localized labels.

Type
object

getChartContainer( [el])

Searches the DOM for the chart container element. Begins the search with el (or this) and proceeds parent-by-parent up the ancestry tree until an element is found.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

The element on which to start the search. If not provided, this is used.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The chart container element or undefined if an element is not found.

Type
HTMLElement | undefined

getContextContainer( [el])

Searches the DOM for the chart context element. Begins the search with el (or this if el is not provided) and proceeds up the ancestry tree until an element is found or the root of the tree has been reached.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

The element on which to start the search. If not provided, this is used.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The chart context element or undefined if an element is not found.

Type
HTMLElement | undefined

getPanelMenuValue()

Resolves the currently selected panel value for menu rendering.

Since:

  • 10.2.0

Returns:

The key that should appear selected in the dropdown.

Type
string

getPanelOptions()

Computes the dropdown options for panel selection, mixing static entries with the currently available chart panels.

Since:

  • 10.2.0

Returns:

Map of option values to localized labels.

Type
object

getRendererSeriesParams()

Returns the renderer series parameters for the active series.

Since:

  • 10.2.0

Returns:

Renderer series parameters for the current series.

Type
object | null

getTypeMenuOptions()

Builds the dropdown option map used by the type selector.

Since:

  • 10.2.0

Returns:

Map of option values keyed by type identifier.

Type
object

hide()

Hides the dialog and closes any lifted menus or open color pickers.

Since:

  • 10.2.0

initializeParameters( [params])

Hydrates the local parameters cache from the currently selected series so dropdowns and other controls reflect the existing series settings.

Parameters:
Name Type Argument Description
params object <optional>

Dialog parameters that may include series data.
Since:

  • 10.2.0

inputEntry(node, cb)

Attaches a keyboard input entry event.

Parameters:
Name Type Description
node HTMLElement

The element to which the input entry event is attached.
cb function

The callback function invoked when input entry occurs.
Inherited From:
Overrides:

makeMenu(name, currentValue, fields)

Builds a lifted dropdown to edit series parameters without relying on external menu configuration.

Parameters:
Name Type Description
name string

The parameter key (stored in this.parameters).
currentValue string

The currently selected value for the menu.
fields object

Map of internal values to localized labels.
Since:

  • 10.2.0

Returns:

The configured menu element ready for insertion.

Type
HTMLElement

<protected> makeTap(node, cb)

Attaches an "stxtap" event to an element, which will be fired on any event that resembles a click or tap. Note only one stxtap event is allowed per element. The handler is saved on the element as the selectFC property.

Designed to be used as a helper method for the included WebComponents. A full tutorial on how to work with and customize the WebComponents can be found here: Web Component Interface.

Parameters:
Name Type Description
node HTMLElement

The element to attach a tap event to.
cb CIQ.makeTap~makeTapCallback

The callback when tapped.
Inherited From:
Overrides:

naturalTabElements(element)

Returns all elements that are navigable by a browser's default tabbing algorithm

Parameters:
Name Type Description
element HTMLElement

Element to query selectors from.
Since:

  • 8.8.0

Inherited From:
Overrides:
Returns:

Array containing all tab navigable elements.

Type
Array.<HTMLElement>

open(params)

Opens the series edit dialog.

Parameters:
Name Type Description
params object

Parameters forwarded to the dialog base class.

Properties
Name Type Description
context CIQ.UI.Context

The chart context.
series object

Series definition captured from the chart engine.
Since:

  • 10.2.0

Overrides:

qs(path, context)

Adapts the querySelector method.

Parameters:
Name Type Description
path string

The CSS selectors for which to search.
context HTMLElement | string

The chart context element, which is the starting point of the DOM query, or "thisChart" to indicate the chart context in which this function is called.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The selected DOM element or undefined if an element is not found.

Type
HTMLElement | undefined

qsa(path, root, bustShadowRoots)

Adapts the querySelectorAll method. Returns an array instead of a node list to enable chaining of the array map, filter, forEach, and reduce functions.

Parameters:
Name Type Description
path string

The CSS selectors to find.
root HTMLElement | string

The root element, which is the starting point of the DOM query, or "thisChart" to indicate the chart context in which this function is called.
bustShadowRoots boolean

Set to true to penetrate shadow root boundaries.
Since:
  • 7.5.0
  • 8.9.0 Added bustShadowRoots parameter
Inherited From:
Overrides:
Returns:

An array of selected DOM element.

Type
Array.<HTMLElement>

refreshAxisColorControl()

Syncs the axis color swatch UI with the current dialog state and hides the control when axis color editing is not available.

Since:

  • 10.2.0

refreshParameters()

Regenerates the menu container so the displayed selection always reflects the latest parameters state.

Since:

  • 10.2.0

refreshSeriesStyle()

Renders the series style section with color pickers based on the current chart type.

Since:

  • 10.2.0

removeClaim()

Remove a claim on keystrokes.

Inherited From:
Overrides:

removeFocused(items)

Removes the cq-focused attribute from all elements in items.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
Since:

  • 8.3.0

Inherited From:
Overrides:

resolveAxisSelection(selection)

Normalizes a menu selection into engine and storage values for y-axis updates.

Parameters:
Name Type Default Description
selection string shared

Selected axis option key.
Since:

  • 10.2.0

Returns:

Contains storeValue, engineValue, and shareYAxis flags.

Type
object

resolveCurrentType()

Resolves the current chart type selection. Falls back to "line" when no chartType is available.

Since:

  • 10.2.0

Returns:

Active type key.

Type
string

resolveNewPanelName(series [, fallbackId])

Resolves a unique panel name for a series when moving it to a new panel.

Parameters:
Name Type Argument Description
series object | null

Series definition for the target renderer.
fallbackId string <optional>

Fallback id to use when series metadata is missing.
Since:

  • 10.2.0

Returns:

Unique panel name.

Type
string

resolvePanelSelection(selection)

Converts a dropdown selection into concrete panel values for storage and chart engine updates.

Parameters:
Name Type Default Description
selection string Auto

Menu value chosen by the user.
Since:

  • 10.2.0

Returns:

Contains storeValue and engineValue keys.

Type
object

setColor(color [, swatch])

Handles swatch color selections by updating the corresponding series through the chart engine helper.

Parameters:
Name Type Argument Description
color string

Selected color value ("auto" supported).
swatch HTMLElement <optional>

Optional swatch element that initiated the change.
Since:

  • 10.2.0

setContext(context)

Called when the component is assigned a context.

Parameters:
Name Type Description
context CIQ.UI.Context

The chart context.
Since:

  • 10.2.0

Overrides:

setLine(activator, width, pattern)

Updates the line style (width and pattern) for the series.

Parameters:
Name Type Description
activator object

The menu activator metadata.

Properties
Name Type Description
node HTMLElement

The corresponding line style dropdown.
width number

The selected line width.
pattern string

The selected line pattern.
Since:

  • 10.2.0

setParameterOption(activator [, name] [, value] [, wasChange])

Handles lifted-dropdown activation events and stores the chosen value before re-rendering the menu markup.

Parameters:
Name Type Argument Default Description
activator object

The menu activator metadata.
name string <optional>

Parameter name fallback for programmatic calls.
value string <optional>

Parameter value fallback for programmatic calls.
wasChange boolean <optional>
 true

True if this is a user-initiated change.
Since:

  • 10.2.0

trimInnerHTMLWhitespace()

Returns a copy of the innerHTML of an element, with leading and trailing characters stripped. The following characters are stripped: newline, carriage return, tab.

Since:

  • 9.1.0

Inherited From:
Overrides:
Returns:

Trimmed innerHTML

Type
string

<static> getSeriesRendererStyleReference()

Returns the style reference object that maps chart types to their editable properties. Used by both the dialog and comparison legend to determine which color properties are relevant for each chart type.

Since:

  • 10.2.0

Returns:

Map of chart types to property definitions.

Type
object

<static> registerIntervalHandler(handlerId, handler)

Registers an interval change handler that can be referenced by series. Handler is responsible for removing current series and replacing it with series using new interval.

Parameters:
Name Type Description
handlerId string

Unique identifier for this handler.
handler function

Function(stx, seriesId, newInterval) that handles interval changes.
Since:

  • 10.2.0

Example
// In a plugin initialization:
SeriesEditDialog.registerIntervalHandler("referenceData", (stx, seriesId, newInterval) => {
  // Function to handle interval change
  return true;
});