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 JavaScript spec

Conversion namespace

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

node
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)
    },
    ...
  };
}

embed(app, instanceConfig?) function

Initiates a new Embed instance using the specified enigma app.

Parameters

  • app qix.Doc
    Required
  • instanceConfig Configuration
    Show instanceConfig properties
    • anything object
    • context Context

      Settings for the rendering instance

      Show context properties
      • constraints Constraints Deprecated
        Show constraints properties
        • active boolean

          Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

          default = false

        • edit boolean

          Whether or not edit actions are available. Should block any edit action.

          default = true

        • passive boolean

          Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

          default = false

        • select boolean

          Whether or not select constraints are on. Should block any selection action. Implied when active is true.

          default = false

      • dataViewType string

        Type used for toggling to the data view (toggleDataView) This type need to be registered as well

        default = "sn-table"

      • deviceType string

        default = "auto"

      • disableCellPadding boolean

        default = false

      • interactions Interactions
        Show interactions properties
        • active boolean

          Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

          default = true

        • edit boolean

          Whether or not edit actions are on. Allows edit actions.

          default = false

        • passive boolean

          Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

          default = true

        • select boolean

          Whether or not select interactions are on. Allows selection actions. Implied when active is false.

          default = true

      • keyboardNavigation boolean

        default = false

      • language string

        default = "en-US"

      • navigation Navigation
        Show navigation properties
        • 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.

        • 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
      • theme string

        default = "light"

    • hostConfig object

      Qlik api compatible host config, see https://github.com/qlik-oss/qlik-api-ts/blob/main/docs/authentication.md#the-host-config

    • 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
        Returns
    • themes Array< ThemeInfo >

      Themes to register

    • types Array< TypeInfo >

      Visualization types to register

Returns

  • Embed
    Required
    Show 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
      Returns
      • Promise < undefined >
        Required
    • create() function
      Required

      Creates a visualization model

      Parameters
      • cfg CreateConfig
        Required

        The create configuration.

        Show cfg properties
        • type string
          Required
        • fields Array< Field >
        • properties qix.GenericObjectProperties
        • version string
      Returns
      • Promise < qix.GenericObject >
        Required

        An engima model

    • 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
    • generateProperties() function
      Required

      Generates properties for a visualization object

      Parameters
      Returns
      • Promise < object >
        Required

        The objects properties

    • getRegisteredTypes() function
      Required

      Gets a list of registered visualization types and versions

      Returns
      • Array< Object >
        Required

        types

    • 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

        • extendProperties boolean

          For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.

          default = false

        • fields Array< Field >

          For creating objects: Data fields to use

        • id string

          For existing objects: Engine identifier of object to render

        • onError() function

          Callback function called if an error occurs. Also called with AbortError when signal aborts.

          Parameters
          • RenderError
            Required
            Show properties
            • originalError Error
              Required
        • onRender() function

          Callback function called after rendering successfully

        • options object

          Options passed into the visualisation

        • plugins Array< Plugin >

          plugins passed into the visualisation

        • properties qix.GenericObjectProperties

          For creating objects: Explicit properties to set

        • signal AbortSignal

          Optional AbortSignal to cancel the render operation. When aborted, destroy() is called for cleanup before onError() is called with the AbortError.

        • type string

          For creating objects: Type of visualisation to render

        • version string

          For creating objects: Version of visualization to render
      Returns
      • Promise < Viz  |  Sheet >
        Required

        A controller to the rendered visualization or sheet.

    • selections() function
      Required

      Gets the app selections of this instance.

      Returns

embed

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

embed createConfiguration(configuration) function

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

    Show configuration properties
    • anything object
    • context Context

      Settings for the rendering instance

      Show context properties
      • constraints Constraints Deprecated
        Show constraints properties
        • active boolean

          Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

          default = false

        • edit boolean

          Whether or not edit actions are available. Should block any edit action.

          default = true

        • passive boolean

          Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

          default = false

        • select boolean

          Whether or not select constraints are on. Should block any selection action. Implied when active is true.

          default = false

      • dataViewType string

        Type used for toggling to the data view (toggleDataView) This type need to be registered as well

        default = "sn-table"

      • deviceType string

        default = "auto"

      • disableCellPadding boolean

        default = false

      • interactions Interactions
        Show interactions properties
        • active boolean

          Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

          default = true

        • edit boolean

          Whether or not edit actions are on. Allows edit actions.

          default = false

        • passive boolean

          Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

          default = true

        • select boolean

          Whether or not select interactions are on. Allows selection actions. Implied when active is false.

          default = true

      • keyboardNavigation boolean

        default = false

      • language string

        default = "en-US"

      • navigation Navigation
        Show navigation properties
        • 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.

        • 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
      • theme string

        default = "light"

    • hostConfig object

      Qlik api compatible host config, see https://github.com/qlik-oss/qlik-api-ts/blob/main/docs/authentication.md#the-host-config

    • 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
        Returns
    • themes Array< ThemeInfo >

      Themes to register

    • types Array< TypeInfo >

      Visualization types to register

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
      Returns

createConfiguration

node
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

EnigmaMocker namespace

Mocks Engima app functionality for demo and testing purposes.

EnigmaMocker fromGenericObjects(genericObjects, options?) function

Experimental
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.

    • appMethods object

      Object with methods to add to the mocked app.

Returns

  • Promise < qix.Doc >
    Required

fromGenericObjects

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

onTakeSnapshot(snapshotCallback) function

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

node
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);
});

useAction(factory, deps?) function

Registers a custom action.

Parameters

  • factory() function
    Required
    Returns
    • ActionDefinition
      Required
      Show properties
      • action A
        Required
      • disabled boolean
      • hidden boolean
      • icon object
        Show icon properties
        • viewBox string

          default = "0 0 16 16"

        • shapes Array< object >
          Required
  • deps Array< any >

Returns

  • A
    Required

useAction

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

useApp() function

Gets the doc API.

Returns

  • qix.Doc  |  undefined
    Required

    The doc API.

useApp

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

useAppLayout() function

Gets the layout of the app associated with this visualization.

Returns

  • qix.NxAppLayout
    Required

    The app layout

useAppLayout

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

useConstraints() function

Deprecated

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
    • active boolean

      Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

      default = false

    • edit boolean

      Whether or not edit actions are available. Should block any edit action.

      default = true

    • passive boolean

      Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

      default = false

    • select boolean

      Whether or not select constraints are on. Should block any selection action. Implied when active is true.

      default = false

useConstraints

node
// configure embed to disallow active interactions when rendering
embed(app, {
 context: {
   constraints: {
     active: true, // do not allow interactions
   }
 }
}).render({ element, id: 'sdfsdf' });
node
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])

useDeviceType() function

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

Returns

  • string
    Required

    device type.

useDeviceType

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

useEffect(effect, deps?) function

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

node
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);
  };
}, []);

useElement() function

Gets the HTMLElement this visualization is rendered into.

Returns

  • HTMLElement
    Required

useElement

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

useEmbed() function

Available since: 1.7.0

Gets the embed instance used.

Returns

  • Embed
    Required

    The embed instance used.

    Show 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
        • constraints Constraints Deprecated
          Show constraints properties
          • active boolean

            Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

            default = false

          • edit boolean

            Whether or not edit actions are available. Should block any edit action.

            default = true

          • passive boolean

            Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

            default = false

          • select boolean

            Whether or not select constraints are on. Should block any selection action. Implied when active is true.

            default = false

        • dataViewType string

          Type used for toggling to the data view (toggleDataView) This type need to be registered as well

          default = "sn-table"

        • deviceType string

          default = "auto"

        • disableCellPadding boolean

          default = false

        • interactions Interactions
          Show interactions properties
          • active boolean

            Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

            default = true

          • edit boolean

            Whether or not edit actions are on. Allows edit actions.

            default = false

          • passive boolean

            Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

            default = true

          • select boolean

            Whether or not select interactions are on. Allows selection actions. Implied when active is false.

            default = true

        • keyboardNavigation boolean

          default = false

        • language string

          default = "en-US"

        • navigation Navigation
          Show navigation properties
          • 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.

          • 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
        • theme string

          default = "light"

      Returns
      • Promise < undefined >
        Required
    • create() function
      Required

      Creates a visualization model

      Parameters
      • cfg CreateConfig
        Required

        The create configuration.

        Show cfg properties
        • type string
          Required
        • fields Array< Field >
        • properties qix.GenericObjectProperties
        • version string
      Returns
      • Promise < qix.GenericObject >
        Required

        An engima model

    • 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
    • generateProperties() function
      Required

      Generates properties for a visualization object

      Parameters
      Returns
      • Promise < object >
        Required

        The objects properties

    • getRegisteredTypes() function
      Required

      Gets a list of registered visualization types and versions

      Returns
      • Array< Object >
        Required

        types

    • 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

        • extendProperties boolean

          For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.

          default = false

        • fields Array< Field >

          For creating objects: Data fields to use

        • id string

          For existing objects: Engine identifier of object to render

        • onError() function

          Callback function called if an error occurs. Also called with AbortError when signal aborts.

          Parameters
          • RenderError
            Required
            Show properties
            • originalError Error
              Required
        • onRender() function

          Callback function called after rendering successfully

        • options object

          Options passed into the visualisation

        • plugins Array< Plugin >

          plugins passed into the visualisation

        • properties qix.GenericObjectProperties

          For creating objects: Explicit properties to set

        • signal AbortSignal

          Optional AbortSignal to cancel the render operation. When aborted, destroy() is called for cleanup before onError() is called with the AbortError.

        • type string

          For creating objects: Type of visualisation to render

        • version string

          For creating objects: Version of visualization to render
      Returns
      • Promise < Viz  |  Sheet >
        Required

        A controller to the rendered visualization or sheet.

    • selections() function
      Required

      Gets the app selections of this instance.

      Returns

useEmbed

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


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

useEmitter() function

Gets an event emitter instance for the visualization.

Returns

  • Emitter
    Required
    Show properties
    • Emitter class
      Required

useEmitter

node
// 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
})

useGlobal() function

Gets the global API.

Returns

  • qix.Global  |  undefined
    Required

    The global API.

useGlobal

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


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

useImperativeHandle(factory, deps?) function

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

node
import { useImperativeHandle } form '@nebula.js/stardust';
// ...
useImperativeHandle(() => ({
  resetZoom() {
    setZoomed(false);
  }
}));
node
// 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();

useInteractionState() function

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
    • active boolean

      Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

      default = true

    • edit boolean

      Whether or not edit actions are on. Allows edit actions.

      default = false

    • passive boolean

      Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

      default = true

    • select boolean

      Whether or not select interactions are on. Allows selection actions. Implied when active is false.

      default = true

useInteractionState

node
// configure embed to disallow active interactions when rendering
embed(app, {
 context: {
   interactions: {
     active: false, // do not allow interactions
   }
 }
}).render({ element, id: 'sdfsdf' });
node
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])

useKeyboard() function

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
    • active boolean
      Required

      Set to true when the chart is activated, ie a user tabs to the chart and presses Enter or Space.

    • enabled boolean
      Required

      Whether or not Nebula handles keyboard navigation or not.

    • 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

node
// configure nebula to enable navigation between charts
embed(app, {
  context: {
    keyboardNavigation: true, // tell Nebula to handle navigation
  }
}).render({ element, id: 'sdfsdf' });
node
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])

useLayout() function

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

Returns

  • qix.GenericObjectLayout
    Required

useLayout

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

useMemo(factory, deps) function

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

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

useModel() function

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

Returns

  • qix.GenericObject  |  undefined
    Required

useModel

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

useNavigation() function

Experimental
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
    • 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.

    • 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

useNavigation

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

useOptions() function

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

node
// when embedding the visualization, anything can be set in options
embed(app).render({
  element,
  type: 'my-chart',
  options: {
    showNavigation: true,
  }
});
node
// 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]);

usePlugins() function

Gets the array of plugins provided when rendering the visualization.

Returns

  • Array< Plugin >
    Required

    array of plugins.

usePlugins

node
// provide plugins that can be used when rendering
embed(app).render({
  element,
  type: 'my-chart',
  plugins: [plugin]
});
node
// 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();
});

usePromise(factory, deps?) function

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

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

useRect() function

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

Returns

  • Rect
    Required

    The size of the element.

    Show properties
    • height number
      Required
    • left number
      Required
    • top number
      Required
    • width number
      Required

useRect

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

useRef(initialValue) function

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

node
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]);

useRenderState() function

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

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


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

useSelections() function

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

    • begin() function
      Required
      Parameters
      • paths Array< string >
        Required
      Returns
      • Promise < undefined >
        Required
    • canCancel() function
      Required
      Returns
      • boolean
        Required
    • cancel() function
      Required
      Returns
      • Promise < undefined >
        Required
    • canClear() function
      Required
      Returns
      • boolean
        Required
    • canConfirm() function
      Required
      Returns
      • boolean
        Required
    • clear() function
      Required
      Returns
      • Promise < undefined >
        Required
    • confirm() function
      Required
      Returns
      • Promise < undefined >
        Required
    • goModal() function
      Required
      Parameters
      • paths Array< string >
        Required
      Returns
      • Promise < undefined >
        Required
    • isActive() function
      Required
      Returns
      • boolean
        Required
    • isModal() function
      Required
      Returns
      • boolean
        Required
    • noModal() function
      Required
      Parameters
      • accept boolean

        default = false

      Returns
      • Promise < undefined >
        Required
    • 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

    • select() function
      Required
      Parameters
      • s object
        Required
        Show s properties
        • method string
          Required
        • params Array< any >
          Required
      Returns
      • Promise < boolean >
        Required

useSelections

node
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);
  };
}, []);

useStaleLayout() function

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

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

useState(initialState) function

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

node
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());

useTheme() function

Gets the theme.

Returns

  • Theme
    Required

    The theme.

    Show properties
    • getColorPickerColor() function
      Required

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

      Parameters
      • c object
        Required
        Show c properties
        • color string
        • index number
      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.
    • getDataColorPalettes() function
      Required
      Returns
    • getDataColorPickerPalettes() function
      Required
      Returns
    • getDataColorScales() function
      Required
      Returns
    • getDataColorSpecials() function
      Required
      Returns
      • DataColorSpecials
        Required
        Show properties
        • nil string
          Required
        • others string
          Required
        • primary string
          Required
    • 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

    • name() function
      Required

      Returns theme name

      Returns
      • string
        Required

        Current theme.

useTheme

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


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

useTranslator() function

Gets the translator.

Returns

  • Translator
    Required

    The translator.

    Show properties
    • 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.

    • language() function
      Required

      Returns current locale.

      Parameters
      • lang string

        language Locale to updated the currentLocale value

      Returns
      • string
        Required

        current locale.

useTranslator

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

ActionDefinition interface

Properties

  • action A
    Required
  • disabled boolean
  • hidden boolean
  • icon object
    Show icon properties
    • viewBox string

      default = "0 0 16 16"

    • shapes Array< object >
      Required

ActionElement interface

Available since: 2.0.0
extends HTMLElement

Properties

  • className 'njs-cell-action'
    Required

ActionToolbarElement interface

Available since: 2.1.0
extends HTMLElement

Properties

  • className 'njs-action-toolbar-popover'
    Required

new AppSelections() class

AppSelections mount(element) function

Mounts the app selection UI into the provided HTMLElement.

Parameters

  • element HTMLElement
    Required

mount

node
selections.mount(element);

AppSelections unmount() function

Unmounts the app selection UI from the DOM.

unmount

node
selections.unmount();

CellBody interface

extends HTMLElement

Properties

  • className 'njs-cell-body'
    Required

CellElement interface

extends HTMLElement

Properties

  • className 'njs-cell'
    Required

CellFooter interface

Available since: 2.0.0
extends HTMLElement

Properties

  • className 'njs-cell-footer'
    Required

CellSubTitle interface

Available since: 2.0.0
extends HTMLElement

Properties

  • className 'njs-cell-sub-title'
    Required

CellTitle interface

Available since: 2.0.0
extends HTMLElement

Properties

  • className 'njs-cell-title'
    Required

Component interface

Properties

  • key string
    Required

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

Component

node
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' },
   }
 }]
});

Configuration interface

Properties

  • anything object
  • context Context

    Settings for the rendering instance

    Show context properties
    • constraints Constraints Deprecated
      Show constraints properties
      • active boolean

        Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

        default = false

      • edit boolean

        Whether or not edit actions are available. Should block any edit action.

        default = true

      • passive boolean

        Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

        default = false

      • select boolean

        Whether or not select constraints are on. Should block any selection action. Implied when active is true.

        default = false

    • dataViewType string

      Type used for toggling to the data view (toggleDataView) This type need to be registered as well

      default = "sn-table"

    • deviceType string

      default = "auto"

    • disableCellPadding boolean

      default = false

    • interactions Interactions
      Show interactions properties
      • active boolean

        Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

        default = true

      • edit boolean

        Whether or not edit actions are on. Allows edit actions.

        default = false

      • passive boolean

        Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

        default = true

      • select boolean

        Whether or not select interactions are on. Allows selection actions. Implied when active is false.

        default = true

    • keyboardNavigation boolean

      default = false

    • language string

      default = "en-US"

    • navigation Navigation
      Show navigation properties
      • 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.

      • 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
    • theme string

      default = "light"

  • hostConfig object

    Qlik api compatible host config, see https://github.com/qlik-oss/qlik-api-ts/blob/main/docs/authentication.md#the-host-config

  • 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
      Returns
  • themes Array< ThemeInfo >

    Themes to register

  • types Array< TypeInfo >

    Visualization types to register

Configuration

node
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),
    },
  ],
});

Constraints interface

Deprecated

Properties

  • active boolean

    Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

    default = false

  • edit boolean

    Whether or not edit actions are available. Should block any edit action.

    default = true

  • passive boolean

    Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

    default = false

  • select boolean

    Whether or not select constraints are on. Should block any selection action. Implied when active is true.

    default = false

Context interface

Properties

  • constraints Constraints Deprecated
    Show constraints properties
    • active boolean

      Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

      default = false

    • edit boolean

      Whether or not edit actions are available. Should block any edit action.

      default = true

    • passive boolean

      Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

      default = false

    • select boolean

      Whether or not select constraints are on. Should block any selection action. Implied when active is true.

      default = false

  • dataViewType string

    Type used for toggling to the data view (toggleDataView) This type need to be registered as well

    default = "sn-table"

  • deviceType string

    default = "auto"

  • disableCellPadding boolean

    default = false

  • interactions Interactions
    Show interactions properties
    • active boolean

      Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

      default = true

    • edit boolean

      Whether or not edit actions are on. Allows edit actions.

      default = false

    • passive boolean

      Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

      default = true

    • select boolean

      Whether or not select interactions are on. Allows selection actions. Implied when active is false.

      default = true

  • keyboardNavigation boolean

    default = false

  • language string

    default = "en-US"

  • navigation Navigation
    Show navigation properties
    • 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.

    • 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
  • theme string

    default = "light"

ConversionType interface

Available since: 1.1.0

Properties

  • 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
        • hypercubePath string
          Required

          Reference to the qHyperCubeDef.

        • propertyTree Object
          Required
      Returns
  • 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.

        • hypercubePath string
          Required

          Reference to the qHyperCubeDef.

        • dataDefinition Object

          Data definition of the target chart.

        • defaultPropertyValues Object

          Default values for a number of properties of the target chart.

        • initialProperties Object

          Initial properties of the target chart.
      Returns
      • Object
        Required

        A properties tree

CreateConfig interface

Rendering configuration for creating and rendering a new object

Properties

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

DataTarget interface

Properties

  • path string
    Required
  • dimensions FieldTarget
    Show dimensions properties
    • added fieldTargetAddedCallback
      Show added properties
      • fieldTargetAddedCallback() function
        Required
        Parameters
        • field T
          Required
        • properties qix.GenericObjectProperties
          Required
    • max function  |  number

      Number or function that returns the maximum number of fields

    • min function  |  number

      Number or function that returns the minimum number of fields

    • removed fieldTargetRemovedCallback
      Show removed properties
      • fieldTargetRemovedCallback() function
        Required
        Parameters
        • field T
          Required
        • properties qix.GenericObjectProperties
          Required
        • index number
          Required
  • measures FieldTarget

Direction 'ltr'  |  'rtl'

EffectCallback() function

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

new Embed() class

Embed context(ctx) function

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
    • constraints Constraints Deprecated
      Show constraints properties
      • active boolean

        Whether or not active constraints are on. Should block any active interaction by users, ie: scroll, click

        default = false

      • edit boolean

        Whether or not edit actions are available. Should block any edit action.

        default = true

      • passive boolean

        Whether or not passive constraints are on. Should block any passive interaction by users, ie: tooltips

        default = false

      • select boolean

        Whether or not select constraints are on. Should block any selection action. Implied when active is true.

        default = false

    • dataViewType string

      Type used for toggling to the data view (toggleDataView) This type need to be registered as well

      default = "sn-table"

    • deviceType string

      default = "auto"

    • disableCellPadding boolean

      default = false

    • interactions Interactions
      Show interactions properties
      • active boolean

        Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

        default = true

      • edit boolean

        Whether or not edit actions are on. Allows edit actions.

        default = false

      • passive boolean

        Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

        default = true

      • select boolean

        Whether or not select interactions are on. Allows selection actions. Implied when active is false.

        default = true

    • keyboardNavigation boolean

      default = false

    • language string

      default = "en-US"

    • navigation Navigation
      Show navigation properties
      • 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.

      • 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
    • theme string

      default = "light"

Returns

  • Promise < undefined >
    Required

context

node
// change theme
n.context({ theme: 'dark'});
node
// change interactions
n.context({ interactions: { select: false } });

Embed create(cfg) function

Creates a visualization model

Parameters

  • cfg CreateConfig
    Required

    The create configuration.

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

Returns

  • Promise < qix.GenericObject >
    Required

    An engima model

create

node
// 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 }
  }
);

Embed field(fieldIdentifier) function

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

field

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

Embed generateProperties(cfg) function

Generates properties for a visualization object

Parameters

  • cfg CreateConfig
    Required

    The create configuration.

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

Returns

  • Promise < object >
    Required

    The objects properties

generateProperties

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

Embed getRegisteredTypes() function

Gets a list of registered visualization types and versions

Returns

  • Array< Object >
    Required

    types

getRegisteredTypes

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

Embed render(cfg) function

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

    • extendProperties boolean

      For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.

      default = false

    • fields Array< Field >

      For creating objects: Data fields to use

    • id string

      For existing objects: Engine identifier of object to render

    • onError() function

      Callback function called if an error occurs. Also called with AbortError when signal aborts.

      Parameters
      • RenderError
        Required
        Show properties
        • originalError Error
          Required
    • onRender() function

      Callback function called after rendering successfully

    • options object

      Options passed into the visualisation

    • plugins Array< Plugin >

      plugins passed into the visualisation

    • properties qix.GenericObjectProperties

      For creating objects: Explicit properties to set

    • signal AbortSignal

      Optional AbortSignal to cancel the render operation. When aborted, destroy() is called for cleanup before onError() is called with the AbortError.

    • type string

      For creating objects: Type of visualisation to render

    • version string

      For creating objects: Version of visualization to render

Returns

  • Promise < Viz  |  Sheet >
    Required

    A controller to the rendered visualization or sheet.

render

node
// render from existing object
n.render({
  element: el,
  id: 'abcdef'
});
node
// render on the fly
n.render({
  element: el,
  type: 'barchart',
  fields: ['Product', { qLibraryId: 'u378hn', type: 'measure' }]
});
node
// with AbortSignal
const controller = new AbortController();
n.render({
  element: el,
  type: 'barchart',
  fields: ['Product', '=Sum(Sales)'],
  signal: controller.signal
});
// Later: cancel the render
controller.abort();

Embed selections() function

Gets the app selections of this instance.

Returns

selections

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

new Emitter() class

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

EnigmaMockerOptions interface

Experimental
Available since: 3.0.0

Options for Enigma Mocker

Properties

  • delay number
    Required

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

  • appMethods object

    Object with methods to add to the mocked app.

ExportDataDef interface

Available since: 1.1.0

Properties

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

ExportFormat interface

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

exportProperties(args) function

Available since: 1.1.0

Exports properties for a chart with a hypercube.

Parameters

  • args object
    Required
    Show args properties
    • hypercubePath string
      Required

      Reference to the qHyperCubeDef.

    • propertyTree Object
      Required

Returns

Field string  |  qix.NxDimension  |  qix.NxMeasure  |  LibraryField

FieldEventTypes 'selectionActivated'  |  'selectionDeactivated'

new FieldInstance() class

Available since: 1.1.0

FieldInstance mount(element, options?) function

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
    • checkboxes boolean

      Show values as checkboxes instead of as fields (not applicable for existing objects)

      default = false

    • components Array< Component >

      Override individual components' styling, otherwise set by the theme or the default style.

    • dense boolean

      Reduces padding and text size (not applicable for existing objects)

      default = false

    • direction Direction

      Direction setting ltr|rtl.

      default = "ltr"

      Show direction properties
      • Direction 'ltr'  |  'rtl'
        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

    • listLayout ListLayout

      Layout direction vertical|horizontal (not applicable for existing objects)

      default = "vertical"

      Show listLayout properties
      • ListLayout 'vertical'  |  'horizontal'
        Required
    • properties object

      Properties object to extend default properties with

      default = "{}"

    • 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

    • stateName string

      Sets the state to make selections in (not applicable for existing objects)

      default = "$"

    • title string

      Custom title, defaults to fieldname (not applicable for existing objects)

    • toolbar boolean

      Show the toolbar

      default = true

    • toolbarMode ToolbarMode

      Toolbar placement mode: attach, detach, or auto.

      default = "auto"

      Show toolbarMode properties
      • ToolbarMode 'attach'  |  'detach'  |  'auto'
        Required

Returns

  • Promise < void >
    Required

    A promise that resolves when the data is fetched.

mount

node
fieldInstance.mount(element);

FieldInstance on(eventType, callback) function

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

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

FieldInstance removeListener(eventType, callback) function

Remove listener on instance

Parameters

  • eventType FieldEventTypes
    Required

    event type

    Show eventType properties
    • FieldEventTypes 'selectionActivated'  |  'selectionDeactivated'
      Required
  • callback() function
    Required

    handler

FieldInstance unmount() function

Available since: 1.1.0

Unmounts the field listbox from the DOM.

unmount

node
listbox.unmount();

FieldTarget interface

Properties

  • added fieldTargetAddedCallback
    Show added properties
    • fieldTargetAddedCallback() function
      Required
      Parameters
      • field T
        Required
      • properties qix.GenericObjectProperties
        Required
  • max function  |  number

    Number or function that returns the maximum number of fields

  • min function  |  number

    Number or function that returns the minimum number of fields

  • removed fieldTargetRemovedCallback
    Show removed properties
    • fieldTargetRemovedCallback() function
      Required
      Parameters
      • field T
        Required
      • properties qix.GenericObjectProperties
        Required
      • index number
        Required

fieldTargetAddedCallback(field, properties) function

Parameters

  • field T
    Required
  • properties qix.GenericObjectProperties
    Required

fieldTargetRemovedCallback(field, properties, index) function

Parameters

  • field T
    Required
  • properties qix.GenericObjectProperties
    Required
  • index number
    Required

Flags interface

Flags isEnabled(flag) function

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.

FrequencyMode 'none'  |  'value'  |  'percent'  |  'relative'

Galaxy interface

Properties

  • anything object
    Required
  • deviceType string
    Required
  • 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.
  • hostConfig object
    Required
  • theme Theme
    Required
    Show theme properties
    • getColorPickerColor() function
      Required

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

      Parameters
      • c object
        Required
        Show c properties
        • color string
        • index number
      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.
    • getDataColorPalettes() function
      Required
      Returns
    • getDataColorPickerPalettes() function
      Required
      Returns
    • getDataColorScales() function
      Required
      Returns
    • getDataColorSpecials() function
      Required
      Returns
      • DataColorSpecials
        Required
        Show properties
        • nil string
          Required
        • others string
          Required
        • primary string
          Required
    • 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

    • name() function
      Required

      Returns theme name

      Returns
      • string
        Required

        Current theme.
  • translator Translator
    Required
    Show translator properties
    • 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.

    • language() function
      Required

      Returns current locale.

      Parameters
      • lang string

        language Locale to updated the currentLocale value

      Returns
      • string
        Required

        current locale.

hyperCubeConversion interface

Available since: 1.1.0
implements ConversionType

importProperties(args) function

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
    • hypercubePath string
      Required

      Reference to the qHyperCubeDef.

    • dataDefinition Object

      Data definition of the target chart.

    • defaultPropertyValues Object

      Default values for a number of properties of the target chart.

    • initialProperties Object

      Initial properties of the target chart.

Returns

  • Object
    Required

    A properties tree

Interactions interface

Properties

  • active boolean

    Whether or not active interactions are on. Allows active interaction by users, ie: scroll, click

    default = true

  • edit boolean

    Whether or not edit actions are on. Allows edit actions.

    default = false

  • passive boolean

    Whether or not passive interactions are on. Allows passive interaction by users, ie: tooltips

    default = true

  • select boolean

    Whether or not select interactions are on. Allows selection actions. Implied when active is false.

    default = true

Keyboard interface

Properties

  • active boolean
    Required

    Set to true when the chart is activated, ie a user tabs to the chart and presses Enter or Space.

  • enabled boolean
    Required

    Whether or not Nebula handles keyboard navigation or not.

Keyboard blur(undefined) function

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

Parameters

  • boolean
    Required

Keyboard focus() function

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

Keyboard focusSelection(undefined) function

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

Parameters

  • boolean
    Required

LibraryField interface

Properties

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

ListLayout 'vertical'  |  'horizontal'

LoadFallback(undefined) function

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

Returns

LoadType interface

Parameters

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

Returns

move(array, oldIndex, newIndex) function

Move an element from position old_index to position new_index in the array.

Parameters

  • array any
    Required
  • oldIndex any
    Required
  • newIndex any
    Required

new Navigation() class

Experimental
Available since: 5.4.0
implements Emitter

The navigation api instance.

Navigation

node
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);
};

Navigation getCurrentSheetId() function

Experimental
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.

Navigation goToSheet(sheetId) function

Experimental
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

new ObjectSelections() class

ObjectSelections addListener(eventType, callback) function

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

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

ObjectSelections begin(paths) function

Parameters

  • paths Array< string >
    Required

Returns

  • Promise < undefined >
    Required

ObjectSelections canCancel() function

Returns

  • boolean
    Required

ObjectSelections cancel() function

Returns

  • Promise < undefined >
    Required

ObjectSelections canClear() function

Returns

  • boolean
    Required

ObjectSelections canConfirm() function

Returns

  • boolean
    Required

ObjectSelections clear() function

Returns

  • Promise < undefined >
    Required

ObjectSelections confirm() function

Returns

  • Promise < undefined >
    Required

ObjectSelections goModal(paths) function

Parameters

  • paths Array< string >
    Required

Returns

  • Promise < undefined >
    Required

ObjectSelections isActive() function

Returns

  • boolean
    Required

ObjectSelections isModal() function

Returns

  • boolean
    Required

ObjectSelections noModal(accept?) function

Parameters

  • accept boolean

    default = false

Returns

  • Promise < undefined >
    Required

ObjectSelections removeListener(eventType, callback) function

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

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

ObjectSelections select(s) function

Parameters

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

Returns

  • Promise < boolean >
    Required

onPropertyChange(properties) function

Parameters

  • properties qix.GenericObjectProperties
    Required

Plugin interface

Experimental
Available since: 1.2.0

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

Properties

  • fn function
    Required

    The implementation of the plugin. Input and return value is up to the plugin implementation to decide based on its purpose.

  • info object
    Required

    Object that can hold various meta info about the plugin

    Show info properties
    • name string
      Required

      The name of the plugin

Plugin

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

QAEDefinition interface

Properties

  • data object
    Show data properties
  • 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
        • hypercubePath string
          Required

          Reference to the qHyperCubeDef.

        • propertyTree Object
          Required
      Returns
  • 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.

        • hypercubePath string
          Required

          Reference to the qHyperCubeDef.

        • dataDefinition Object

          Data definition of the target chart.

        • defaultPropertyValues Object

          Default values for a number of properties of the target chart.

        • initialProperties Object

          Initial properties of the target chart.
      Returns
      • Object
        Required

        A properties tree
  • properties QAEProperties  |  qix.GenericObjectProperties

QAEProperties interface

Properties

  • initial qix.GenericObjectProperties
  • onChange onPropertyChange
    Show onChange properties
    • onPropertyChange() function
      Required
      Parameters
      • properties qix.GenericObjectProperties
        Required

QInfo interface

Properties

  • qId string
    Required

    Generic object id

Rect interface

Properties

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

Ref interface

Reference object returned from useRef

Properties

  • current R
    Required

    Current value

RenderConfig interface

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

Properties

  • element HTMLElement
    Required

    Target html element to render in to

  • extendProperties boolean

    For creating objects: Whether to deeply extend properties or not. If false then subtrees will be overwritten.

    default = false

  • fields Array< Field >

    For creating objects: Data fields to use

  • id string

    For existing objects: Engine identifier of object to render

  • options object

    Options passed into the visualisation

  • plugins Array< Plugin >

    plugins passed into the visualisation

  • properties qix.GenericObjectProperties

    For creating objects: Explicit properties to set

  • signal AbortSignal

    Optional AbortSignal to cancel the render operation. When aborted, destroy() is called for cleanup before onError() is called with the AbortError.

  • type string

    For creating objects: Type of visualisation to render

  • version string

    For creating objects: Version of visualization to render

RenderConfig

node
// 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 renderConfig = {
  id: 'jG5LP',
  element: document.querySelector('.line'),
};
nebbie.render(renderConfig);
// Using AbortSignal to cancel rendering:
const controller = new AbortController();
const abortConfig = {
  type: 'bar',
  element: document.querySelector('.bar'),
  fields: ['Country', '=Sum(Sales)'],
  signal: controller.signal,
  onError: (err) => {
    if (err.name === 'AbortError') {
      console.log('Render was cancelled');
    } else {
      console.error('Render failed:', err);
    }
  }
};
const vizPromise = nebbie.render(abortConfig);
// Cancel the render operation
controller.abort();

RenderConfig onError(undefined) function

Callback function called if an error occurs. Also called with AbortError when signal aborts.

Parameters

  • RenderError
    Required
    Show properties
    • originalError Error
      Required

RenderConfig onRender() function

Callback function called after rendering successfully

new RenderError(message, originalError) class

extends Error

Properties

  • originalError Error
    Required

RenderState interface

Properties

  • pending any
    Required
  • restore any
    Required

SearchMode boolean  |  'toggle'

SetStateFn interface

Parameters

  • newState S  |  function
    Required

    The new state

new Sheet() class

Experimental
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
    • 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.

    • 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

Sheet

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

Sheet destroy() function

Destroys the sheet and removes it from the the DOM.

destroy

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

SheetElement interface

Experimental
Available since: 3.1.0
extends HTMLElement

Properties

  • className 'njs-sheet'
    Required

new Theme() class

Theme getColorPickerColor(c) function

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

Parameters

  • c object
    Required
    Show c properties
    • color string
    • index number

Returns

  • string
    Required

    The resolved color.

getColorPickerColor

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

Theme getContrastingColorTo(color) function

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

node
theme.getContrastingColorTo('#400');

Theme getDataColorPalettes() function

Returns

Theme getDataColorPickerPalettes() function

Returns

Theme getDataColorScales() function

Returns

Theme getDataColorSpecials() function

Returns

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

Theme getStyle(basePath, path, attribute) function

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

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

Theme name() function

Returns theme name

Returns

  • string
    Required

    Current theme.

name

node
theme.name();

ThemeInfo interface

Properties

  • id string
    Required

    Theme identifier

ThemeInfo load() function

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

Returns

type ThemeJSON any

ToolbarMode 'attach'  |  'detach'  |  'auto'

new Translator() class

Translator add(item) function

Registers a string in multiple locales

Parameters

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

add

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

Translator get(str, args?) function

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.

Translator language(lang?) function

Returns current locale.

Parameters

  • lang string

    language Locale to updated the currentLocale value

Returns

  • string
    Required

    current locale.

TypeInfo interface

Properties

  • load LoadType
    Required
    Show load properties
    • LoadType interface
      Required
      Parameters
      • type object
        Required
        Show type properties
        • name string
          Required
        • version string
          Required
      Returns
  • name string
    Required
  • meta object
  • version string

Visualization interface

The entry point for defining a visualization.

Parameters

  • galaxy Galaxy
    Required
    Show galaxy properties
    • anything object
      Required
    • deviceType string
      Required
    • 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.
    • hostConfig object
      Required
    • theme Theme
      Required
      Show theme properties
      • getColorPickerColor() function
        Required

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

        Parameters
        • c object
          Required
          Show c properties
          • color string
          • index number
        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.
      • getDataColorPalettes() function
        Required
        Returns
      • getDataColorPickerPalettes() function
        Required
        Returns
      • getDataColorScales() function
        Required
        Returns
      • getDataColorSpecials() function
        Required
        Returns
        • DataColorSpecials
          Required
          Show properties
          • nil string
            Required
          • others string
            Required
          • primary string
            Required
      • 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

      • name() function
        Required

        Returns theme name

        Returns
        • string
          Required

          Current theme.
    • translator Translator
      Required
      Show translator properties
      • 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.

      • language() function
        Required

        Returns current locale.

        Parameters
        • lang string

          language Locale to updated the currentLocale value

        Returns
        • string
          Required

          current locale.

Returns

  • VisualizationDefinition
    Required
    Show properties
    • component() function
      Required
      Returns
      • void
        Required
    • qae QAEDefinition
      Required
      Show qae properties
      • data object
        Show data properties
      • 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
            • hypercubePath string
              Required

              Reference to the qHyperCubeDef.

            • propertyTree Object
              Required
          Returns
      • 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.

            • hypercubePath string
              Required

              Reference to the qHyperCubeDef.

            • dataDefinition Object

              Data definition of the target chart.

            • defaultPropertyValues Object

              Default values for a number of properties of the target chart.

            • initialProperties Object

              Initial properties of the target chart.
          Returns
          • Object
            Required

            A properties tree
      • properties QAEProperties  |  qix.GenericObjectProperties

Visualization

node
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}!!!`;
    }
  };
}

VisualizationDefinition interface

Properties

  • qae QAEDefinition
    Required
    Show qae properties
    • data object
      Show data properties
    • 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
          • hypercubePath string
            Required

            Reference to the qHyperCubeDef.

          • propertyTree Object
            Required
        Returns
    • 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.

          • hypercubePath string
            Required

            Reference to the qHyperCubeDef.

          • dataDefinition Object

            Data definition of the target chart.

          • defaultPropertyValues Object

            Default values for a number of properties of the target chart.

          • initialProperties Object

            Initial properties of the target chart.
        Returns
        • Object
          Required

          A properties tree
    • properties QAEProperties  |  qix.GenericObjectProperties

VisualizationDefinition component() function

Returns

  • void
    Required

new Viz() class

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.

  • viewDataToggled boolean
    Required

    Whether or not the chart has the data view toggled on.

Viz

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

Viz addListener(eventName, listener) function

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

Viz convertTo(newType, forceUpdate?, forcePatch?) function

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

node
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();

Viz destroy() function

Destroys the visualization and removes it from the the DOM.

Returns

  • Promise < void >
    Required

destroy

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

Viz getImperativeHandle() function

Gets the specific api that a Viz exposes.

Returns

  • Promise < object >
    Required

    object that contains the internal Viz api.

Viz removeListener(eventName, listener) function

Removes a listener

Parameters

  • eventName string
    Required

    Event name to remove from

  • listener() function
    Required

    Callback function to remove

Viz toggleDataView(showDataView?) function

Experimental
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.

VizElement interface

extends HTMLElement

Properties

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

VizElementAttributes interface

extends NamedNodeMap

Properties

  • data-render-count string
    Required

ColorPickerPalette interface

Properties

  • colors Array< string >
    Required
  • key string
    Required

DataColorSpecials interface

Properties

  • nil string
    Required
  • others string
    Required
  • primary string
    Required

DataPalette interface

Properties

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

ScalePalette interface

Properties

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