@reaqtive/q

v0.0.0-beta.18

Published

3 years ago

A react library to connect React to the QIX engine and to Qlik Capability APIs

Downloads

0High
0Medium
0Low

xuuajii

qlik react mashup mash up analytics data visualization QIX sense

@reaqtive/q

This package provides a set of hooks, contexts and components to interact with the Qlik Engine APIs and the Qlik Capability APIs. Its purpose is to simplify the interaction with the engine and provide a set of tested APIs to easily retrieve data and interfaces from the engine. @reaqtive/q does not provide any layout components, it only allows you to interact with the Qlik engine. You can use it as a stand alone package and develop your layout components using its APIs, as described below. Depending on your needs and you can install @reaqtive/components instead. It provides a set of ready to use layout components to build data visualization apps on top o Qlik APIs, and depends on @reaqtive/q.

Installation

npm install @reaqtive/q

PROVIDED FEATURES

REAQTIVE

Reaqtive

Reaqtive is the main component of the library. It provides Reaqtive contexts to its child or children. Contexts allows you to interact with Qlik APIs. To have access to Qlik APIs you have to wrap your main component in a <Reaqtive> tag. Reaqtive allows to connect the same React app to multiple Qlik apps. If you use only the Engine APIs you just have render multiple <Reaqtive> components in your app remembering to set to false the qCapabilityApiRequired prop. Instead, if you want to use also the capability APIs you have to use the QShareCapabilityApi component to avoid to download AngularJS twice. You can find an example here Provided contexts are:

Example:

import React from 'react'
import Reaqtive from '@reaqtive/q'
import {MyComponentWithQGlobal, MyComponentWithQDoc, MyComponentWithQCapabilityApi, MyComponentWithQApp, MyQGenericObject, MyQVariable} from './index'
import {MyRqtvNavbar, MyRqtvListbox, MyRqtvDropdownFilter, MyRqtvButtonBar, MyRqtvModalListbox, MyRqtvSearchField, MyRqtvMultibox, MyQVizExamples, MyRqtvContainerExample,MyRqtvCurrentSelections, MyRqtvSearchObject} from '../components/index'

const MyReaqtiveComponent = props => {
  // This qConfig allows to connect to on Qlik Sense Desktop and open the app called Executive Dashboard
  const qConfig = {                                 //For QS Desktop
      host: 'YOUR HOST ADDRESS',                        //localhost
      secure: true,                                 //false
      port: 443,                                    //4848
      prefix: '',                                   //''
      appId: 'bc1566bc-6299-4d8b-8976-d5b60225ded8'//'8aa3a035-0689-4aab-a920-d6722509ed51' //your app file name (e.g. 'Executive dashboard.qvf')
  };

  return (
    <Reaqtive qConfig={qConfig}>
      {props.children}
      {/*<div className="container">
        <Wrapper>
         <MyRqtvListbox/>
        </Wrapper>
        <Wrapper>
         <MyQVizExamples/>
        </Wrapper>
        <Wrapper>
          <div>...</div>
        </Wrapper>
      </div>*/}
    </Reaqtive>
  )
}

const Wrapper = props => <div style={{marginBottom:'2rem'}}>{props.children}</div>

export default MyReaqtiveComponent

Props:

prop | type | default | required | description ---- | :----: | :-------: | :--------: | ----------- qCapabilityApiRequired | Boolean | true | :x: | if true Reaqtive downloads capability APIs from Qlik server and provides the qlik object and the qApp to its children qConfig | Shape | | :white_check_mark: | qConfig is an object that provides reaqtive the params needed to connect to the Qlik server. params are: host, port, secure, prefix, appId: the id of the app reaqtive should connect to qConfig.appId | String | | :white_check_mark: | appId: the id of the app reaqtive should connect to qConfig.host | String | | :white_check_mark: | host: the ip address or domain of the Qlik SystemProvider qConfig.port | Number | | :white_check_mark: | port: the port on which Qlik server is listening qConfig.prefix | String | | :white_check_mark: | prefix: Qlik's virtual proxy path qConfig.secure | Boolean | | :white_check_mark: | secure: true if the Qlik server uses https, false otherwise

CONTEXTS

QGlobal

QGlobal This context provides a handler for the qGlobal provided by Qlik engine Api. The handler is an object with 3 props: qGlobal: the actual qGlobal provided by the qEngine. It is initially null and it is set when the promis is resolved qError: initially null it is set to true if the promise for the qGlobal returns an error qLoading: initially true, it is set to false when the promise to get the qGlobal is resolved https://help.qlik.com/en-US/sense-developer/February2019/APIs/EngineAPI/index.html

Example:

import React, {useContext} from 'react'
import {QGlobal} from '@reaqtive/q'

const MyComponentWithQGlobal = props => {
  const qGlobalHandler = useContext(QGlobal)
  console.log(qGlobalHandler)
  return(
    /*
      This component must be wrapped by Reaqtive to use the desired context.
      Since contexts are provided as promises you must always check if they are available or still loading using the handler properties
    */
    <div>This comoponent have access to the qGlobal class and call its methods</div>
  )
}

export default MyComponentWithQGlobal

QDoc

QDoc This context provides a handler for the qDoc provided by Qlik engine Api. The handler is an object with 3 props: qDoc: the actual qDoc provided by the qEngine. It is initially null and it is set when the promis is resolved qError: initially null it is set to true if the promise for the qDoc returns an error qLoading: initially true, it is set to false when the promise to get the qDoc is resolved https://help.qlik.com/en-US/sense-developer/February2019/APIs/EngineAPI/index.html

Example:

import React, {useContext} from 'react'
import {QDoc} from '@reaqtive/q'

const MyComponentWithQDoc = props => {
  const qDocHandler = useContext(QDoc)
  console.log(qDocHandler)
  return(
    /*
      This component must be wrapped by Reaqtive to use the desired context.
      Since contexts are provided as promises you must always check if they are available or still loading using the handler properties
    */
    <div>This comoponent have access to the qDoc class and call its methods</div>
  )
}

export default MyComponentWithQDoc

QCapabilityApi

QCapabilityApi This context provides a handler for the qlik object provided by Qlik Capability APIs. The handler is an object with 5 props: qLoadingRequireJS: initially true, it is set to false when the promise to get requireJS is resolved qLoadingQlikJS: initially true, it is set to false when the promise to get qlikJS is resolved qLoadingCss: initially true, it is set to false when the promise to get qlikCSS is resolved qlik: the qlik provided by the qlik Capability APIs. It is initially null and it is set when the promis is resolved qError: initially null it is set to true if one of the promises to load requireJS or the qlik object or the css fails

Example:

import React, {useContext} from 'react'
import {QCapabilityApi} from '@reaqtive/q'

const MyComponentWithQCapabilityApi = props => {
  const qCapabilityApiHandler = useContext(QCapabilityApi)
  console.log(qCapabilityApiHandler)
  return(
    /*
      This component must be wrapped by Reaqtive to use the desired context.
      Since contexts are provided as promises you must always check if they are available or still loading using the handler properties
    */
    <div>This comoponent have access to the  qlik class provided by the qCapabilityApi and call its methods</div>
  )
}

export default MyComponentWithQCapabilityApi

QApp

QApp This context provides a handler for the application (qApp) object provided by Qlik Capability APIs. The handler is an object with 3 props: qLoading: initially true, it is set to false when the promise to get the qApp is resolved qApp: the app provided by the qlik Capability APIs. It is initially null and it is set when the promis is resolved qError: initially null it is set to true if the promise to get the qApp returns an error

Example:

import React, {useContext} from 'react'
import {QApp} from '@reaqtive/q'

const MyComponentWithQApp = props => {
  const qAppHandler = useContext(QApp)
  console.log(qAppHandler)
  return(
    /*
      This component must be wrapped by Reaqtive to use the desired context.
      Since contexts are provided as promises you must always check if they are available or still loading using the handler properties
    */
    <div>This comoponent have access to the qApp class and call its methods</div>
  )
}

export default MyComponentWithQApp

COMPONENTS

QGenericObject

QGenericObject Creates a generic object and provides qObject and qLayout to its clid. It expects only 1 child It attaches an onChange event-listener to the qObject and automatically updates the layout when the event fires. For example it can provide a listobject or a hypercube to its children.

QGenericObject must have one and only one child. The child can be a React element (external layout mode) or a function that returns a React element (inline layout mode).

See the example below for details

Example:

import React from 'react'
import {QGenericObject} from '@reaqtive/q'

const qObjectDef = {
  "qInfo": { "qId": "", "qType": "FieldList" },
  "qFieldListDef": {
    "qShowSystem": false,
    "qShowHidden": false,
    "qShowSemantic": true,
    "qShowSrcTables": true
  }
}

const MyQGenericObject = props => {
  return (
    <div className="row">
      {/*Externallayout mode*/}
      <QGenericObject qObjectDef={qObjectDef}>
        {
         /**
          *You can define the view of your generic object in a separate component that we call Layout as a convention.
          *The Layout will received the interfaces provided by the QGenericObject as props.
          */
        }
        <Layout/>
      </QGenericObject>

      {/*Inline layout mode*/}
      <QGenericObject qObjectDef={qObjectDef}>
        {
          /**
           *You can define the view of your generic object in line using a function.
           *The function accept one argument which is an object that contains all the interfaces provided by the QGenericObject.
           *You will have access to the interfaces in the body of the function.
           */}
        {(qGenericObject)=>{
          console.log('inline layout', qGenericObject)
          return (
            <div className="col-md-6">
              <div>My Generic Object - Inline layout mode</div>
              <div style={{maxHeight:300, overflowY:'auto'}}>
                <ul className="list-group">
                  {
                    qGenericObject.qLayoutHandler.qLayout&&qGenericObject.qLayoutHandler.qLayout.qFieldList.qItems.map(item=>
                      <li key={item.qName} className="list-group-item">{item.qName}</li>
                    )
                  }
                </ul>
              </div>
            </div>
          )
        }}
      </QGenericObject>
    </div>
  )
}

const Layout = props => {
  console.log('external layout', props)
  return (
    <div className="col-md-6">
      <div>My Generic Object - External layout mode</div>
      <div style={{maxHeight:300, overflowY:'auto'}}>
        <ul className="list-group">
          {
            props.qLayoutHandler.qLayout&&props.qLayoutHandler.qLayout.qFieldList.qItems.map(item=>
              <li key={item.qName} className="list-group-item">{item.qName}</li>
            )
          }
        </ul>
      </div>
    </div>
  )
}

export default MyQGenericObject

Props:

prop | type | default | required | description ---- | :----: | :-------: | :--------: | ----------- qObjectDef | Object | | :white_check_mark: | The definition of the qObject. Check the following links for details https://help.qlik.com/en-US/sense-developer/February2019/APIs/EngineAPI/genericobject.html quickSelectionMode | Boolean | true | :x: | If true the object will handle selections using Qlik Sense mode (user will have to accept selections) If set to false the object will handle selections using QlikView mode (selection immediately applied)

QShareCapabilityApi

This component is needed when you wan to display in the same React app Qlik Visualizations taken from 2 or more Qlik Sense apps. It wraps the Reaqtive component and provides the QCapabilityAPI context to the components downstream. This work around is needed to avoid to download QCapabilityAPI and AngularJS more than once.

Example:

import React from 'react'
import {QShareCapabilityApi, Reaqtive} from '@reaqtive/q'

const qConfig = {                                 //For QS Desktop
      host: 'YOUR HOST ADDRESS',                        //localhost
      secure: true,                                 //false
      port: 443,                                    //4848
      prefix: '',                                   //''
  };
const app1 = '8aa3a035-0689-4aab-a920-d6722509ed51'
const app2 = '58d7234b-b31c-4f24-b1f8-2c7453e557fa' 

const MySharedCapabilityApis = props =>
<QShareCapabilityApi qConfig={qConfig}>
  <Reaqtive qConfig={...qConfig, appId:app1}>
    ... your components here
  </Reaqtive>
  <Reaqtive qConfig={...qConfig, appId:app2}>
    ... your components here
  </Reaqtive>
</QShareCapabilityApi>

export default MySharedCapabilityApis

Props:

prop | type | default | required | description ---- | :----: | :-------: | :--------: | ----------- qConfig | Shape | | :white_check_mark: | qConfig is an object that provides reaqtive the params needed to connect to the Qlik server. params are: host, port, secure, prefix. appId is not needed in this case since the only purpose of this component is to download Qlik Capability APIs and provide it downstream. qConfig.host | String | | :white_check_mark: | host: the ip address or domain of the Qlik SystemProvider qConfig.port | Number | | :white_check_mark: | port: the port on which Qlik server is listening qConfig.prefix | String | | :white_check_mark: | prefix: Qlik's virtual proxy path qConfig.secure | Boolean | | :white_check_mark: | secure: true if the Qlik server uses https, false otherwise

QVariable

QVariable It provides a variable and its layout to its child. It automatically aupdate layout everytime the variable is updated by the engine calculations.

QVariable must have one and only one child. The child can be a React element (external layout mode) or a function that returns a React element (inline layout mode).

See the example below for details

Example:

import React from 'react'
import {QVariable} from '@reaqtive/q'

const MyQVariable = props => {
  const variableName = 'MonthNames';
  return(
    <div className="row">
      {/*Inline layout*/}
      <QVariable variableName={variableName}>
        {(qVariable)=>{
            console.log('variable', qVariable)
            return (
              <div className="col-md-6">
                <div>
                  <span>MyVariable name is: </span>
                  <span>{variableName}</span>
                </div>
                <span>MyVariable value is: </span>
                {qVariable.qLayoutHandler.qLayout&&<span>{qVariable.qLayoutHandler.qLayout.qText}</span>}
              </div>
            )
          }
        }
      </QVariable>
      {/*External layout*/}
      <QVariable variableName={variableName}>
        <Layout variableName={variableName}/>
      </QVariable>
    </div>
  )
}

const Layout = props =>
<div className="col-md-6">
  <div>
    <span>MyVariable name is: </span>
    <span>{props.variableName}</span>
  </div>
  <div>
    <span>MyVariable value is: </span>
    {props.qLayoutHandler.qLayout&&
      <span>{props.qLayoutHandler.qLayout.qText}</span>
    }
  </div>
</div>
export default MyQVariable

Props:

prop | type | default | required | description ---- | :----: | :-------: | :--------: | ----------- variableId | String | | :x: | The id of the variable. It must not be provided if variableName is provided variableName | String | | :x: | The name of the variable. It must not be provided if variableId is provided

HOOKS

useQFieldReducer

Description

a hook to retrieve a field from qDoc. if provided a defaulta value it selecte the value when it mounts and set the field to always one selected if isAlwaysOneSelected is set to true

Params

param | type | default value | required | description ---- | :----: | :-------: | :--------: | ----------- qFieldName | string | | :white_check_mark: | the name of the field qState | string | | :x: | the the alternate state the field will be linked to isAlwaysOneSelected | boolean | | :x: | flag to set isAlwaysOneSelected defaultValue | string | | :x: | the defaultValue to be selected before setting isAlwaysOneSelected to true resetOnUnmount | boolean | | :x: | if set to true it set isAlwaysOneSelected to false when unmount

Returns

It returns a qfieldHandler: the handler of the qlik field

useQLayoutReducer

Description

a hook to create and retrieve a the layout of a qObject (tested with generic objects and variables)

Params

param | type | default value | required | description ---- | :----: | :-------: | :--------: | ----------- qObjectHandler | qObjectHandler | | :white_check_mark: | the handler retrieved by useQObjectReducer qSelectionHandler | qSelectionHandler | | :x: | the handler that manages the selection state of the generic object, it is not needed if the qObject does not have a selection state to handle

Returns

It returns a qLayoutHandler: the handler of the qLayout

name | type | description ---- | :----: | ------- qLoading | boolean| if true the the handler is still waiting for response from the qlik server qError | boolean| if true there was an error retrieving the qLayout from the engine qLayout | object| the object returned from the server which contains the layout returned from the qlik server setLayoutUpdater | function| a method that accept a function that can be defined inside the view using the layout. by default the layout updater is qObject.getLayout(). it could be useful to change the layout updater when the generic object is in selecting mode applyQLayoutPatch | function| a function that allow to change the shape of the layout from the view. it is inteneded to be used when the qDisplayArea changes: the view asks the server for a new data page and the apply the patch to the already existing layout

useQObjectReducer

Description

a hook to create and retrieve a generic object from the qlik engine

Params

param | type | default value | required | description ---- | :----: | :-------: | :--------: | ----------- qObjectDef | qObjectDef | | :white_check_mark: | The object that tells to the qlik engine what object you want

Returns

It returns a qObjectHandler: the handler of the newly created object

name | type | description ---- | :----: | ------- qLoading | boolean| if true the the handler is still waiting for response from the qlik server qError | boolean| if true there was an error retrieving the qObject from the engine qObject | object| the object returned from the server reloadObject | function| a method to ask the qlik engine to recalculate the qObject shouldUpdate | boolean| a boolean variable which is set to true when the object is recalculated and you should ask the engine fro the layou (e.g. after selections) setShouldUpdate | function| a function to clean up the shouldupdate property after the needed effects have run

useQVariableReducer

Description

hook to retrieve a variable already available in the qDoc

Params

param | type | default value | required | description ---- | :----: | :-------: | :--------: | ----------- id | string | | :white_check_mark: | the name or id of the variable idType | string |name | :x: | tells to the variable reducer whether to use the name or id to retrieve the variable

Returns

It returns a qVariableHandler: the handler of the variable

useQVizHandler

Description

a hook to retrieve a variable already available in the qDoc

Params

param | type | default value | required | description ---- | :----: | :-------: | :--------: | ----------- qApp | object | | :white_check_mark: | the qApp object provided by the qApp context id | string | | :x: | if id is defined and chartProps are not, the useQVizHandler will ask for an already existing viz to the qApp chartProps | object | | :x: | if the chartProps is defined the useQVizHandler will create the visualization on the fly not considering an eventually provided id

Returns

It returns a qVizHandler: - handler to interact with the visualization retrieved from the qApp

name | type | description ---- | :----: | ------- qVizLoading | boolean| if true the the handler is still waiting for response from the qlik server qViz | object| the interface to interact with the visualization (e.g. to export it in excel, to resize it, etc.)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@reaqtive/q

Installation

PROVIDED FEATURES

REAQTIVE

Reaqtive

CONTEXTS

QGlobal

QDoc

QCapabilityApi

QApp

COMPONENTS

QGenericObject

QShareCapabilityApi

QVariable

HOOKS

useQFieldReducer

Description

Params

Returns

useQLayoutReducer

Description

Params

Returns

useQObjectReducer

Description

Params

Returns

useQVariableReducer

Description

Params

Returns

useQVizHandler

Description

Params

Returns