@reaqtive/components v0.0.0-beta.18

@reaqtive/components

This package helps creating guided analytics using Qlik APIs. It provides a set of reusable react components to speed up mash up developments. You can choose to use stand alone components and build your own navigation and routing functionalities or you can use RqtvApp and RqtvPage for built-in page navigation functionalities.

Installation

npm install @reaqtive/components

@reaqtive/q will be installed as well, since @reaqtive/components depends on it. @reaqtive/q will help you interact with Qlik engine and Qlik Capability APIs

PROVIDED FEATURES

• FILTERS
• VISUALIZATIONS
• APP OBJECTS
• APP
• TRIGGERS
• STYLES

FILTERS

RqtvButtonBar

RqtvButtonBar it is a paginated listbox shaped as a buttonbar It does not ask for selection confirmation, but just toggle the selection when a button is clicked

You can twek its behavuiour using props.

You can customize its styles using css or using props.

Example:

import React from 'react'
import {RqtvButtonBar} from '@reaqtive/components'

const MyRqtvButtonBar = props =>
<RqtvButtonBar
  qFieldExpr = "$Field"
/>

export default MyRqtvButtonBar

Props:

RqtvDropdownFilter

RqtvDropdownFilter It is a listbox shaped as a dropdown. It has the same responsive behaviour as bootstrap dropdown when wrapped in a collapse

You can twek its behavuiour using props.

You can customize its styles using css or using props.

Example:

import React from 'react'
import {RqtvDropdownFilter} from '@reaqtive/components'

const MyRqtvDropdownFilter = props =>
<RqtvDropdownFilter
  qFieldExpr="Customer"
  dropdownMenuItemStyle={{textTransform:'uppercase'}}
/>

export default MyRqtvDropdownFilter

Props:

RqtvListbox

RqtvListbox It looks like a Qlik Sense listbox, but is always expanded (does'not turn into a drop down). It will fill its container width

You can twek its behavuiour using props.

You can customize its styles using css or using props.

Example:

import React from 'react'
import {RqtvListbox} from '@reaqtive/components'

const MyRqtvListbox = props => {
  return(
    <RqtvListbox
      qFieldExpr="Customer"
      qLabelExpr="=count(distinct Customer)"
      height={300}
    />
  )
}

export default MyRqtvListbox

Props:

RqtvModalListbox

RqtvModalListbox It allows you to wrap a listbox inside a modal: the listbox will be hidden and a button will be shown. Clicking the button the listbox will appear inside a modal

Example:

import React from 'react'
import {RqtvModalListbox} from '@reaqtive/components'

const MyRqtvModalListbox = props =>
<RqtvModalListbox
  listboxProps={{
    qFieldExpr:"$Table",
    height:300
  }}
/>

export default MyRqtvModalListbox

Props:

RqtvSearchField

RqtvSearchField It provides you an input field to search a listbox. When the user starts typing a dropdown menu appears under the input field.

You can tweak its behaviour using props

You can customize style using props and css

Example:

import React from 'react'
import {RqtvSearchField} from '@reaqtive/components'

const MyRqtvSearchField = props =>
<RqtvSearchField
  qFieldExpr="Customer"
  placeholder="Search"
/>
export default MyRqtvSearchField

Props:

RqtvMultibox

RqtvMultibox

It returns an accordion that shows a list of fields. A listbox is displayed for the active field. One field at a time can be active.

Example:

import React from 'react'
import {RqtvMultibox} from '@reaqtive/components'

const MyRqtvMultibox = props => {
  return(
    <RqtvMultibox
      fieldList={['$Table', '$Field']}
    />
  )
}

export default MyRqtvMultibox

Props:

VISUALIZATIONS

QViz

QViz

It is a component that allows to retrieve Qlik visualizations. Qlik visualizations can be retrieved by id (if they already exists in the Qlik Sense app) or they can be created on the fly providing the properties to the engine. QViz also provide an imperative handle to inteact with Qlik visualizazion. To access the handle you have to provide a handle to the QViz component

Example:

import React from 'react'
import {QViz} from '@reaqtive/components'

const MyQVizExamples = () =>
  <>
    <MyQVizFromApp/>
    <MyQVizOnTheFly/>
  </>


const MyQVizFromApp = props => {
  return(
    <QViz
      id="QYthJs"
      height={250}
    />
  )
}

const MyQVizOnTheFly = props =>{
  return(
    <QViz
      id="VizExample1"
      chartProps={{
        chartType:'barchart',
        chartColumns: [
          {
            "qDef":{
              "qFieldDefs": ["[Product Sub Group Desc]"],
               "qFieldLabels": ["Product Sub Group"],
               "qSortCriterias":[{qSortByExpression:1,qExpression:"=Sum([Sales Quantity]*[Sales Price])"}],
               "qReverseSort":true
             }
           },
          "Customer Type",
          {
            "qDef":{
              "qDef":"=Sum([Sales Quantity]*[Sales Price])",
              "qLabel":"Revenue"
            }
          }
        ],
        rest: {
          "showTitles": false,
          "title": "Revenue",
          "barGrouping":{grouping:"stacked"}
        }
      }}
      height={300}
    />
  )
}

export default MyQVizExamples

Props:

RqtvVizContainer

RqtvVizContainer

It provides a container to a visualization. It accepts multiple children. In case i detects more tha one child, it shows one child at a time and a dropdown menu to toggle the desired child. If its children provide exports methods it automatically shows export buttons

Example:

import React, {useState, useEffect, useRef} from 'react'
import {RqtvVizContainer, QViz, RqtvMaximizePortalEl} from '@reaqtive/components'

const MyRqtvContainer = props =>
<RqtvVizContainer
  height={'300px'}
  showExportExcel={true}
  showExportPdf={true}
  showExportImg={true}
  maximizeElRef={props.maximizeElRef}
  onMaximize={props.onMaximize}
>
  <QViz id="nRxXG" title="bar chart"/>
</RqtvVizContainer>

const MyMultiVizRqtvContainer = props =>
<RqtvVizContainer
  style={{height:'300', maxHeight:'300'}}
  maximizeElRef={props.maximizeElRef}
  onMaximize={props.onMaximize}
  vizRef={props.vizRef}
>
  <QViz key="pDKRhr" id="pDKRhr" title="scatter chart"/>
  <QViz key="nvqpV" id="nvqpV" title="line chart"/>
</RqtvVizContainer>

const MyRqtvContainerExample = props => {
  const maximizeElRef = useRef()
  const vizRef = useRef()

  const viz = vizRef.current&&vizRef.current.getQViz()
  /**
    * HTML overflow is handled by RqtvApp if the RqtvMaximizePortalEl and RqtvVizContainer
    * are inside it, otherwise you will have to handle it in your code, below an example
    */

  const [isMaximized, setIsMaximized] = useState(false)

  useEffect(()=>{
    const html = document.getElementsByTagName("html")[0];
    const maximize = () => {
      html.style.overflow ='hidden'
      html.scrollTop=0
    }
    const minimize = () => {
      html.style.overflow ='auto'
    }
    isMaximized?maximize():minimize()
  }, [isMaximized])

  const onMaximize = () => {
    setIsMaximized(!isMaximized)
  }

  return(
    <>
      <RqtvMaximizePortalEl maximizeElRef={maximizeElRef}/>
      <MyRqtvContainer
        maximizeElRef={maximizeElRef}
        onMaximize={onMaximize}
      />
      <MyMultiVizRqtvContainer
        maximizeElRef={maximizeElRef}
        onMaximize={onMaximize}
        vizRef={vizRef}
      />
    </>
  )
}
export default MyRqtvContainerExample

Props:

APP OBJECTS

RqtvCurrentSelections

RqtvCurrentSelections

it is a toolbar that displays the current selection status and the buttons to go back, forward and clear current selections. Clicking on the button displayin the number of current selections, a modal will appear showing the current selection box (fields and selected values) It currently does not support alternate states. It always display the default state. Styles can be customized via css (or scss)

Example:

import React from 'react'
import  {RqtvCurrentSelections} from '@reaqtive/components'

const MyRqtvCurrentSelections = props =>
    <RqtvCurrentSelections
      useCurrentSelectionModal={true}
      isResponsive={true}
      showModalToggler={true}
      alwayShowToolbar={true}
      hidePrefix={'%'}
    />

export default MyRqtvCurrentSelections

Props:

RqtvSearchObject

RqtvSearchObject

It dispays a search object to search a single string in multiple fields.

If rendered inside the rqtv-navbar it will have fixed position and search results will colver the underlying page

Example:

import React from 'react'
import {RqtvSearchObject} from '@reaqtive/components'

const MyRqtvSearchObject =  props =>
   <RqtvSearchObject
      useBackdrop={false}
      alwaysExpanded={false}
      expandFrom='left'
      resultsWidth='100%'
      placeholder="Search"
    />

export default MyRqtvSearchObject

Props:

RqtvNavbar

RqtvNavbar

It is a component that renders the top navbar of the reaqtive app and add spacing to the top of the page if the navbar is fixed top. It includes the RqtvCurrentSelections component and the RqtvSearchObject component. It is based on bootstrap navbar, its styles can be customized using navbarClassName prop which will be passed to the navbar itself or via sass/css

Example:

import React from 'react'
import {RqtvNavbar} from '@reaqtive/components'

const MyRqtvNavbar = props => {
  return(
  <>
    <div className="border border-primary">
      <RqtvNavbar
        showSideMenuToggle={false}
        title="RqtvNavbar"
        fixedTop={false}
      />
      <div className="container py-5">
        <p>Below your content</p>
      </div>
    </div>
  </>
  )

}

export default MyRqtvNavbar

Props:

RqtvSideMenu

RqtvSideMenu

It returns toggleable fixed-positioned side menu displayed on the left of the page. Default tabs are the list of pages of the app and a multibox with filters. The open/close state has to be managed in parent component

Example:

import React, {useState} from 'react'
import {RqtvSideMenu, RqtvSideMenuMain} from '@reaqtive/components'

const MyRqtvSideMenu = props => {
  const [open, setOpen] = useState(false)

  const toggleSideMenu = () => {
    setOpen(!open)
  }

  const closeSideMenu = () => {
    setOpen(false)
  }

  return(
    <div style={{position:'relative'}}>
      <RqtvSideMenu
        isOpen={open}
        onClose={closeSideMenu}
      >
        <div className="text-light text-center">Here you can display your content</div>
      </RqtvSideMenu>
      <RqtvSideMenuMain isOpen={open}>
        <div className="container-fluid border border-primary">
          <div className="my-2">
            <button className="btn btn-primary" onClick={toggleSideMenu}>Toggle Menu</button>
          </div>
          <div className="py-2">Your content Here</div>
        </div>
      </RqtvSideMenuMain>
    </div>
  )
}

export default MyRqtvSideMenu

Props:

APP

Components described in this section are supposed to work together: it is suggested to use RqtvApp if you want to use the other components describe here.

RqtvApp

RqtvApp

It provides routing using react router and a context that allows you to store app info to be available everywhere inside your app.

Example:

import React from 'react'
import {RqtvApp} from '@reaqtive/components'
import {HomePage, FirstPage, SecondPage} from './rqtv-page'

const MyRqtvApp = (props) => {
  return(
    <RqtvApp title="Example App" brandUrl='/' hidePrefix="Prod" >
        <FirstPage path="/first-page"/>
        <SecondPage path="/second-page"/>
        <HomePage path="/" linkName="HOME"/>
    </RqtvApp>
  )
}

export default MyRqtvApp

Props:

RqtvPage

RqtvPage

It is a container based on the Route component of the React Router. It can't be used outside RqtvApp. It is a dummy component which provides a the RqtvPageContext and a QGenericObject with 2 experessions: qTitleExpr --> providing the qTitle result qConditionExpr --> providing the qCondition result When navigating among RqtvPages you can use query strings to select values in fields. Here an example of a query string: ?selections=Customer:Benedict;Zocalo&selections=Account:61099 . Place your query string at the end of the url you are navigating to. RqtvPage also accept triggers which are fired when the page mounts. Like Routes RqtvPages can be nested. RqtvPage does not unMount when the route change, to force unmount add a key prop (it has to be unique among pages).

Example:

import React from 'react'
import {RqtvStandardTemplate, RqtvPage, RqtvCurrentSelections, RqtvDropdownFilter,  RqtvListbox, RqtvModalListbox} from '@reaqtive/components'
import {useRouteMatch, NavLink} from 'react-router-dom'
import {useQFieldReducer} from '@reaqtive/q'
import MyRqtvStandardTemplate from './rqtv-standard-template'
import MyRqtvContainerExample from './rqtv-viz-container'
import TabsExample from './tabs'


const HomePage = props =>
<RqtvPage {...props} exact={true} qTitleExpr="'Homepage'">
  <RqtvStandardTemplate sideMenuFieldsMatch={{method:'include', mask:['Product*']}}>
    <div>Home Page</div>
    <MyRqtvContainerExample/>
    <RqtvCurrentSelections qState="comparison"/>
    <RqtvListbox alwaysOneSelected={true} defaultValue={'Zocalo'} qFieldExpr={"Customer"} />
  </RqtvStandardTemplate>
</RqtvPage>

const FirstPage = props =>{
  return(
    <RqtvPage {...props}>
      <RqtvStandardTemplate sideMenuFieldsMatch={{method:'include', mask:['Customer*', 'Account*']}}>
        <RqtvListbox qFieldExpr="Customer" />
        <MyFirstNestedPage/>
      </RqtvStandardTemplate>
    </RqtvPage>
  )
}


const MyFirstNestedPage = props =>{
  const { path, url } = useRouteMatch();

  return(
    <>
      <RqtvPage
        path={`${path}/with-condition`}
        qConditionExpr={'=count(distinct Customer)=1'}
        fallbackPage={`${path}`}
      >
        <div>this is a nested page with a condition</div>
        <MyRqtvContainerExample/>
      </RqtvPage>
      <RqtvPage path={`${path}`} exact={true}>
        <div>this is a nested page with no condition</div>
        <div>
          <NavLink to={`${url}/with-condition/?selections=Customer:Benedict&selections=Account:61099`}><button>go to page with condition</button></NavLink>
          <MyRqtvContainerExample/>
        </div>
      </RqtvPage>
    </>
  )
}

const SecondPage = props =>
<RqtvPage {...props} qTitleExpr="'Revenue is: '&Sum([Sales Quantity]*[Sales Price])" exactActiveMatch={false}>
  <MyRqtvStandardTemplate>
    <TabsExample/>
  </MyRqtvStandardTemplate>
</RqtvPage>

export {HomePage, FirstPage, SecondPage}

Props:

RqtvStandardTemplate

RqtvStandardTemplate

It is a component that allows you to use Reaqtive main components without having to declare them one by one. Of course does not allow the same flexibility as recreating a template manually. It includes the RqtvSideMenu, the RqtvNavbar and the RqtvPageHeader. It is suggested to use this component inside the RqtvApp

Example:

import React from 'react'
import {RqtvStandardTemplate, RqtvPage} from '@reaqtive/components'


const MyRqtvStandardTemplate = props => {
  return(
    <RqtvStandardTemplate sideMenuClickAwayAccept={false}>
      <div>Standard Template Example</div>
      {props.children}
    </RqtvStandardTemplate>
  )
}

export default MyRqtvStandardTemplate

Props:

TRIGGERS

RqtvApp and RqtvPage accept arrays of triggers as props. They are fired before rendering the app or the page. This is still an experimental feature, but data structures are very unlikely to change. Below you can find the types of triggers you can use described as PropTypes

/*Select one value of one field*/
const fieldSelectionTrigger = PropTypes.shape({
    type: 'fieldSelection',
    params: PropTypes.shape({
      fieldName:PropTypes.string,
      value:PropTypes.string,
    })
  })

/*Select multiple values of one field*/
const fieldSelectionsTrigger = PropTypes.shape({
  type: 'fieldSelections',
  params: PropTypes.shape({
    fieldName:PropTypes.string,
    value:PropTypes.arrayOf(PropTypes.shape({
      qText: PropTypes.string,
      qIsNumeric: PropTypes.bool,
      qNumber: PropTypes.number
    })),
  })
})

/*Clear one field*/
const clearFieldTrigger =  PropTypes.shape({
  type: 'clearField',
  params: PropTypes.shape({
    fieldName:PropTypes.string,
  })
})

const triggerType = PropTypes.oneOf([clearFieldTrigger,fieldSelectionsTrigger,fieldSelectionTrigger])

STYLES

Styles are based on bootstrap classes and components. In reaqtive components plain boostrap classes have been used and they are scoped using the name of the Reaqtive components they are used into. For example the wrapper div of a RqtvListbox has rqtv-listbox class, the RqtvSideMenu a rqtv-side-menu class. You can customize the styles the components referring to these classes in your scss files. Moreover you can customize Reaqtive theme by including a theme file and changing theme variables values. You can add your theme creating an index.scss file and a theme.scss file. Below an example.

theme.scss

...
$primary: #5C88DA;
$side-menu-field-list-border-color:rgba(0,0,0,0);
$navbar-bg:#fff;
$navbar-color:$primary;
...

index.scss

// import files with this order otherwise Reaqtive theme will overwrite yours
@import "./styles/theme.scss";
@import "~@reaqtive/components/dist/index.scss";
...

index.js

...
import './index.scss'
...

You can find the complete list of Reaqtive theme variable here and the complete list of Bootstrap variables here