Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

@reaqtive/q

0.0.0-beta.2 • Public • Published

@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: '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 if true Reaqtive downloads capability APIs from Qlik server and provides the qlik object and the qApp to its children
qConfig Shape 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 appId: the id of the app reaqtive should connect to
qConfig.host String host: the ip address or domain of the Qlik SystemProvider
qConfig.port Number port: the port on which Qlik server is listening
qConfig.prefix String prefix: Qlik's virtual proxy path
qConfig.secure Boolean 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 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 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

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 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 host: the ip address or domain of the Qlik SystemProvider
qConfig.port Number port: the port on which Qlik server is listening
qConfig.prefix String prefix: Qlik's virtual proxy path
qConfig.secure Boolean 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 The id of the variable. It must not be provided if variableName is provided
variableName String 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 the name of the field
isAlwaysOneSelected boolean flag to set isAlwaysOneSelected
defaultValue string the defaultValue to be selected before setting isAlwaysOneSelected to true
resetOnUnmount boolean if set to true it set isAlwaysOneSelected to false when unmount

Returns

It returns a qfieldHandler: the handler of the qlik field

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 qField from the engine
qField object the object returned from the server to interact with the 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 the handler retrieved by useQObjectReducer
qSelectionHandler qSelectionHandler 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 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 the name or id of the variable
idType string name 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

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 qVariable from the engine
qVariable object the object returned from the server to interact with the variable
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

useQVizHandler

Description

a hook to retrieve a variable already available in the qDoc

Params

param type default value required description
qApp object the qApp object provided by the qApp context
id string if id is defined and chartProps are not, the useQVizHandler will ask for an already existing viz to the qApp
chartProps object 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.)

Install

npm i @reaqtive/q

DownloadsWeekly Downloads

6

Version

0.0.0-beta.2

License

MIT

Unpacked Size

141 kB

Total Files

34

Last publish

Collaborators

  • avatar