jprdonnelly/nebula.js
1
0
Fork 0
mirror of https://github.com/qlik-oss/nebula.js.git synced 2025-12-19 17:58:43 -05:00
Code Issues Projects Releases Wiki Activity
Files
5cb6233f103dd1ca6444e638fa95ce4e28de5921
nebula.js/docs/api-reference.md
Tobias Åström bd39cb4b4d chore: import editorial review (#592) 
* chore: import editorial review

* chore: make spec compliant
2021-04-08 08:39:11 +02:00

24 KiB
Raw Blame History

id, title
id title
api-reference API Reference

@nebula.js/stardust

version: 0.6.0-alpha.0

Table of contents

API

function: embed(app[, instanceConfig])

Initiates a new embed instance using the specified app.

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

embed.createConfiguration(configuration)

Creates a new embed scope bound to the specified configuration.

The configuration is merged with all previous scopes.

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

function: useState(initialState)

  • initialState <S|Function> The initial state.
  • returns: <Array> The value and a function to update it.

Creates a stateful value.

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

function: useEffect(effect[, deps])

  • effect <EffectCallback> The callback.
  • deps <Array<any>> The dependencies which should trigger the callback.

Triggers a callback function when a dependent value changes.

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

function: useMemo(factory, deps)

  • factory <Function> The factory function.
  • deps <Array<any>> The dependencies.
  • returns: <T> The value returned from the factory function.

Creates a stateful value when a dependent changes.

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

function: usePromise(factory[, deps])

  • factory <Function> The factory function that calls the promise.
  • deps <Array<any>> The dependencies.
  • returns: <Array> The resolved value.

Runs a callback function when a dependent changes.

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

function: useElement()

  • returns: <HTMLElement>

Gets the HTMLElement this supernova is rendered into.

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

function: useRect()

  • returns: <Rect> The size of the element.

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

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

function: useLayout()

  • returns: <qae.GenericObjectLayout>

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

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

function: useStaleLayout()

  • returns: <qae.GenericObjectLayout>

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

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.

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

function: useAppLayout()

  • returns: <qae.NxAppLayout> The app layout

Gets the layout of the app associated with this supernova.

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

function: useModel()

  • returns: <enigma.GenericObject|undefined>

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

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

function: useApp()

  • returns: <enigma.Doc|undefined> The doc API.

Gets the doc API.

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

function: useGlobal()

  • returns: <enigma.Global|undefined> The global API.

Gets the global API.

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

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

function: useSelections()

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

function: useTheme()

  • returns: <Theme> The theme.

Gets the theme.

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

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

function: useTranslator()

Gets the translator.

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

function: useAction(factory[, deps])

Registers a custom action.

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

function: useConstraints()

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

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

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

function: useOptions()

Gets the options object provided when rendering the supernova.

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

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

// when embedding the supernova, 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]);

function: onTakeSnapshot(snapshotCallback)

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

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

interface: Context

interface: Configuration

undefined: Galaxy.translator

undefined: Galaxy.flags

undefined: Galaxy.anything

class: Embed

embed.render(cfg)

Renders a visualization into an HTMLElement.

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

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

embed.context(ctx)

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

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

// limit constraints
n.context({ constraints: { active: true } });

embed.selections()

Gets the app selections of this instance.

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

interface: ThemeInfo

  • id <string> Theme identifier
  • load <Function> A function that should return a Promise that resolve to a raw JSON theme

class: SupernovaController

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

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

supernovaController.destroy()

Destroys the supernova and removes if from the the DOM.

const ctl = ctl.destroy();

interface: Flags

  • isEnabled <Function> Checks whether the specified flag is enabled.

interface: CreateConfig

  • type <string>
  • version <string>
  • fields <Array>
  • properties <qae.GenericObjectProperties>

interface: BaseConfig

  • element <HTMLElement>
  • options <Object>

interface: GetConfig

type Field = <string|qae.NxDimension|qae.NxMeasure|LibraryField>

interface: LibraryField

  • qLibraryId <string>
  • type <'dimension'|'measure'>

class: AppSelections

appSelections.mount(element)

  • element <HTMLElement>

Mounts the app selection UI into the provided HTMLElement

selections.mount(element);

appSelections.unmount()

Unmounts the app selection UI from the DOM

selections.unmount();

class: ObjectSelections

objectSelections.begin(paths)

objectSelections.clear()

objectSelections.confirm()

objectSelections.cancel()

objectSelections.select(s)

objectSelections.canClear()

objectSelections.canConfirm()

objectSelections.canCancel()

objectSelections.isActive()

objectSelections.isModal()

objectSelections.goModal(paths)

objectSelections.noModal([accept])

objectSelections.abortModal()

interface: LoadType(type)

interface: TypeInfo

interface: Supernova(galaxy)

The entry point for defining a supernova.

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

interface: SupernovaDefinition

interface: SetStateFn(newState)

type EffectCallback = <Function>

interface: Rect

interface: ActionDefinition

interface: Constraints

interface: QAEDefinition

interface: DataTarget

interface: FieldTarget

class: Translator

translator.add(item)

Registers a string in multiple locales

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

  • str <string> Id of the registered string
  • args <Array<string>> Values passed down for string interpolation
  • returns: <string> The translated string

Translates a string for current locale

class: Theme

theme.getDataColorScales()

theme.getDataColorPalettes()

theme.getDataColorPickerPalettes()

theme.getDataColorSpecials()

theme.getColorPickerColor(c)

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

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

theme.getContrastingColorTo(color)

  • color <string> A color to measure the contrast against
  • returns: <string> - The color that has the best contrast against the specified color.

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.

theme.getContrastingColorTo('#400');

theme.getStyle(basePath, path, attribute)

  • 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

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.

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

interface: ScalePalette

interface: DataPalette

interface: ColorPickerPalette

interface: DataColorSpecials

Reference in New Issue View Git Blame Copy Permalink