From 7ac87a9ea62e886ca6f0b3b4127a3dacb9ecb586 Mon Sep 17 00:00:00 2001 From: Miralem Drek Date: Wed, 11 Mar 2020 12:46:51 +0100 Subject: [PATCH] docs: initial instructions (#348) --- docs/README.md | 3 +- docs/app-selections.md | 6 ++ docs/installation.md | 67 +++++++++++++++++++ docs/nucleus-configuration.md | 6 ++ docs/render-charts.md | 6 ++ docs/sn-controller.md | 6 ++ docs/web-integration.md | 117 ++++++++++++++++++++++++++++++++++ website/core/Footer.js | 2 +- website/i18n/en.json | 41 ++++++++++++ website/sidebars.json | 3 +- website/siteConfig.js | 21 +----- website/static/css/custom.css | 17 +++++ 12 files changed, 273 insertions(+), 22 deletions(-) create mode 100644 docs/app-selections.md create mode 100644 docs/installation.md create mode 100644 docs/nucleus-configuration.md create mode 100644 docs/render-charts.md create mode 100644 docs/sn-controller.md create mode 100644 docs/web-integration.md create mode 100644 website/i18n/en.json diff --git a/docs/README.md b/docs/README.md index ab6e8362c..e7375845a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,8 +7,9 @@ title: Introduction `nebula.js` is a collection of JavaScript libraries and APIs that helps developers integrate visualizations and mashups on top of Qlik's Associative Engine. -It consists of three parts: +It consists of : - `nucleus`: A product and framework agnostic JavaScript library for building mashups. - `supernova`: A JavaScript API for consuming and visualizing QIX data. +- `snapshooter`: A JavaScript API for rendering a `supernova` in offline mode. - `cli`: Tools to help you create, develop and build a `supernova`. diff --git a/docs/app-selections.md b/docs/app-selections.md new file mode 100644 index 000000000..2e387a72f --- /dev/null +++ b/docs/app-selections.md @@ -0,0 +1,6 @@ +--- +id: app-selections +title: App selections +--- + +TODO diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000..7d22d4695 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,67 @@ +--- +id: installation +title: Installation +--- + +All `nebula.js` modules are available on the public npm registry as npm packages and can be installed through either npm or as a script import. + +`@nebula.js/supernova` and `@nebula.js/nucleus` are the two core modules that you will be using and are required when integrating `nebula.js` on the web. + +## Script import + +The easiest way to load the modules is from a CDN like `jsdelivr`: + +```html + + +``` + +Both are UMD packages and will add the variables `supernova` and `nucleus` to the global namespace. + +For production, it is recommended to use a specific version of each module to avoid surprises from newer or breaking versions of the APIs: + +```html + + +``` + +## Npm or yarn + +If you are building your own web project using Webpack, Rollup, Parcel or similar you can install the packages with npm: + +```bash +$ npm install @nebula.js/supernova @nebula.js/nucleus +``` + +or yarn: + +```bash +$ yarn add @nebula.js/supernova @nebula.js/nucleus +``` + +and then import `nucleus` wherever you're using it: + +```js +import nucleus from '@nebula.js/nucleus'; +``` + +You should not need to import `@nebula.js/supernova` yourself, it is a dependency to most charts and will be resolved automatically by the bundling tool when needed. + +## CLI + +`nebula.js` provides a CLI for quickly getting started with a supernova project and provides a development server to help you during the +development phase. + +```bash +$ npm install @nebula.js/cli +``` + +## Development builds + +Some modules are available as a development build which provide more errors and warnings when detecting potentially bad usage of the APIs. +You should only use these during the development phase of your project, never in production. + +```html + + +``` diff --git a/docs/nucleus-configuration.md b/docs/nucleus-configuration.md new file mode 100644 index 000000000..1a1be1531 --- /dev/null +++ b/docs/nucleus-configuration.md @@ -0,0 +1,6 @@ +--- +id: nucleus-configuration +title: Configuration +--- + +TODO diff --git a/docs/render-charts.md b/docs/render-charts.md new file mode 100644 index 000000000..0088ccb5d --- /dev/null +++ b/docs/render-charts.md @@ -0,0 +1,6 @@ +--- +id: render-charts +title: Render charts +--- + +TODO diff --git a/docs/sn-controller.md b/docs/sn-controller.md new file mode 100644 index 000000000..e79c954e0 --- /dev/null +++ b/docs/sn-controller.md @@ -0,0 +1,6 @@ +--- +id: sn-controller +title: Modify charts +--- + +TODO diff --git a/docs/web-integration.md b/docs/web-integration.md new file mode 100644 index 000000000..a56272e7b --- /dev/null +++ b/docs/web-integration.md @@ -0,0 +1,117 @@ +--- +id: web-integration +title: Web integration +--- + +Integrating `nebula.js` with your project requires the following steps: + +1. Connect to a Qlik Sense deployment +1. Load `nebula.js` core modules +1. Load chart modules +1. Configure nucleus +1. Render charts + +## Connect to Qlik + +The majority of communication between the web and a Qlik Sense deployment happens with a WebSocket connection, how you authenticate and create such a connection depends on the type of deployment you want to connect to. The examples will assume you are connecting to your own Qlik Cloud Services tenant and have already [configured it to allow web integrations](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/mc-adminster-web-integrations.htm). + +The connection needs to be created using `enigma.js` which you should load first: + +```html + +``` + +Before creating the connection, you need to fetch a `schema` which helps `enigma.js` understand how and what methods you can use to communicate with Qlik: + +```js +async function connect() { + const schema = await (await fetch('https://cdn.jsdelivr.net/npm/enigma.js@2.6.3/schemas/12.170.2.json')).json(); +} +``` + +To create the connection you need to know your QCS tenant url, the `qlik-web-integration-id` and the GUID of the document you want to open: + +```js +async function connect() { + const schema = await (await fetch('https://cdn.jsdelivr.net/npm/enigma.js@2.6.3/schemas/12.170.2.json')).json(); + + const enigmaGlobal = await enigma + .create({ + schema, + url: 'wss://.us.qlikcloud.com/app/?qlik-web-integration-id=', + }) + .open(); + + const enigmaApp = await enigmaGlobal.openDoc(''); +} +``` + +Read more: + +- [Connecting to various Qlik Sense deployments](#) +- [enigma.js](#) + +## Load nebula core modules + +Load the two core `nebula.js` modules: + +```html + + +``` + +## Load chart modules + +The core modules do not contain any charts by themselves, each chart is its own separate module and needs to be loaded and registered before it can be used. + +Official supernova chart modules from Qlik are published under the `@nebula.js` scope and are prefixed with `sn-`. +The available charts are as follows: + +- Bar chart: `@nebula.js/sn-bar-chart` +- Line chart: `@nebula.js/sn-line-chart` +- Pie chart: `@nebula.js/sn-pie-chart` +- Sankey chart: `@nebula.js/sn-sankey-chart` +- Funnel chart: `@nebula.js/sn-funnel-chart` +- Mekko chart: `@nebula.js/sn-mekko-chart` + +You can load a chart through a ` +``` + +which makes it available to you on the global `window` object as `@nebula.js/sn-bar-chart`. + +## Render charts + +Before rendering the chart you need to configure `nucleus` with the supernova types you want to support: + +```js +const n = nucleus.createConfiguration({ + types: [ + { + type: 'barchart', + load: () => Promise.resolve(window['@nebula.js/sn-bar-chart']), + }, + ], +}); +``` + +You can then render a chart on the fly in an `HTMLElement` that has a fixed size and provide the initial `fields` to it: + +```js +n(enigmaApp).render({ + element: document.querySelector('#chart'), + type: 'barchart', + fields: ['Product', '=sum(Sales)'], +}); +``` + +If the `GenericObject` already exists in the app you opened, you can render it by providing its `id`: + +```js +n(enigmaApp).render({ + element: document.querySelector('#chart'), + id: '', +}); +``` diff --git a/website/core/Footer.js b/website/core/Footer.js index 0e1b5e6ba..b9fd23248 100644 --- a/website/core/Footer.js +++ b/website/core/Footer.js @@ -23,7 +23,7 @@ function Footer({ config, language }) {
Links
diff --git a/website/i18n/en.json b/website/i18n/en.json new file mode 100644 index 000000000..747ed390f --- /dev/null +++ b/website/i18n/en.json @@ -0,0 +1,41 @@ +{ + "_comment": "This file is auto-generated by write-translations.js", + "localized-strings": { + "next": "Next", + "previous": "Previous", + "tagline": "A new star on the rise", + "docs": { + "app-selections": { + "title": "App selections" + }, + "installation": { + "title": "Installation" + }, + "nucleus-configuration": { + "title": "Configuration" + }, + "introduction": { + "title": "Introduction" + }, + "render-charts": { + "title": "Render charts" + }, + "sn-controller": { + "title": "Modify charts" + }, + "web-integration": { + "title": "Web integration" + } + }, + "links": {}, + "categories": { + "Getting started": "Getting started", + "Nucleus guide": "Nucleus guide" + } + }, + "pages-strings": { + "Help Translate|recruit community translators for your project": "Help Translate", + "Edit this Doc|recruitment message asking to edit the doc source": "Edit", + "Translate this Doc|recruitment message asking to translate the docs": "Translate" + } +} diff --git a/website/sidebars.json b/website/sidebars.json index 075d01a81..89830139f 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,5 +1,6 @@ { "docs": { - "Introduction": ["introduction"] + "Getting started": ["introduction", "installation", "web-integration"], + "Nucleus guide": ["nucleus-configuration", "render-charts", "sn-controller", "app-selections"] } } diff --git a/website/siteConfig.js b/website/siteConfig.js index 35cedb0f3..55df70f06 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -25,30 +25,13 @@ const siteConfig = { secondaryColor: '#0f0', }, - /* Custom fonts for website */ - /* - fonts: { - myFont: [ - "Times New Roman", - "Serif" - ], - myOtherFont: [ - "-apple-system", - "system-ui" - ] - }, - */ - // This copyright info is used in /core/Footer.js and blog RSS/Atom feeds. copyright: `Copyright © ${new Date().getFullYear()} QlikTech International AB`, highlight: { - // Highlight.js theme to use for syntax highlighting in code blocks. - theme: 'default', + theme: 'atom-one-light', }, - - // Add custom scripts here that would be placed in