@nebula.js/stardust

v1.0.0

Product and framework agnostic integration API for Qlik's Associative Engine

Initiates a new Embed instance using the specified enigma app.

Parameters

app
enigma.Doc

No description

instanceConfig

No description

Returns

No description

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

Creates a new embed scope bound to the specified configuration.

The configuration is merged with all previous scopes.

Parameters

configuration

The configuration object

Returns

No description

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({
 theme: 'dark'
});

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

Creates a stateful value.

Parameters

initialState
S | function

The initial state.

Returns

Array<S, SetStateFn>

The value and a function to update it.

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

// update
setZoomed(true);

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

Triggers a callback function when a dependant value changes.

Parameters

effect

The callback.

deps
optional
Array<any>

The dependencies which should trigger the callback.

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

Creates a stateful value when a dependant changes.

Parameters

factory
function

The factory function.

deps
Array<any>

The dependencies.

Returns

T

The value returned from the factory function.

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

Runs a callback function when a dependant changes.

Parameters

factory
function

The factory function that calls the promise.

deps
optional
Array<any>

The dependencies.

Returns

Array<P, Error>

The resolved value.

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

useElement
()

function

Gets the HTMLElement this visualization is rendered into.

Returns

HTMLElement

No description

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

useRect
()

function

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

Returns

The size of the element.

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

useLayout
()

function

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

Returns

qae.GenericObjectLayout

No description

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

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

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

Returns

qae.GenericObjectLayout

No description

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

Gets the layout of the app associated with this visualization.

Returns

qae.NxAppLayout

The app layout

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

useModel
()

function

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

Returns

enigma.GenericObject | undefined

No description

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

useApp
()

function

Gets the doc API.

Returns

enigma.Doc | undefined

The doc API.

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

useGlobal
()

function

Gets the global API.

Returns

enigma.Global | undefined

The global API.

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

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

Gets the object selections.

Returns

The object selections.

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

useTheme
()

function

Gets the theme.

Returns

The theme.

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

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

Gets the translator.

Returns

The translator.

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

Registers a custom action.

Parameters

factory
function

No description

deps
optional
Array<any>

No description

Returns

A

No description

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

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

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

Returns

No description

// configure embed to disallow active interactions when rendering
embed(app, {
  constraints: {
    active: true, // do not allow interactions
  }
}).render({ element, id: 'sdfsdf' });
import { useConstraints } from '@nebula.js/stardust';
// ...
const constraints = useConstraints();
useEffect(() => {
  if (constraints.active) {
    // do not add any event listener if active constraint is set
    return undefined;
  }
  const listener = () => {};
  element.addEventListener('click', listener);
  return () => {
    element.removeEventListener('click', listener);
  };
}, [constraints])

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

No description

// when embedding the visualization, anything can be set in options
embed(app).render({
  element,
  type: 'my-chart',
  options: {
    showNavigation: true,
  }
});
// it is up to you use and implement the provided options
import { useOptions } from '@nebula.js/stardust';
import { useEffect } from '@nebula.js/stardust';
// ...
const options = useOptions();
useEffect(() => {
  if (!options.showNavigation) {
    // hide navigation
  } else {
    // show navigation
  }
}, [options.showNavigation]);

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

Parameters

snapshotCallback
function

No description

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

Context

interface

Properties

constraints
optional

No description

theme
optional, default='light'
string

No description

language
optional, default='en-US'
string

No description

Configuration

interface

Properties

context
optional

No description

types
optional
Array<any>

No description

themes
optional
Array<any>

No description

anything
optional
object

No description

Galaxy

interface

Properties

translator

No description

flags

No description

anything
object

No description

Renders a visualization into an HTMLElement.

Parameters

cfg

The render configuration.

Returns

Promise<Viz>

A controller to the rendered visualization.

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

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

The context to update.

Returns

Promise<undefined>

No description

// change theme
n.context({ theme: 'dark'});
// limit constraints
n.context({ constraints: { active: true } });

Gets the app selections of this instance.

Returns

Promise<AppSelections>

No description

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

ThemeInfo

interface

Properties

id
string

Theme identifier

A function that should return a Promise that resolve to a raw JSON theme

Returns

Promise<ThemeJSON>

No description

new Viz

class

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

Properties

id
string

The id of this visualization's generic object.

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

Vizdestroy
()

function

Destroys the visualization and removes if from the the DOM.

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

Flags

interface

Checks whether the specified flag is enabled.

Parameters

flag
string

The value flag to check.

Returns

boolean

True if the specified flag is enabled, false otherwise.

Mounts the app selection UI into the provided HTMLElement.

Parameters

element
HTMLElement

No description

selections.mount(element);

Unmounts the app selection UI from the DOM.

selections.unmount();

Parameters

paths
Array<any>

No description

Returns

Promise<undefined>

No description

Returns

Promise<undefined>

No description

Returns

Promise<undefined>

No description

Returns

Promise<undefined>

No description

Parameters

s

No description

Returns

Promise<boolean>

No description

Returns

boolean

No description

Returns

boolean

No description

Returns

boolean

No description

Returns

boolean

No description

Returns

boolean

No description

Parameters

paths
Array<any>

No description

Returns

Promise<undefined>

No description

Parameters

accept
optional, default=false
boolean

No description

Returns

Promise<undefined>

No description

CreateConfig

interface
extendsBaseConfig

Properties

type
string

No description

version
string

No description

fields
optional
Array<any>

No description

properties
optional
qae.GenericObjectProperties

No description

BaseConfig

interface

Properties

element
HTMLElement

No description

options
optional
object

No description

GetConfig

interface
extendsBaseConfig

Properties

id
string

No description

type Field

string | qae.NxDimension | qae.NxMeasure | LibraryField

LibraryField

interface

Properties

qLibraryId
string

No description

type
'dimension' | 'measure'

No description

Parameters

type

No description

Returns

Promise<Visualization>

No description

TypeInfo

interface

Properties

name
string

No description

version
string

No description

load

No description

meta
optional
object

No description

CellElement

interface
extendsHTMLElement

Properties

className
'njs-cell'

No description

VizElement

interface
extendsHTMLElement

Properties

attributes

No description

className
'njs-viz'

No description

The entry point for defining a visualization.

Parameters

galaxy

No description

Returns

No description

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

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

Properties

qae

No description

Returns

void

No description

Parameters

newState
S | function

The new state

Returns

void | function

No description

Rect

interface

Properties

top
number

No description

left
number

No description

width
number

No description

height
number

No description

Properties

action
A

No description

hidden
optional
boolean

No description

disabled
optional
boolean

No description

icon
optional

No description

Constraints

interface

Properties

passive
optional
boolean

No description

active
optional
boolean

No description

select
optional
boolean

No description

QAEDefinition

interface

Properties

properties
optional
qae.GenericObjectProperties

No description

data
optional

No description

DataTarget

interface

Properties

path
string

No description

dimensions
optional

No description

measures
optional

No description

FieldTarget

interface

Returns

number

No description

Returns

number

No description

Parameters

T

No description

qae.GenericObjectProperties

No description

Parameters

T

No description

qae.GenericObjectProperties

No description

number

No description

Registers a string in multiple locales

Parameters

item

No description

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

Translates a string for current locale

Parameters

str
string

Id of the registered string

args
optional
Array<any>

Values passed down for string interpolation

Returns

string

The translated string

Returns

Array<any>

No description

Returns

Array<any>

No description

Returns

Array<any>

No description

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

Parameters

c

No description

Returns

string

The resolved color.

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

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

The returned colors are derived from the theme.

Parameters

color
string

A color to measure the contrast against

Returns

string
  • The color that has the best contrast against the specified color.
theme.getContrastingColorTo('#400');

Get the value of a style attribute in the theme by searching in the theme's json structure.
The search starts at the specified base path and continue upwards until the value is found.
If possible it will get the attribute's value using the given path.

Parameters

basePath
string

Base path in the theme's json structure to start the search in (specified as a name path separated by dots)

path
string

Expected path for the attribute (specified as a name path separated by dots)

attribute
string

Name of the style attribute

Returns

string

The style value

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

Properties

key
string

No description

type
'gradient' | 'class'

No description

colors
Array<any>

No description

Properties

key
string

No description

type
'pyramid' | 'row'

No description

colors
Array<any> | Array<any>

No description

Properties

key
string

No description

colors
Array<any>

No description

Properties

primary
string

No description

nil
string

No description

others
string

No description