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
77bd9522deaebca357b99ff3eebf28be60282c39
nebula.js/docs/supernova-api.md
Miralem Drek 77bd9522de docs(supernova): update jsdoc (#367)
2020-03-20 14:17:46 +01:00

19 KiB
Raw Blame History

@nebula.js/supernova

version: 0.2.0

Table of contents

API

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/supernova';
// ...
// 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 dependant value changes.

import { useEffect } from '@nebula.js/supernova';
// ...
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 dependant changes.

import { useMemo } from '@nebula.js/supernova';
// ...
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 dependant changes.

import { usePromise } from '@nebula.js/supernova';
import { useModel } from '@nebula.js/supernova';
// ...
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/supernova';
// ...
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/supernova';
// ...
const rect = useRect();
useEffect(() => {
  console.log('resize');
}, [rect.width, rect.height]);

function: useLayout()

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

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

function: useStaleLayout()

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/supernova';
// ...
const staleLayout = useStaleLayout();
console.log(staleLayout);

function: useAppLayout()

Gets the layout of the app associated with this supernova.

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

function: useModel()

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

import { useModel } from '@nebula.js/supernova';
// ...
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/supernova';
// ...
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/supernova';

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

function: useSelections()

Gets the object selections.

import { useSelections } from '@nebula.js/supernova';
import { useElement } from '@nebula.js/supernova';
import { useEffect } from '@nebula.js/supernova';
// ...
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/supernova';

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

function: useTranslator()

Gets the translator.

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

function: useAction(factory[, deps])

Registers a custom action.

import { useAction } from '@nebula.js/supernova';
// ...
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 nucleus to disallow active interactions when rendering
nucleus(app, {
  constraints: {
    active: true, // do not allow interactions
  },
}).render({ element, id: 'sdfsdf' });

import { useConstraints } from '@nebula.js/supernova';
// ...
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 rendering the supernova with nucleus, anything can be set in options
nucleus(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/supernova';
import { useEffect } from '@nebula.js/supernova';
// ...
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/supernova';
import { useState } from '@nebula.js/supernova';
import { useLayout } from '@nebula.js/supernova';

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

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

interface: Supernova([env])

The entry point for defining a supernova.

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

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

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