nebula.js: stardust

Product and framework agnostic integration API for Qlik's Associative Engine, commonly used with enigma.js. Consider using the qlik-embed toolkit for an easier embedding experience, whilst building on the same core technologies.

Download specification

Initiates a new Embed instance using the specified enigma app.

Parameters

app qix.Doc
Required
instanceConfig Configuration
Show instanceConfig properties
- load LoadFallback
  Fallback load function for missing types
  
  Show load properties
  
  LoadFallback() function
  Required
  Fallback load function for missing types
  Parameters
  
  LoadType
  Required
  
  Show properties
  
  LoadType interface
  Required
  Parameters
  
  type object
  Required
  
  Show type properties
  
  name string
  Required
  
  version string
  Required
  
  Returns
  
  Promise < Visualization >
  Required
  
  Returns
  
  Promise < Visualization >
  Required
- context Context
  Settings for the rendering instance
  
  Show context properties
  
  theme string
  default = "light"
  
  language string
  default = "en-US"
  
  deviceType string
  default = "auto"
  
  constraints Constraints Deprecated
  
  Show constraints properties
  
  passive boolean
  Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
  default = false
  
  active boolean
  Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
  default = false
  
  select boolean
  Whether or not select constraints are on. Should block any selection action. Implied when active is true.
  default = false
  
  edit boolean
  Whether or not edit actions are available. Should block any edit action.
  default = true
  
  interactions Interactions
  
  Show interactions properties
  
  passive boolean
  Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
  default = true
  
  active boolean
  Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
  default = true
  
  select boolean
  Whether or not select interactions are on. Allows selection actions. Implied when active is false.
  default = true
  
  edit boolean
  Whether or not edit actions are on. Allows edit actions.
  default = false
  
  keyboardNavigation boolean
  default = false
  
  disableCellPadding boolean
  default = false
  
  dataViewType string
  Type used for toggling to the data view (toggleDataView) This type need to be registered as well
  default = "sn-table"
- types Array< TypeInfo >
  Visualization types to register
- themes Array< ThemeInfo >
  Themes to register
- hostConfig object
  Qlik api compatible host config, see https://github.com/qlik-oss/qlik-api-ts/blob/main/docs/authentication.md#the-host-config
- anything object

Returns

Embed
Required
Show properties
- render() function
  Required
  Renders a visualization or sheet into an HTMLElement. Visualizations can either be existing objects or created on the fly. Support for sense sheets is experimental.
  Parameters
  
  cfg RenderConfig
  Required
  The render configuration.
  
  Show cfg properties
  
  element HTMLElement
  Required
  Target html element to render in to
  
  options object
  Options passed into the visualisation
  
  onRender() function
  Callback function called after rendering successfully
  
  onError() function
  Callback function called if an error occurs
  Parameters
  
  RenderError
  Required
  
  Show properties
  
  originalError Error
  Required
  
  plugins Array< Plugin >
  plugins passed into the visualisation
  
  id string
  For existing objects: Engine identifier of object to render
  
  type string
  For creating objects: Type of visualisation to render
  
  version string
  For creating objects: Version of visualization to render
  
  fields Array< Field >
  For creating objects: Data fields to use
  
  extendProperties boolean
  For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.
  default = false
  
  properties qix.GenericObjectProperties
  For creating objects: Explicit properties to set
  
  Returns
  
  Promise < Viz | Sheet >
  Required
  A controller to the rendered visualization or sheet.
- create() function
  Required
  Creates a visualization model
  Parameters
  
  cfg CreateConfig
  Required
  The create configuration.
  
  Show cfg properties
  
  type string
  Required
  
  version string
  
  fields Array< Field >
  
  properties qix.GenericObjectProperties
  
  Returns
  
  Promise < qix.GenericObject >
  Required
  An engima model
- generateProperties() function
  Required
  Generates properties for a visualization object
  Parameters
  
  cfg CreateConfig
  Required
  The create configuration.
  
  Returns
  
  Promise < object >
  Required
  The objects properties
- context() function
  Required
  Updates the current context of this embed instance. Use this when you want to change some part of the current context, like theme.
  Parameters
  
  ctx Context
  Required
  The context to update.
  
  Returns
  
  Promise < undefined >
  Required
- selections() function
  Required
  Gets the app selections of this instance.
  Returns
  
  Promise < AppSelections >
  Required
- field() function
  Required
  Available since: 1.1.0
  Gets the listbox instance of the specified field
  Parameters
  
  fieldIdentifier string | LibraryField | QInfo
  Required
  Fieldname as a string, a Library dimension or an object id
  
  Returns
  
  Promise < FieldInstance >
  Required
- getRegisteredTypes() function
  Required
  Gets a list of registered visualization types and versions
  Returns
  
  Array< Object >
  Required
  types

embed

import { embed } from '@nebula.js/stardust'
const n = embed(app);
n.render({ id: 'abc' });

Creates a new embed scope bound to the specified configuration.

The configuration is merged with all previous scopes.

Parameters

configuration Configuration
Required
The configuration object

Returns

embed
Required
Show properties
- createConfiguration() function
  Required
  Creates a new embed scope bound to the specified configuration.
  
  The configuration is merged with all previous scopes.
  Parameters
  
  configuration Configuration
  Required
  The configuration object
  
  Returns
  
  embed
  Required

createConfiguration

import { embed } from '@nebula.js/stardust';
// create a 'master' config which registers all types
const m = embed.createConfiguration({
  types: [{
    name: 'mekko',
    version: '1.0.0',
    load: () => Promise.resolve(mekko)
  }],
});

// create an alternate config with dark theme
// and inherit the config from the previous
const d = m.createConfiguration({
 context: {
   theme: 'dark'
 }
});

m(app).render({ type: 'mekko' }); // will render the object with default theme
d(app).render({ type: 'mekko' }); // will render the object with 'dark' theme
embed(app).render({ type: 'mekko' }); // will throw error since 'mekko' is not a register type on the default instance

Creates a stateful value.

Parameters

initialState S | function
Required
The initial state.

Returns

Array< S , SetStateFn >
Required
The value and a function to update it.

useState

import { useState } from '@nebula.js/stardust';
// ...
// initiate with simple primitive value
const [zoomed, setZoomed] = useState(false);

// update
setZoomed(true);

// lazy initiation
const [value, setValue] = useState(() => heavy());

Triggers a callback function when a dependent value changes.

Omitting the dependency array will have the hook run on each update and an empty dependency array runs only once.

Parameters

effect EffectCallback
Required
The callback.
Show effect properties
- EffectCallback() function
  Required
  Callback function that should return a function that in turns gets called before the hook runs again or when the component is destroyed. For example to remove any listeners added in the callback itself.
  Returns
  
  void | function
  Required
deps Array< any >
The dependencies that should trigger the callback.

useEffect

import { useEffect } from '@nebula.js/stardust';
// ...
useEffect(() => {
  console.log('mounted');
  return () => {
    console.log('unmounted');
  };
}, []);

useEffect(() => {
  const clickHandler = () => { console.log('click') };
  const button = element.querySelector('.button');
  button.addEventListener('click', clickHandler);
  return () => {
    button.removeEventListener('click', clickHandler);
  };
}, []);

Creates a stateful value when a dependent changes.

Parameters

factory() function
Required
The factory function.
Returns
- T
  Required
deps Array< any >
Required
The dependencies.

Returns

T
Required
The value returned from the factory function.

useMemo

import { useMemo } from '@nebula.js/stardust';
// ...
const v = useMemo(() => {
  return doSomeHeavyCalculation();
}), []);

Creates a reference to a value not needed for rendering

While Nebula does not have a virtual DOM, it is still useful to have a reference to an object that is retained across renders and in it self does not trigger a render.

Parameters

initialValue R
Required
The initial value.

Returns

Ref
Required
An object with the current value
Show properties
- current R
  Required
  Current value

useRef

import { useRef } from '@nebula.js/stardust';
// ...
// initiate with simple value
const timesRendered = useRef(0);

useEffect(() => {
 render(layout);
 // increments the render counter, a useState would trigger another render
 timesRendered.current += 1;
},[layout]);

Runs a callback function when a dependent changes.

Useful for async operations that otherwise cause no side effects. Do not add for example listeners withing the callback as there is no teardown function.

Parameters

factory() function
Required
The factory function that calls the promise.
Returns
- Promise < P >
  Required
deps Array< any >
The dependencies.

Returns

Array< P , Error >
Required
The resolved value or rejected error

usePromise

import { usePromise } from '@nebula.js/stardust';
import { useModel } from '@nebula.js/stardust';
// ...
const model = useModel();
const [resolved, rejected] = usePromise(() => model.getLayout(), [model]);

Gets the HTMLElement this visualization is rendered into.

Returns

HTMLElement
Required

useElement

import { useElement } from '@nebula.js/stardust';
// ...
const el = useElement();
el.innerHTML = 'Hello!';

Gets the size of the HTMLElement the visualization is rendered into.

Returns

Rect
Required
The size of the element.
Show properties
- top number
  Required
- left number
  Required
- width number
  Required
- height number
  Required

useRect

import { useRect } from '@nebula.js/stardust';
// ...
const rect = useRect();
useEffect(() => {
  console.log('resize');
}, [rect.width, rect.height])

Gets the layout of the generic object associated with this visualization.

Returns

qix.GenericObjectLayout
Required

useLayout

import { useLayout } from '@nebula.js/stardust';
// ...
const layout = useLayout();
console.log(layout);

Gets the layout of the generic object associated with this visualization.

Unlike the regular layout, a stale layout is not changed when a generic object enters the modal state. This is mostly notable in that qSelectionInfo.qInSelections in the layout is always false. The returned value from useStaleLayout() and useLayout() are identical when the object is not in a modal state.

Returns

qix.GenericObjectLayout
Required

useStaleLayout

import { useStaleLayout } from '@nebula.js/stardust';
// ...
const staleLayout = useStaleLayout();
console.log(staleLayout);

Gets the layout of the app associated with this visualization.

Returns

qix.NxAppLayout
Required
The app layout

useAppLayout

import { useAppLayout } from '@nebula.js/stardust';
// ...
const appLayout = useAppLayout();
console.log(appLayout.qLocaleInfo);

Gets the generic object API of the generic object connected to this visualization.

Returns

qix.GenericObject | undefined
Required

useModel

import { useModel } from '@nebula.js/stardust';
// ...
const model = useModel();
useEffect(() => {
  model.getInfo().then(info => {
    console.log(info);
  })
}, []);

Gets the doc API.

Returns

qix.Doc | undefined
Required
The doc API.

useApp

import { useApp } from '@nebula.js/stardust';
// ...
const app = useApp();
useEffect(() => {
  app.getAllInfos().then(infos => {
    console.log(infos);
  })
}, []);

Gets the global API.

Returns

qix.Global | undefined
Required
The global API.

useGlobal

import { useGlobal } from '@nebula.js/stardust';

// ...
const g = useGlobal();
useEffect(() => {
  g.engineVersion().then(version => {
    console.log(version);
  })
}, []);

Gets the object selections.

Returns

ObjectSelections
Required
The object selections.
Show properties
- addListener() function
  Required
  Event listener function on instance
  Parameters
  
  eventType string
  Required
  event type that function needs to listen
  
  callback() function
  Required
  a callback function to run when event emits
- removeListener() function
  Required
  Remove listener function on instance
  Parameters
  
  eventType string
  Required
  event type that function needs to listen
  
  callback() function
  Required
  a callback function to run when event emits
- begin() function
  Required
  Parameters
  
  paths Array< string >
  Required
  
  Returns
  
  Promise < undefined >
  Required
- clear() function
  Required
  Returns
  
  Promise < undefined >
  Required
- confirm() function
  Required
  Returns
  
  Promise < undefined >
  Required
- cancel() function
  Required
  Returns
  
  Promise < undefined >
  Required
- select() function
  Required
  Parameters
  
  s object
  Required
  
  Show s properties
  
  method string
  Required
  
  params Array< any >
  Required
  
  Returns
  
  Promise < boolean >
  Required
- canClear() function
  Required
  Returns
  
  boolean
  Required
- canConfirm() function
  Required
  Returns
  
  boolean
  Required
- canCancel() function
  Required
  Returns
  
  boolean
  Required
- isActive() function
  Required
  Returns
  
  boolean
  Required
- isModal() function
  Required
  Returns
  
  boolean
  Required
- goModal() function
  Required
  Parameters
  
  paths Array< string >
  Required
  
  Returns
  
  Promise < undefined >
  Required
- noModal() function
  Required
  Parameters
  
  accept boolean
  default = false
  
  Returns
  
  Promise < undefined >
  Required

useSelections

import { useSelections } from '@nebula.js/stardust';
import { useElement } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const selections = useSelections();
const element = useElement();
useEffect(() => {
  const onClick = () => {
    selections.begin('/qHyperCubeDef');
  };
  element.addEventListener('click', onClick);
  return () => {
    element.removeEventListener('click', onClick);
  };
}, []);

Gets the theme.

Returns

Theme
Required
The theme.
Show properties
- name() function
  Required
  Returns theme name
  Returns
  
  string
  Required
  Current theme.
- getDataColorScales() function
  Required
  Returns
  
  Array< ScalePalette >
  Required
- getDataColorPalettes() function
  Required
  Returns
  
  Array< DataPalette >
  Required
- getDataColorPickerPalettes() function
  Required
  Returns
  
  Array< ColorPickerPalette >
  Required
- getDataColorSpecials() function
  Required
  Returns
  
  DataColorSpecials
  Required
  
  Show properties
  
  primary string
  Required
  
  nil string
  Required
  
  others string
  Required
- getColorPickerColor() function
  Required
  Resolve a color object using the color picker palette from the provided JSON theme.
  Parameters
  
  c object
  Required
  
  Show c properties
  
  index number
  
  color string
  
  supportNone boolean
  Shifts the palette index by one to account for the "none" color
  
  Returns
  
  string
  Required
  The resolved color.
- getContrastingColorTo() function
  Required
  Get the best contrasting color against the specified color. This is typically used to find a suitable text color for a label placed on an arbitrarily colored background.
  
  The returned colors are derived from the theme.
  Parameters
  
  color string
  Required
  A color to measure the contrast against
  
  Returns
  
  string
  Required
  
  The color that has the best contrast against the specified color.
- getStyle() function
  Required
  Get the value of a style attribute in the theme by searching in the theme's JSON structure. The search starts at the specified base path and continues upwards until the value is found. If possible it will get the attribute's value using the given path. When attributes separated by dots are provided, such as 'hover.color', they are required in the theme JSON file
  Parameters
  
  basePath string
  Required
  Base path in the theme's JSON structure to start the search in (specified as a name path separated by dots).
  
  path string
  Required
  Expected path for the attribute (specified as a name path separated by dots).
  
  attribute string
  Required
  Name of the style attribute. (specified as a name attribute separated by dots).
  
  Returns
  
  string | undefined
  Required
  The style value or undefined if not found

useTheme

import { useTheme } from '@nebula.js/stardust';

const theme = useTheme();
console.log(theme.getContrastingColorTo('#ff0000'));

Available since: 1.7.0

Gets the embed instance used.

Returns

Embed
Required
The embed instance used.
Show properties
- render() function
  Required
  Renders a visualization or sheet into an HTMLElement. Visualizations can either be existing objects or created on the fly. Support for sense sheets is experimental.
  Parameters
  
  cfg RenderConfig
  Required
  The render configuration.
  
  Show cfg properties
  
  element HTMLElement
  Required
  Target html element to render in to
  
  options object
  Options passed into the visualisation
  
  onRender() function
  Callback function called after rendering successfully
  
  onError() function
  Callback function called if an error occurs
  Parameters
  
  RenderError
  Required
  
  Show properties
  
  originalError Error
  Required
  
  plugins Array< Plugin >
  plugins passed into the visualisation
  
  id string
  For existing objects: Engine identifier of object to render
  
  type string
  For creating objects: Type of visualisation to render
  
  version string
  For creating objects: Version of visualization to render
  
  fields Array< Field >
  For creating objects: Data fields to use
  
  extendProperties boolean
  For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.
  default = false
  
  properties qix.GenericObjectProperties
  For creating objects: Explicit properties to set
  
  Returns
  
  Promise < Viz | Sheet >
  Required
  A controller to the rendered visualization or sheet.
- create() function
  Required
  Creates a visualization model
  Parameters
  
  cfg CreateConfig
  Required
  The create configuration.
  
  Show cfg properties
  
  type string
  Required
  
  version string
  
  fields Array< Field >
  
  properties qix.GenericObjectProperties
  
  Returns
  
  Promise < qix.GenericObject >
  Required
  An engima model
- generateProperties() function
  Required
  Generates properties for a visualization object
  Parameters
  
  cfg CreateConfig
  Required
  The create configuration.
  
  Returns
  
  Promise < object >
  Required
  The objects properties
- context() function
  Required
  Updates the current context of this embed instance. Use this when you want to change some part of the current context, like theme.
  Parameters
  
  ctx Context
  Required
  The context to update.
  
  Show ctx properties
  
  theme string
  default = "light"
  
  language string
  default = "en-US"
  
  deviceType string
  default = "auto"
  
  constraints Constraints Deprecated
  
  Show constraints properties
  
  passive boolean
  Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
  default = false
  
  active boolean
  Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
  default = false
  
  select boolean
  Whether or not select constraints are on. Should block any selection action. Implied when active is true.
  default = false
  
  edit boolean
  Whether or not edit actions are available. Should block any edit action.
  default = true
  
  interactions Interactions
  
  Show interactions properties
  
  passive boolean
  Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
  default = true
  
  active boolean
  Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
  default = true
  
  select boolean
  Whether or not select interactions are on. Allows selection actions. Implied when active is false.
  default = true
  
  edit boolean
  Whether or not edit actions are on. Allows edit actions.
  default = false
  
  keyboardNavigation boolean
  default = false
  
  disableCellPadding boolean
  default = false
  
  dataViewType string
  Type used for toggling to the data view (toggleDataView) This type need to be registered as well
  default = "sn-table"
  
  Returns
  
  Promise < undefined >
  Required
- selections() function
  Required
  Gets the app selections of this instance.
  Returns
  
  Promise < AppSelections >
  Required
- field() function
  Required
  Available since: 1.1.0
  Gets the listbox instance of the specified field
  Parameters
  
  fieldIdentifier string | LibraryField | QInfo
  Required
  Fieldname as a string, a Library dimension or an object id
  
  Returns
  
  Promise < FieldInstance >
  Required
- getRegisteredTypes() function
  Required
  Gets a list of registered visualization types and versions
  Returns
  
  Array< Object >
  Required
  types

useEmbed

import { useEmbed } from '@nebula.js/stardust';

const embed = useEmbed();
embed.render(...)

Gets the translator.

Returns

Translator
Required
The translator.
Show properties
- language() function
  Required
  Returns current locale.
  Parameters
  
  lang string
  language Locale to updated the currentLocale value
  
  Returns
  
  string
  Required
  current locale.
- add() function
  Required
  Registers a string in multiple locales
  Parameters
  
  item object
  Required
  
  Show item properties
  
  id string
  Required
  
  locale object
  Required
- get() function
  Required
  Translates a string for current locale.
  Parameters
  
  str string
  Required
  ID of the registered string.
  
  args Array< string >
  Values passed down for string interpolation.
  
  Returns
  
  string
  Required
  The translated string.

useTranslator

import { useTranslator } from '@nebula.js/stardust';
// ...
const translator = useTranslator();
console.log(translator.get('SomeString'));

Gets the device type. ('touch' or 'desktop')

Returns

string
Required
device type.

useDeviceType

import { useDeviceType } from '@nebula.js/stardust';
// ...
const deviceType = useDeviceType();
if (deviceType === 'touch') { ... };

Available since: 5.4.0

Gets the navigation api to control sheet navigation. When useNavigation is used in Sense, it returns Sense.navigation.

Returns

Navigation
Required
navigation api.
Show properties
- goToSheet() function
  RequiredExperimental
  Available since: 5.4.0
  Navigate to the supplied sheet and emit 'sheetChanged' event if the target sheet Id is valid. This allows a navigation object to synchronize its current sheet item with the active sheet.
  Parameters
  
  sheetId string
  Required
  Id of the sheet to navigate to
- getCurrentSheetId() function
  RequiredExperimental
  Available since: 5.4.0
  Return the current sheet id
  Returns
  
  string | false
  Required
  The current sheet Id. false means there is no current sheet.

useNavigation

import { useNavigation } from "@nebula.js/stardust";
// ...
const navigation = useNavigation();
const [activeSheetId, setActiveSheetId] = useState(navigation?.getCurrentSheetId() || "");

Gets the array of plugins provided when rendering the visualization.

Returns

Array< Plugin >
Required
array of plugins.

usePlugins

// provide plugins that can be used when rendering
embed(app).render({
  element,
  type: 'my-chart',
  plugins: [plugin]
});

// It's up to the chart implementation to make use of plugins in any way
import { usePlugins } from '@nebula.js/stardust';
// ...
const plugins = usePlugins();
plugins.forEach((plugin) => {
  // Invoke plugin
  plugin.fn();
});

Registers a custom action.

Parameters

factory() function
Required
Returns
- ActionDefinition
  Required
  Show properties
  action A
  Required
  
  hidden boolean
  
  disabled boolean
  
  icon object
  
  Show icon properties
  
  viewBox string
  default = "0 0 16 16"
  
  shapes Array< object >
  Required
deps Array< any >

Returns

A
Required

useAction

import { useAction } from '@nebula.js/stardust';
// ...
const [zoomed, setZoomed] = useState(false);
const act = useAction(() => ({
  hidden: false,
  disabled: zoomed,
  action() {
    setZoomed(prev => !prev);
  },
  icon: {}
}), [zoomed]);

Gets the desired constraints that should be applied when rendering the visualization.

The constraints are set on the embed configuration before the visualization is rendered and should be respected when implementing the visualization.

Returns

Constraints
Required
Show properties
- passive boolean
  Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
  default = false
- active boolean
  Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
  default = false
- select boolean
  Whether or not select constraints are on. Should block any selection action. Implied when active is true.
  default = false
- edit boolean
  Whether or not edit actions are available. Should block any edit action.
  default = true

useConstraints

// configure embed to disallow active interactions when rendering
embed(app, {
 context: {
   constraints: {
     active: true, // do not allow interactions
   }
 }
}).render({ element, id: 'sdfsdf' });

import { useConstraints } from '@nebula.js/stardust';
// ...
const constraints = useConstraints();
useEffect(() => {
  if (constraints.active) {
    // do not add any event listener if active constraint is set
    return undefined;
  }
  const listener = () => {};
  element.addEventListener('click', listener);
  return () => {
    element.removeEventListener('click', listener);
  };
}, [constraints])

Gets the desired interaction states that should be applied when rendering the visualization.

The interactions are set on the embed configuration before the visualization is rendered and should be respected when implementing the visualization.

Returns

Interactions
Required
Show properties
- passive boolean
  Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
  default = true
- active boolean
  Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
  default = true
- select boolean
  Whether or not select interactions are on. Allows selection actions. Implied when active is false.
  default = true
- edit boolean
  Whether or not edit actions are on. Allows edit actions.
  default = false

useInteractionState

// configure embed to disallow active interactions when rendering
embed(app, {
 context: {
   interactions: {
     active: false, // do not allow interactions
   }
 }
}).render({ element, id: 'sdfsdf' });

import { useInteractionState } from '@nebula.js/stardust';
// ...
const interactions = useInteractionState();
useEffect(() => {
  if (!interactions.active) {
    // do not add any event listener if active constraint is set
    return undefined;
  }
  const listener = () => {};
  element.addEventListener('click', listener);
  return () => {
    element.removeEventListener('click', listener);
  };
}, [interactions])

Gets the options object provided when rendering the visualization.

This is an empty object by default but enables customization of the visualization through this object. Options are different from setting properties on the generic object in that options are only temporary settings applied to the visualization when rendered.

You have the responsibility to provide documentation of the options you support, if any.

Returns

object
Required

useOptions

// when embedding the visualization, anything can be set in options
embed(app).render({
  element,
  type: 'my-chart',
  options: {
    showNavigation: true,
  }
});

// it is up to you use and implement the provided options
import { useOptions } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const options = useOptions();
useEffect(() => {
  if (!options.showNavigation) {
    // hide navigation
  } else {
    // show navigation
  }
}, [options.showNavigation]);

This is an empty object by default, but enables you to provide a custom API of your visualization to make it possible to control after it has been rendered.

You can only use this hook once, calling it more than once is considered an error.

Parameters

factory() function
Required
Returns
- T
  Required
deps Array< any >

useImperativeHandle

import { useImperativeHandle } form '@nebula.js/stardust';
// ...
useImperativeHandle(() => ({
  resetZoom() {
    setZoomed(false);
  }
}));

// when embedding the visualization, you can get a handle to this API
// and use it to control the visualization
const ctl = await embed(app).render({
  element,
  type: 'my-chart',
});
ctl.getImperativeHandle().resetZoom();

Registers a callback that is called when a snapshot is taken.

Parameters

snapshotCallback() function
Required
Parameters
- qix.GenericObjectLayout
  Required
Returns
- Promise < qix.GenericObjectLayout >
  Required

onTakeSnapshot

import { onTakeSnapshot } from '@nebula.js/stardust';
import { useState } from '@nebula.js/stardust';
import { useLayout } from '@nebula.js/stardust';

const layout = useLayout();
const [zoomed] = useState(layout.isZoomed || false);

onTakeSnapshot((copyOfLayout) => {
  copyOfLayout.isZoomed = zoomed;
  return Promise.resolve(copyOfLayout);
});

Gets render state instance.

Used to update properties and get a new layout without triggering onInitialRender.

Returns

RenderState
Required
The render state.
Show properties
- pending any
  Required
- restore any
  Required

useRenderState

import { useRenderState } from '@nebula.js/stardust';

const renderState = useRenderState();
useState(() => {
  if(needPropertiesUpdate(...)) {
     useRenderState.pending();
     updateProperties(...);
  } else {
     useRenderState.restore();
     ...
  }
}, [...]);

Gets an event emitter instance for the visualization.

Returns

Emitter
Required
Show properties
- Emitter class
  Required

useEmitter

// In a Nebula visualization
import { useEmitter } from '@nebula.js/stardust';
useEffect(()=> {
  // on some trigger
  emitter.emit("trigger", params)
}, [...])

// In a mashup
const viz = await n.render({
  element: el,
  id: 'abcdef'
});
viz.addListener("trigger", ()=> {
  // do something
})

Gets the desired keyboard settings and status to applied when rendering the visualization. A visualization should in general only have tab stops if either keyboard.enabled is false or if active is true. This means that either Nebula isn't configured to handle keyboard input or the chart is currently focused. Enabling or disabling keyboardNavigation are set on the embed configuration and should be respected by the visualization.

Returns

Keyboard
Required
Show properties
- enabled boolean
  Required
  Whether or not Nebula handles keyboard navigation or not.
- active boolean
  Required
  Set to true when the chart is activated, ie a user tabs to the chart and presses Enter or Space.
- blur() function
  Function used by the visualization to tell Nebula it wants to relinquish focus
  Parameters
  
  boolean
  Required
- focus() function
  Function used by the visualization to tell Nebula it wants to focus
- focusSelection() function
  Function used by the visualization to tell Nebula that focus the selection toolbar
  Parameters
  
  boolean
  Required

useKeyboard

// configure nebula to enable navigation between charts
embed(app, {
  context: {
    keyboardNavigation: true, // tell Nebula to handle navigation
  }
}).render({ element, id: 'sdfsdf' });

import { useKeyboard } from '@nebula.js/stardust';
// ...
const keyboard = useKeyboard();
useEffect(() => {
 // Set a tab stop on our button if in focus or if Nebulas navigation is disabled
 button.setAttribute('tabIndex', keyboard.active || !keyboard.enabled ? 0 : -1);
 // If navigation is enabled and focus has shifted, lets focus the button
 keyboard.enabled && keyboard.active && button.focus();
}, [keyboard])

Available since: 1.1.0

Provides conversion functionality to extensions.

Properties

hypercube hyperCubeConversion
Required
Available since: 1.1.0
Provides conversion functionality to extensions with hyperCubes.
Show hypercube properties
- hyperCubeConversion interface
  Required
  Available since: 1.1.0

Conversion

import { conversion } from '@nebula.js/stardust';

export default function() {
  return {
    qae: {
      ...
      importProperties: ( exportFormat, initialProperties ) =>  conversion.hyperCube.importProperties(exportFormat, initialProperties),
      exportProperties: ( fullPropertyTree ) => conversion.hyperCube.exportProperties(fullPropertyTree)
    },
    ...
  };
}

Mocks Engima app functionality for demo and testing purposes.

Available since: 3.0.0

Mocks Engima app functionality. It accepts one / many generic objects as input argument and returns the mocked Enigma app. Each generic object represents one visualisation and specifies how it behaves. For example, what layout to use the data to present.

The generic object is represented with a Javascript object with a number of properties. The name of the property correlates to the name in the Enigma model for app.getObject(id). For example, the property getLayout in the generic object is used to define app.getObject(id).getLayout(). Any property can be added to the fixture (just make sure it exists and behaves as in the Enigma model!).

The value for each property is either fixed (string / boolean / number / object) or a function. Arguments are forwarded to the function to allow for greater flexibility. For example, this can be used to return different hypercube data when scrolling in the chart.

Parameters

genericObjects Array< object >
Required
Generic objects controlling behaviour of visualizations.
options EnigmaMockerOptions
Options
Show options properties
- delay number
  Required
  Simulate delay (in ms) for calls in enigma-mocker.

Returns

Promise < qix.Doc >
Required

fromGenericObjects

const genericObject = {
  getLayout() {
    return {
      qInfo: {
        qId: 'qqj4zx',
        qType: 'sn-grid-chart'
      },
      ...
    }
  },
  getHyperCubeData(path, page) {
    return [ ... ];
  }
};
const app = await EnigmaMocker.fromGenericObjects([genericObject]);

Properties

key string
Required
The key of the component. Currently supporting components "theme" and "selections".

Component

const n = embed(app);
const inst = await n.field('field_name');
inst.mount(document.querySelector('.listbox'), {
  components: [{
   key: 'theme',
   header: {
     fontColor: { color: '#f00' },
     fontSize: 23,
   },
   content: {
     fontSize: 16,
     useContrastColor: false,
   }
  },{
   key: 'selections',
   colors: {
     selected: { color: '#0f0' },
     alternative: { color: '#ededed' },
     excluded: { color: '#ccc' },
     selectedExcluded: { color: '#bbb' },
     possible: { color: '#fefefe' },
     possible: { color: '#fefefe' },
   }
 }]
});

Fallback load function for missing types

Parameters

LoadType
Required
Show properties
- LoadType interface
  Required
  Parameters
  
  type object
  Required
  
  Show type properties
  
  name string
  Required
  
  version string
  Required
  
  Returns
  
  Promise < Visualization >
  Required

Returns

Promise < Visualization >
Required

Properties

load LoadFallback
Fallback load function for missing types
Show load properties
- LoadFallback() function
  Required
  Fallback load function for missing types
  Parameters
  
  LoadType
  Required
  
  Show properties
  
  LoadType interface
  Required
  Parameters
  
  type object
  Required
  
  Show type properties
  
  name string
  Required
  
  version string
  Required
  
  Returns
  
  Promise < Visualization >
  Required
  
  Returns
  
  Promise < Visualization >
  Required
context Context
Settings for the rendering instance
Show context properties
- theme string
  default = "light"
- language string
  default = "en-US"
- deviceType string
  default = "auto"
- constraints Constraints Deprecated
  
  Show constraints properties
  
  passive boolean
  Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
  default = false
  
  active boolean
  Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
  default = false
  
  select boolean
  Whether or not select constraints are on. Should block any selection action. Implied when active is true.
  default = false
  
  edit boolean
  Whether or not edit actions are available. Should block any edit action.
  default = true
- interactions Interactions
  
  Show interactions properties
  
  passive boolean
  Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
  default = true
  
  active boolean
  Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
  default = true
  
  select boolean
  Whether or not select interactions are on. Allows selection actions. Implied when active is false.
  default = true
  
  edit boolean
  Whether or not edit actions are on. Allows edit actions.
  default = false
- keyboardNavigation boolean
  default = false
- disableCellPadding boolean
  default = false
- dataViewType string
  Type used for toggling to the data view (toggleDataView) This type need to be registered as well
  default = "sn-table"
types Array< TypeInfo >
Visualization types to register
themes Array< ThemeInfo >
Themes to register
hostConfig object
Qlik api compatible host config, see https://github.com/qlik-oss/qlik-api-ts/blob/main/docs/authentication.md#the-host-config
anything object

Configuration

import { embed } from '@nebula.js/stardust'
n = embed(app, {
  context: {
    keyboardNavigation: true,
    theme: 'purple',
  },
  load: ({ name, version }) => {
    if (name === 'linechart') {
      return Promise.resolve(line);
    }
  },
  types: [
    {
      name: 'bar',
      load: () => Promise.resolve(bar),
    },
  ],
  themes: [
    {
      id: 'purple',
      load: () => Promise.resolve(purpleThemeJson),
    },
  ],
});

Properties

theme string
default = "light"
language string
default = "en-US"
deviceType string
default = "auto"
constraints Constraints Deprecated
Show constraints properties
- passive boolean
  Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
  default = false
- active boolean
  Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
  default = false
- select boolean
  Whether or not select constraints are on. Should block any selection action. Implied when active is true.
  default = false
- edit boolean
  Whether or not edit actions are available. Should block any edit action.
  default = true
interactions Interactions
Show interactions properties
- passive boolean
  Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
  default = true
- active boolean
  Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
  default = true
- select boolean
  Whether or not select interactions are on. Allows selection actions. Implied when active is false.
  default = true
- edit boolean
  Whether or not edit actions are on. Allows edit actions.
  default = false
keyboardNavigation boolean
default = false
disableCellPadding boolean
default = false
dataViewType string
Type used for toggling to the data view (toggleDataView) This type need to be registered as well
default = "sn-table"

Properties

translator Translator
Required
Show translator properties
- language() function
  Required
  Returns current locale.
  Parameters
  
  lang string
  language Locale to updated the currentLocale value
  
  Returns
  
  string
  Required
  current locale.
- add() function
  Required
  Registers a string in multiple locales
  Parameters
  
  item object
  Required
  
  Show item properties
  
  id string
  Required
  
  locale object
  Required
- get() function
  Required
  Translates a string for current locale.
  Parameters
  
  str string
  Required
  ID of the registered string.
  
  args Array< string >
  Values passed down for string interpolation.
  
  Returns
  
  string
  Required
  The translated string.
flags Flags
Required
Show flags properties
- isEnabled() function
  Required
  Checks whether the specified flag is enabled.
  Parameters
  
  flag string
  Required
  The value flag to check.
  
  Returns
  
  boolean
  Required
  True if the specified flag is enabled, false otherwise.
deviceType string
Required
hostConfig object
Required
anything object
Required

Renders a visualization or sheet into an HTMLElement. Visualizations can either be existing objects or created on the fly. Support for sense sheets is experimental.

Parameters

cfg RenderConfig
Required
The render configuration.
Show cfg properties
- element HTMLElement
  Required
  Target html element to render in to
- options object
  Options passed into the visualisation
- onRender() function
  Callback function called after rendering successfully
- onError() function
  Callback function called if an error occurs
  Parameters
  
  RenderError
  Required
  
  Show properties
  
  originalError Error
  Required
- plugins Array< Plugin >
  plugins passed into the visualisation
- id string
  For existing objects: Engine identifier of object to render
- type string
  For creating objects: Type of visualisation to render
- version string
  For creating objects: Version of visualization to render
- fields Array< Field >
  For creating objects: Data fields to use
- extendProperties boolean
  For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.
  default = false
- properties qix.GenericObjectProperties
  For creating objects: Explicit properties to set

Returns

Promise < Viz | Sheet >
Required
A controller to the rendered visualization or sheet.

render

// render from existing object
n.render({
  element: el,
  id: 'abcdef'
});

// render on the fly
n.render({
  element: el,
  type: 'barchart',
  fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }]
});

Creates a visualization model

Parameters

cfg CreateConfig
Required
The create configuration.
Show cfg properties
- type string
  Required
- version string
- fields Array< Field >
- properties qix.GenericObjectProperties

Returns

Promise < qix.GenericObject >
Required
An engima model

create

// create a barchart in the app and return the model
const model = await n.create({
    type: 'barchart',
    fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }],
    properties: { showTitle: true }
  }
);

Generates properties for a visualization object

Parameters

cfg CreateConfig
Required
The create configuration.

Returns

Promise < object >
Required
The objects properties

generateProperties

// generate properties for a barchart
const properties = await n.generateProperties({
    type: 'barchart',
    fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }],
    properties: { showTitle: true }
  },
);

Updates the current context of this embed instance. Use this when you want to change some part of the current context, like theme.

Parameters

ctx Context
Required
The context to update.
Show ctx properties
- theme string
  default = "light"
- language string
  default = "en-US"
- deviceType string
  default = "auto"
- constraints Constraints Deprecated
  
  Show constraints properties
  
  passive boolean
  Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
  default = false
  
  active boolean
  Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
  default = false
  
  select boolean
  Whether or not select constraints are on. Should block any selection action. Implied when active is true.
  default = false
  
  edit boolean
  Whether or not edit actions are available. Should block any edit action.
  default = true
- interactions Interactions
  
  Show interactions properties
  
  passive boolean
  Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
  default = true
  
  active boolean
  Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
  default = true
  
  select boolean
  Whether or not select interactions are on. Allows selection actions. Implied when active is false.
  default = true
  
  edit boolean
  Whether or not edit actions are on. Allows edit actions.
  default = false
- keyboardNavigation boolean
  default = false
- disableCellPadding boolean
  default = false
- dataViewType string
  Type used for toggling to the data view (toggleDataView) This type need to be registered as well
  default = "sn-table"

Returns

Promise < undefined >
Required

context

// change theme
n.context({ theme: 'dark'});

// change interactions
n.context({ interactions: { select: false } });

Gets the app selections of this instance.

Returns

Promise < AppSelections >
Required

selections

const selections = await n.selections();
selections.mount(element);

Available since: 1.1.0

Gets the listbox instance of the specified field

Parameters

fieldIdentifier string | LibraryField | QInfo
Required
Fieldname as a string, a Library dimension or an object id

Returns

Promise < FieldInstance >
Required

field

const fieldInstance = await n.field("MyField");
fieldInstance.mount(element, { title: "Hello Field"});

Gets a list of registered visualization types and versions

Returns

Array< Object >
Required
types

getRegisteredTypes

const types = n.getRegisteredTypes();
// Contains
//[
// {
//   name: "barchart"
//   versions:[undefined, "1.2.0"]
// }
//]

Available since: 1.1.0

Event listener function on instance

Parameters

eventType FieldEventTypes
Required
event type that function needs to listen
Show eventType properties
- FieldEventTypes 'selectionActivated' | 'selectionDeactivated'
  Required
callback() function
Required
a callback function to run when event emits

on

const handleSomeEvent () => {...};
fieldInstance.on('someEvent', handleSomeEvent);
...
fieldInstance.removeListener('someEvent', handleSomeEvent);

Remove listener on instance

Parameters

eventType FieldEventTypes
Required
event type
callback() function
Required
handler

Available since: 1.1.0

Mounts the field as a listbox into the provided HTMLElement.

Parameters

element HTMLElement
Required
options object
Settings for the embedded listbox
Show options properties
- title string
  Custom title, defaults to fieldname (not applicable for existing objects)
- direction Direction
  Direction setting ltr|rtl.
  default = "ltr"
  
  Show direction properties
  
  Direction 'ltr' | 'rtl'
  Required
- listLayout ListLayout
  Layout direction vertical|horizontal (not applicable for existing objects)
  default = "vertical"
  
  Show listLayout properties
  
  ListLayout 'vertical' | 'horizontal'
  Required
- frequencyMode FrequencyMode
  Show frequency none|value|percent|relative
  default = "none"
  
  Show frequencyMode properties
  
  FrequencyMode 'none' | 'value' | 'percent' | 'relative'
  Required
- histogram boolean
  Show histogram bar (not applicable for existing objects)
  default = false
- search SearchMode
  Show the search bar permanently, using the toggle button or when in selection: false|true|toggle
  default = true
  
  Show search properties
  
  SearchMode boolean | 'toggle'
  Required
- showLock boolean
  Show the button for toggling locked state.
  default = false
- toolbar boolean
  Show the toolbar
  default = true
- checkboxes boolean
  Show values as checkboxes instead of as fields (not applicable for existing objects)
  default = false
- dense boolean
  Reduces padding and text size (not applicable for existing objects)
  default = false
- stateName string
  Sets the state to make selections in (not applicable for existing objects)
  default = "$"
- components Array< Component >
  Override individual components' styling, otherwise set by the theme or the default style.
- properties object
  Properties object to extend default properties with
  default = "{}"

Returns

Promise < void >
Required
A promise that resolves when the data is fetched.

mount

fieldInstance.mount(element);

Available since: 1.1.0

Unmounts the field listbox from the DOM.

unmount

listbox.unmount();

Properties

id string
Required
Theme identifier

A function that should return a Promise that resolves to a raw JSON theme.

Returns

Promise < ThemeJSON >
Required

Properties

qId string
Required
Generic object id

Available since: 3.1.0

A controller to further modify a visualization after it has been rendered.

Properties

id string
Required
The id of this sheets's generic object.
model string
Required
This sheets Enigma model, a representation of the generic object.
navigation Navigation
RequiredExperimental
Available since: 5.4.0
The navigation api to control sheet navigation.
Show navigation properties
- goToSheet() function
  RequiredExperimental
  Available since: 5.4.0
  Navigate to the supplied sheet and emit 'sheetChanged' event if the target sheet Id is valid. This allows a navigation object to synchronize its current sheet item with the active sheet.
  Parameters
  
  sheetId string
  Required
  Id of the sheet to navigate to
- getCurrentSheetId() function
  RequiredExperimental
  Available since: 5.4.0
  Return the current sheet id
  Returns
  
  string | false
  Required
  The current sheet Id. false means there is no current sheet.

Sheet

const sheet = await embed(app).render({
  element,
  id: "jD5Gd"
});
sheet.destroy();

Destroys the sheet and removes it from the the DOM.

destroy

const sheet = await embed(app).render({
  element,
  id: "jD5Gd"
});
sheet.destroy();

A controller to further modify a visualization after it has been rendered.

Properties

id string
Required
The id of this visualization's generic object.
model qix.GenericObject
Required
This visualizations Enigma model, a representation of the generic object.

Viz

const viz = await embed(app).render({
  element,
  type: 'barchart'
});
viz.destroy();

Destroys the visualization and removes it from the the DOM.

destroy

const viz = await embed(app).render({
  element,
  id: 'abc'
});
viz.destroy();

Available since: 1.1.0

Converts the visualization to a different registered type.

Will update properties if permissions allow, else will patch (can be forced with forcePatch parameter)

Not all chart types are compatible, similar structures are required.

Parameters

newType string
Required
Which registered type to convert to.
forceUpdate boolean
Whether to apply the change or not, else simply returns the resulting properties, defaults to true.
forcePatch boolean
Whether to always patch the change instead of making a permanent change

Returns

Promise < object >
Required
Promise object that resolves to the full property tree of the converted visualization.

convertTo

const viz = await embed(app).render({
  element,
  id: 'abc'
});
await viz.convertTo('barChart');
// Change the barchart to a linechart, only in the current session
const newProperties = await viz.convertTo('lineChart', false, true);
// Remove the conversion by clearing the patches
await viz.model.clearSoftPatches();

Available since: 4.9.0

Toggles the chart to a data view of the chart.

The chart will be toggled to the type defined in the nebula context (dataViewType).

The default dataViewType for nebula is sn-table. The specified chart type needs to be registered as well, in order to make it possible to render the data view.

Parameters

showDataView boolean
If included, forces the chart into a specific state. True will show data view, and false will show the original chart. If not included it will always toggle between the two views.

Listens to custom events from inside the visualization. See useEmitter

Parameters

eventName string
Required
Event name to listen to
listener() function
Required
Callback function to invoke

Removes a listener

Parameters

eventName string
Required
Event name to remove from
listener() function
Required
Callback function to remove

Gets the specific api that a Viz exposes.

Returns

Promise < object >
Required
object that contains the internal Viz api.

Checks whether the specified flag is enabled.

Parameters

flag string
Required
The value flag to check.

Returns

boolean
Required
True if the specified flag is enabled, false otherwise.

Mounts the app selection UI into the provided HTMLElement.

Parameters

element HTMLElement
Required

mount

selections.mount(element);

Unmounts the app selection UI from the DOM.

unmount

selections.unmount();

Event listener function on instance

Parameters

eventType string
Required
event type that function needs to listen
callback() function
Required
a callback function to run when event emits

addListener

api.addListener('someEvent', () => {...});

Remove listener function on instance

Parameters

eventType string
Required
event type that function needs to listen
callback() function
Required
a callback function to run when event emits

removeListener

api.removeListener('someEvent', () => {...});

Parameters

paths Array< string >
Required

Returns

Promise < undefined >
Required

Returns

Promise < undefined >
Required

Returns

Promise < undefined >
Required

Returns

Promise < undefined >
Required

Parameters

s object
Required
Show s properties
- method string
  Required
- params Array< any >
  Required

Returns

Promise < boolean >
Required

Returns

boolean
Required

Returns

boolean
Required

Returns

boolean
Required

Returns

boolean
Required

Returns

boolean
Required

Parameters

paths Array< string >
Required

Returns

Promise < undefined >
Required

Parameters

accept boolean
default = false

Returns

Promise < undefined >
Required

Rendering configuration for creating and rendering a new object

Properties

type string
Required
version string
fields Array< Field >
properties qix.GenericObjectProperties

Configuration for rendering a visualisation, either creating or fetching an existing object.

Properties

element HTMLElement
Required
Target html element to render in to
options object
Options passed into the visualisation
plugins Array< Plugin >
plugins passed into the visualisation
id string
For existing objects: Engine identifier of object to render
type string
For creating objects: Type of visualisation to render
version string
For creating objects: Version of visualization to render
fields Array< Field >
For creating objects: Data fields to use
extendProperties boolean
For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.
default = false
properties qix.GenericObjectProperties
For creating objects: Explicit properties to set

RenderConfig

// A config for Creating objects:
const createConfig = {
  type: 'bar',
  element: document.querySelector('.bar'),
  extendProperties: true,
  fields: ['[Country names]', '=Sum(Sales)'],
  properties: {
    legend: {
      show: false,
    },
  }
};
nebbie.render(createConfig);
// A config for rendering an existing object:
const createConfig = {
  id: 'jG5LP',
  element: document.querySelector('.line'),
};
nebbie.render(createConfig);

Callback function called after rendering successfully

Callback function called if an error occurs

Parameters

RenderError
Required
Show properties
- originalError Error
  Required

Properties

qLibraryId string
Required
type 'dimension' | 'measure'
Required

Available since: 1.2.0

An object literal containing meta information about the plugin and a function containing the plugin implementation.

Properties

info object
Required
Object that can hold various meta info about the plugin
Show info properties
- name string
  Required
  The name of the plugin
fn function
Required
The implementation of the plugin. Input and return value is up to the plugin implementation to decide based on its purpose.

Plugin

const plugin = {
  info: {
    name: "example-plugin",
    type: "meta-type",
  },
  fn: () => {
    // Plugin implementation goes here
  }
};

Parameters

type object
Required
Show type properties
- name string
  Required
- version string
  Required

Returns

Promise < Visualization >
Required

Properties

name string
Required
version string
load LoadType
Required
Show load properties
- LoadType interface
  Required
  Parameters
  
  type object
  Required
  
  Show type properties
  
  name string
  Required
  
  version string
  Required
  
  Returns
  
  Promise < Visualization >
  Required
meta object

extends Error

Properties

originalError Error
Required

Available since: 5.4.0

implements Emitter

The navigation api instance.

Navigation

const navigation = useNavigation();
//...
useEffect(() => {
  const onSheetChanged = () => {
    // do something
  };
  if (navigation?.addListener) {
    navigation.addListener("sheetChanged", onSheetChanged);
  }
  return () => {
    if (navigation?.removeListener) {
      navigation.removeListener("sheetChanged", onSheetChanged);
    }
  };
}, [navigation]);

const onSheetClick = (sheetId: string) => {
  navigation?.goToSheet(sheetId);
};

Available since: 5.4.0

Navigate to the supplied sheet and emit 'sheetChanged' event if the target sheet Id is valid. This allows a navigation object to synchronize its current sheet item with the active sheet.

Parameters

sheetId string
Required
Id of the sheet to navigate to

Available since: 5.4.0

Return the current sheet id

Returns

string | false
Required
The current sheet Id. false means there is no current sheet.

Available since: 2.1.0

extends HTMLElement

Properties

className 'njs-action-toolbar-popover'
Required

Available since: 2.0.0

extends HTMLElement

Properties

className 'njs-cell-action'
Required

extends HTMLElement

Properties

className 'njs-cell'
Required

Available since: 2.0.0

extends HTMLElement

Properties

className 'njs-cell-footer'
Required

Available since: 2.0.0

extends HTMLElement

Properties

className 'njs-cell-title'
Required

Available since: 2.0.0

extends HTMLElement

Properties

className 'njs-cell-sub-title'
Required

Available since: 3.1.0

extends HTMLElement

Properties

className 'njs-sheet'
Required

extends NamedNodeMap

Properties

data-render-count string
Required

extends HTMLElement

Properties

attributes VizElementAttributes
Required
Show attributes properties
- data-render-count string
  Required
className 'njs-viz'
Required

The entry point for defining a visualization.

Parameters

galaxy Galaxy
Required
Show galaxy properties
- translator Translator
  Required
  
  Show translator properties
  
  language() function
  Required
  Returns current locale.
  Parameters
  
  lang string
  language Locale to updated the currentLocale value
  
  Returns
  
  string
  Required
  current locale.
  
  add() function
  Required
  Registers a string in multiple locales
  Parameters
  
  item object
  Required
  
  Show item properties
  
  id string
  Required
  
  locale object
  Required
  
  get() function
  Required
  Translates a string for current locale.
  Parameters
  
  str string
  Required
  ID of the registered string.
  
  args Array< string >
  Values passed down for string interpolation.
  
  Returns
  
  string
  Required
  The translated string.
- flags Flags
  Required
  
  Show flags properties
  
  isEnabled() function
  Required
  Checks whether the specified flag is enabled.
  Parameters
  
  flag string
  Required
  The value flag to check.
  
  Returns
  
  boolean
  Required
  True if the specified flag is enabled, false otherwise.
- deviceType string
  Required
- hostConfig object
  Required
- anything object
  Required

Returns

VisualizationDefinition
Required
Show properties
- qae QAEDefinition
  Required
  
  Show qae properties
  
  properties qix.GenericObjectProperties
  
  data object
  
  Show data properties
  
  targets Array< DataTarget >
  Required
  
  importProperties importProperties
  
  Show importProperties properties
  
  importProperties() function
  Required
  Available since: 1.1.0
  Imports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  exportFormat ExportFormat
  Required
  The export object which is the output of exportProperties.
  
  initialProperties Object
  Initial properties of the target chart.
  
  dataDefinition Object
  Data definition of the target chart.
  
  defaultPropertyValues Object
  Default values for a number of properties of the target chart.
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  Object
  Required
  A properties tree
  
  exportProperties exportProperties
  
  Show exportProperties properties
  
  exportProperties() function
  Required
  Available since: 1.1.0
  Exports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  propertyTree Object
  Required
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  ExportFormat
  Required
  
  Show properties
  
  data Array< ExportDataDef >
  
  properties object
- component() function
  Required
  Returns
  
  void
  Required

Visualization

import { useElement, useLayout } from '@nebula.js/stardust';

export default function() {
  return {
    qae: {
      properties: {
        dude: 'Heisenberg',
      }
    },
    component() {
      const el = useElement();
      const layout = useLayout();
      el.innerHTML = `What's my name? ${layout.dude}!!!`;
    }
  };
}

Properties

qae QAEDefinition
Required
Show qae properties
- properties qix.GenericObjectProperties
- data object
  
  Show data properties
  
  targets Array< DataTarget >
  Required
- importProperties importProperties
  
  Show importProperties properties
  
  importProperties() function
  Required
  Available since: 1.1.0
  Imports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  exportFormat ExportFormat
  Required
  The export object which is the output of exportProperties.
  
  initialProperties Object
  Initial properties of the target chart.
  
  dataDefinition Object
  Data definition of the target chart.
  
  defaultPropertyValues Object
  Default values for a number of properties of the target chart.
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  Object
  Required
  A properties tree
- exportProperties exportProperties
  
  Show exportProperties properties
  
  exportProperties() function
  Required
  Available since: 1.1.0
  Exports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  propertyTree Object
  Required
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  ExportFormat
  Required
  
  Show properties
  
  data Array< ExportDataDef >
  
  properties object

Returns

void
Required

Parameters

newState S | function
Required
The new state

Callback function that should return a function that in turns gets called before the hook runs again or when the component is destroyed. For example to remove any listeners added in the callback itself.

Returns

void | function
Required

Reference object returned from useRef

Properties

current R
Required
Current value

Properties

top number
Required
left number
Required
width number
Required
height number
Required

Properties

action A
Required
hidden boolean
disabled boolean
icon object
Show icon properties
- viewBox string
  default = "0 0 16 16"
- shapes Array< object >
  Required

Properties

passive boolean
Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips
default = false
active boolean
Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click
default = false
select boolean
Whether or not select constraints are on. Should block any selection action. Implied when active is true.
default = false
edit boolean
Whether or not edit actions are available. Should block any edit action.
default = true

Properties

passive boolean
Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips
default = true
active boolean
Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click
default = true
select boolean
Whether or not select interactions are on. Allows selection actions. Implied when active is false.
default = true
edit boolean
Whether or not edit actions are on. Allows edit actions.
default = false

Properties

pending any
Required
restore any
Required

The emitter instance. Implements https://nodejs.org/api/events.html#class-eventemitter.

Properties

enabled boolean
Required
Whether or not Nebula handles keyboard navigation or not.
active boolean
Required
Set to true when the chart is activated, ie a user tabs to the chart and presses Enter or Space.

Function used by the visualization to tell Nebula it wants to relinquish focus

Parameters

boolean
Required

Function used by the visualization to tell Nebula it wants to focus

Function used by the visualization to tell Nebula that focus the selection toolbar

Parameters

boolean
Required

Available since: 1.1.0

Imports properties for a chart with a hypercube.

Parameters

args object
Required
Show args properties
- exportFormat ExportFormat
  Required
  The export object which is the output of exportProperties.
  
  Show exportFormat properties
  
  data Array< ExportDataDef >
  
  properties object
- initialProperties Object
  Initial properties of the target chart.
- dataDefinition Object
  Data definition of the target chart.
- defaultPropertyValues Object
  Default values for a number of properties of the target chart.
- hypercubePath string
  Required
  Reference to the qHyperCubeDef.

Returns

Object
Required
A properties tree

Available since: 1.1.0

Exports properties for a chart with a hypercube.

Parameters

args object
Required
Show args properties
- propertyTree Object
  Required
- hypercubePath string
  Required
  Reference to the qHyperCubeDef.

Returns

ExportFormat
Required
Show properties
- data Array< ExportDataDef >
- properties object

Properties

properties qix.GenericObjectProperties
data object
Show data properties
- targets Array< DataTarget >
  Required
importProperties importProperties
Show importProperties properties
- importProperties() function
  Required
  Available since: 1.1.0
  Imports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  exportFormat ExportFormat
  Required
  The export object which is the output of exportProperties.
  
  initialProperties Object
  Initial properties of the target chart.
  
  dataDefinition Object
  Data definition of the target chart.
  
  defaultPropertyValues Object
  Default values for a number of properties of the target chart.
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  Object
  Required
  A properties tree
exportProperties exportProperties
Show exportProperties properties
- exportProperties() function
  Required
  Available since: 1.1.0
  Exports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  propertyTree Object
  Required
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  ExportFormat
  Required
  
  Show properties
  
  data Array< ExportDataDef >
  
  properties object

Properties

path string
Required
dimensions FieldTarget
Show dimensions properties
- min function | number
  Number or function that returns the minimum number of fields
- max function | number
  Number or function that returns the maximum number of fields
- added fieldTargetAddedCallback
  
  Show added properties
  
  fieldTargetAddedCallback() function
  Required
  Parameters
  
  field T
  Required
  
  properties qix.GenericObjectProperties
  Required
- removed fieldTargetRemovedCallback
  
  Show removed properties
  
  fieldTargetRemovedCallback() function
  Required
  Parameters
  
  field T
  Required
  
  properties qix.GenericObjectProperties
  Required
  
  index number
  Required
measures FieldTarget

Parameters

field T
Required
properties qix.GenericObjectProperties
Required

Parameters

field T
Required
properties qix.GenericObjectProperties
Required
index number
Required

Properties

min function | number
Number or function that returns the minimum number of fields
max function | number
Number or function that returns the maximum number of fields
added fieldTargetAddedCallback
Show added properties
- fieldTargetAddedCallback() function
  Required
  Parameters
  
  field T
  Required
  
  properties qix.GenericObjectProperties
  Required
removed fieldTargetRemovedCallback
Show removed properties
- fieldTargetRemovedCallback() function
  Required
  Parameters
  
  field T
  Required
  
  properties qix.GenericObjectProperties
  Required
  
  index number
  Required

Returns current locale.

Parameters

lang string
language Locale to updated the currentLocale value

Returns

string
Required
current locale.

Registers a string in multiple locales

Parameters

item object
Required
Show item properties
- id string
  Required
- locale object
  Required

add

translator.add({
  id: 'company.hello_user',
  locale: {
    'en-US': 'Hello {0}',
    'sv-SE': 'Hej {0}'
  }
});
translator.get('company.hello_user', ['John']); // Hello John

Translates a string for current locale.

Parameters

str string
Required
ID of the registered string.
args Array< string >
Values passed down for string interpolation.

Returns

string
Required
The translated string.

Returns theme name

Returns

string
Required
Current theme.

name

theme.name();

Returns

Array< ScalePalette >
Required

Returns

Array< DataPalette >
Required

Returns

Array< ColorPickerPalette >
Required

Returns

DataColorSpecials
Required
Show properties
- primary string
  Required
- nil string
  Required
- others string
  Required

Resolve a color object using the color picker palette from the provided JSON theme.

Parameters

c object
Required
Show c properties
- index number
- color string
supportNone boolean
Shifts the palette index by one to account for the "none" color

Returns

string
Required
The resolved color.

getColorPickerColor

theme.getColorPickerColor({ index: 1 });
theme.getColorPickerColor({ index: 1 }, true);
theme.getColorPickerColor({ color: 'red' });

Get the best contrasting color against the specified color. This is typically used to find a suitable text color for a label placed on an arbitrarily colored background.

The returned colors are derived from the theme.

Parameters

color string
Required
A color to measure the contrast against

Returns

string
Required
- The color that has the best contrast against the specified color.

getContrastingColorTo

theme.getContrastingColorTo('#400');

Get the value of a style attribute in the theme by searching in the theme's JSON structure. The search starts at the specified base path and continues upwards until the value is found. If possible it will get the attribute's value using the given path. When attributes separated by dots are provided, such as 'hover.color', they are required in the theme JSON file

Parameters

basePath string
Required
Base path in the theme's JSON structure to start the search in (specified as a name path separated by dots).
path string
Required
Expected path for the attribute (specified as a name path separated by dots).
attribute string
Required
Name of the style attribute. (specified as a name attribute separated by dots).

Returns

string | undefined
Required
The style value or undefined if not found

getStyle

theme.getStyle('object', 'title.main', 'fontSize');
theme.getStyle('object', 'title', 'main.fontSize');
theme.getStyle('object', '', 'title.main.fontSize');
theme.getStyle('', '', 'fontSize');

Available since: 1.1.0

Used for exporting and importing properties between backend models. An object that exports to ExportFormat should put dimensions and measures inside one data group. If an object has two hypercubes, each of the cubes should export dimensions and measures in two separate data groups. An object that imports from this structure is responsible for putting the existing properties where they should be in the new model.

Properties

data Array< ExportDataDef >
properties object

Available since: 1.1.0

Properties

dimensions Array< qix.NxDimension >
Required
measures Array< qix.NxMeasure >
Required
excludedDimensions Array< qix.NxDimension >
Required
excludedMeasures Array< qix.NxMeasure >
Required
interColumnSortOrder Array< number >
Required

Available since: 1.1.0

Properties

importProperties importProperties
Required
Show importProperties properties
- importProperties() function
  Required
  Available since: 1.1.0
  Imports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  exportFormat ExportFormat
  Required
  The export object which is the output of exportProperties.
  
  initialProperties Object
  Initial properties of the target chart.
  
  dataDefinition Object
  Data definition of the target chart.
  
  defaultPropertyValues Object
  Default values for a number of properties of the target chart.
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  Object
  Required
  A properties tree
exportProperties exportProperties
Required
Show exportProperties properties
- exportProperties() function
  Required
  Available since: 1.1.0
  Exports properties for a chart with a hypercube.
  Parameters
  
  args object
  Required
  
  Show args properties
  
  propertyTree Object
  Required
  
  hypercubePath string
  Required
  Reference to the qHyperCubeDef.
  
  Returns
  
  ExportFormat
  Required
  
  Show properties
  
  data Array< ExportDataDef >
  
  properties object

Available since: 1.1.0

implements ConversionType

Available since: 3.0.0

Options for Enigma Mocker

Properties

delay number
Required
Simulate delay (in ms) for calls in enigma-mocker.

Properties

key string
Required
type 'gradient' | 'class-pyramid'
Required
colors Array< string > | Array< Array< string > >
Required

Properties

key string
Required
type 'pyramid' | 'row'
Required
colors Array< string > | Array< Array< string > >
Required

Properties

key string
Required
colors Array< string >
Required

Properties

primary string
Required
nil string
Required
others string
Required

nebula.js: stardust

embed(app, instanceConfig?) function

Parameters

Returns

embed

embed createConfiguration(configuration) function

Parameters

Returns

createConfiguration

useState(initialState) function

Parameters

Returns

useState

useEffect(effect, deps?) function

Parameters

useEffect

useMemo(factory, deps) function

Parameters

Returns

useMemo

useRef(initialValue) function

Parameters

Returns

useRef

usePromise(factory, deps?) function

Parameters

Returns

usePromise

useElement() function

Returns

useElement

useRect() function

Returns

useRect

useLayout() function

Returns

useLayout

useStaleLayout() function

Returns

useStaleLayout

useAppLayout() function

Returns

useAppLayout

useModel() function

Returns

useModel

useApp() function

Returns

useApp

useGlobal() function

Returns

useGlobal

useSelections() function

Returns

useSelections

useTheme() function

Returns

useTheme

useEmbed() function

Returns

useEmbed

useTranslator() function

Returns

useTranslator

useDeviceType() function

Returns

useDeviceType

useNavigation() function

Returns

useNavigation

usePlugins() function

Returns

usePlugins

useAction(factory, deps?) function

Parameters

Returns

useAction

useConstraints() function

Returns

useConstraints