mirror of
https://github.com/qlik-oss/nebula.js.git
synced 2025-12-19 09:48:18 -05:00
docs: simplify web integration docs (#373)
This commit is contained in:
Miralem Drek
BIN
data/apps/the_movies.qvf
Normal file
BIN
data/apps/the_movies.qvf
Normal file
Binary file not shown.
@@ -18,7 +18,7 @@ You can then `mount` the selections UI into that element:
|
||||
```js
|
||||
const n = nucleus(enigmaApp);
|
||||
|
||||
await (n.selections()).mount(document.querySelector('.curr-selections');
|
||||
(await n.selections()).mount(document.querySelector('.curr-selections'));
|
||||
```
|
||||
|
||||
Without any selections it should like this:
|
||||
@@ -34,13 +34,11 @@ As you start applying selections in the various charts, the UI will update to re
|
||||
If you are connected to multiple apps, you can show the current selections in each one by mounting the bar into different elements:
|
||||
|
||||
```js
|
||||
await nucleus(enigmaApp)
|
||||
.selections()
|
||||
.mount(document.querySelector('.curr-selections'));
|
||||
(await nucleus(enigmaApp).selections()).mount(document.querySelector('.curr-selections'));
|
||||
|
||||
await nucleus(anotherApp, { context: { theme: 'dark' } })
|
||||
.selections()
|
||||
.mount(document.querySelector('.another-curr-selections'));
|
||||
(await nucleus(anotherApp, { context: { theme: 'dark' } }).selections()).mount(
|
||||
document.querySelector('.another-curr-selections')
|
||||
);
|
||||
```
|
||||
|
||||
|
||||
|
||||
BIN
docs/assets/mashup-sample.png
Normal file
BIN
docs/assets/mashup-sample.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 210 KiB |
@@ -3,66 +3,111 @@ id: web-integration
|
||||
title: Web integration
|
||||
---
|
||||
|
||||
Integrating `nebula.js` with your project requires the following steps:
|
||||
This guide will walk you through creating a simple mashup that connects to Qlik Sense and visualizes some data.
|
||||
|
||||
1. Connect to a Qlik Sense deployment
|
||||
1. Load `nebula.js` core modules
|
||||
1. Load chart modules
|
||||
1. Configure nucleus
|
||||
1. Render charts
|
||||
It will include the following steps:
|
||||
|
||||
## Connect to Qlik
|
||||
1. Setup a Qlik Cloud Services account
|
||||
1. Create a simple web project
|
||||
1. Configure connection
|
||||
1. Visualize data
|
||||
|
||||
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).
|
||||
and requires that you have:
|
||||
|
||||
The connection needs to be created using `enigma.js` which you should load first:
|
||||
- `node.js` `v10.0.0+` installed on your machine
|
||||
- A decent IDE, we recommend [VSCode](https://code.visualstudio.com/).
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/enigma.js" crossorigin></script>
|
||||
## Setup up a Qlik Cloud Services account
|
||||
|
||||
Though `nebula.js` works and can be integrated with all Qlik Sense products, this will guide you on how to integrate with Qlik Cloud Services.
|
||||
|
||||
Perform the following steps:
|
||||
|
||||
1. [Register for a subscription on Qlik Cloud Services](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Introduction/qcs-register.htm).
|
||||
1. [Configure your deployment](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Introduction/qcs-tenant-domain.htm).
|
||||
1. [Create a new web integration](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/mc-adminster-web-integrations.htm) from the [Management console](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/management-console.htm).
|
||||
1. You will later on run the mashup from your local machine, to allow this connection to happen you should add `http://localhost:1234` to the whitelist of origins.
|
||||
1. Once the web integration has been created an ID will be assigned to it, this is the `qlik-web-integration-id` you will need later on.
|
||||
1. [Upload an app](https://help.qlik.com/en-US/cloud-services/Subsystems/Hub/Content/Sense_Hub/Apps/create-app-cloud-hub.htm)
|
||||
1. If you don't have an app or data already prepared, you can [download the movies dataset](https://github.com/qlik-oss/nebula.js/raw/master/data/apps/the_movies.qvf) from the github repository and upload it to the cloud.
|
||||
|
||||
Each app in QCS has a global unique identifier (GUID) which you will need later on.
|
||||
The GUID can be extracted from the URL and is the part that follows `/app`. For example, if the URL is `https://qcs.us.qlikcloud.com/sense/app/7fc4d85c-0e07-4160-90a9-c2ca4a45fd81`, then the GUID of the app is `7fc4d85c-0e07-4160-90a9-c2ca4a45fd81`.
|
||||
|
||||
## Create a simple web project
|
||||
|
||||
The quickest way to create a web project is to use the `nebula.js` command line interface:
|
||||
|
||||
```bash
|
||||
npx @nebula.js/cli create mashup hello-qcs
|
||||
```
|
||||
|
||||
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:
|
||||
The command will scaffold a web project into the `hello-qcs` folder with the following structure:
|
||||
|
||||
- `/src`
|
||||
- `configure.js` - Initial configuration of `nebula.js`
|
||||
- `connect.js` - Connection setup with `enigma.js`
|
||||
- `index.html` - A minimal html page
|
||||
- `index.js` - Connect and visualize
|
||||
|
||||
`/src/index.js` is where you will need to make modifications later on to bring everything together.
|
||||
|
||||
## Configure connection
|
||||
|
||||
To configure the connection you will need your QCS tenant url, the `qlik-web-integration-id` and the GUID of the app you want to open.
|
||||
|
||||
Open up `src/index.js` and update the `<>` placeholders with the correct values, for example:
|
||||
|
||||
```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 app = await connect({
|
||||
url: 'https://qcs.us.qlikcloud.com',
|
||||
webIntegrationId: '8Ys9sBVyq6i2lxtclPWaaZhQr7OgwKaT',
|
||||
appId: '7fc4d85c-0e07-4160-90a9-c2ca4a45fd81',
|
||||
});
|
||||
```
|
||||
|
||||
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:
|
||||
## Visualize data
|
||||
|
||||
The movies dataset you uploaded earlier has a bar chart on the first sheet with the id `EAjjuyE`, you can render that same bar chart in your mashup by providing the id and an element to render the visualization into:
|
||||
|
||||
```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://<tenant>.us.qlikcloud.com/app/<GUID>?qlik-web-integration-id=<qlik-web-integration-id>',
|
||||
})
|
||||
.open();
|
||||
|
||||
const enigmaApp = await enigmaGlobal.openDoc('<GUID>');
|
||||
}
|
||||
n.render({
|
||||
element: document.querySelector('.object'),
|
||||
id: 'EAjjuyE',
|
||||
});
|
||||
```
|
||||
|
||||
Read more:
|
||||
Start the web development server by executing the following in a terminal:
|
||||
|
||||
- [Connecting to various Qlik Sense deployments](#)
|
||||
- [enigma.js](#)
|
||||
|
||||
## Load nebula core modules
|
||||
|
||||
Load the two core `nebula.js` modules:
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/@nebula.js/supernova" crossorigin></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/@nebula.js/nucleus" crossorigin></script>
|
||||
```
|
||||
npm run start
|
||||
```
|
||||
|
||||
## Load visualization modules
|
||||
The server will run on [http://localhost:1234](http://localhost:1234).
|
||||
|
||||
The core modules do not contain any visualizations by themselves, each visualization is its own separate module and needs to be loaded and registered before it can be used.
|
||||
When opening the page, you may be re-routed to your QCS tenant to login if the session timed out since you did the setup. Once logged in, you will be re-routed back to the develoment server where you should see the same bar chart:
|
||||
|
||||
|
||||
|
||||
The visualization is fully interactive, any selections you make will be reflected in the current app selections toolbar at the top.
|
||||
|
||||
## More visualizations
|
||||
|
||||
### Render on the fly
|
||||
|
||||
You can render a visualization without having to create it in the app by providing the `type` and some data `fields`:
|
||||
|
||||
```js
|
||||
n.render({
|
||||
element: document.querySelector('.object'),
|
||||
type: 'barchart',
|
||||
fields: ['title', '=avg(rating')],
|
||||
});
|
||||
```
|
||||
|
||||
### More types
|
||||
|
||||
The core modules of `nebula.js`do not contain any visualizations by themselves, each visualization is its own separate module and needs to be loaded and registered before it can be used.
|
||||
|
||||
Official supernova modules from Qlik are published under the `@nebula.js` scope and are prefixed with `sn-`.
|
||||
|
||||
@@ -75,44 +120,26 @@ The available visualizations are as follows:
|
||||
- Funnel chart: `@nebula.js/sn-funnel-chart`
|
||||
- Mekko chart: `@nebula.js/sn-mekko-chart`
|
||||
|
||||
You can load a visualization through a `<script>` tag:
|
||||
The template you created your mashup from only includes the `bar-chart` module, you can add more types by installing each one you want to use:
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/@nebula.js/sn-bar-chart" crossorigin></script>
|
||||
```bash
|
||||
npm install @nebula.js/sn-pie-chart
|
||||
```
|
||||
|
||||
which makes it available to you on the global `window` object as `@nebula.js/sn-bar-chart`.
|
||||
|
||||
## Render visualizations
|
||||
|
||||
Before rendering the visualization you need to configure `nucleus` with the supernova types you want to support:
|
||||
Then modify `/src/configure.js` to include the new modules:
|
||||
|
||||
```js
|
||||
const n = nucleus.createConfiguration({
|
||||
import piechart from '@nebula.js/sn-pie-chart';
|
||||
//...
|
||||
|
||||
nucles.createConfiguration({
|
||||
// ...
|
||||
types: [
|
||||
// ...
|
||||
{
|
||||
type: 'barchart',
|
||||
load: () => Promise.resolve(window['@nebula.js/sn-bar-chart']),
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
You can then render a visualization 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: '<ObjectID>',
|
||||
});
|
||||
name: 'piechart',
|
||||
load: () = Promise.resolve(piechart)
|
||||
}
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"docs": {
|
||||
"Getting started": ["introduction", "installation", "web-integration"],
|
||||
"Nucleus guide": ["nucleus-configuration", "render-charts", "sn-controller", "app-selections", "nucleus-reference"]
|
||||
"Nucleus guide": ["nucleus-configuration", "render-charts", "app-selections", "nucleus-reference"]
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user