Repository files navigation

React utils for Openfin Application development

• All in typescript
• Provide general features for frameless window
• Provide a general client-side config service

DOCUMENTATION

    npm i react-openfin     or     yarn add react-openfin

Before continue, make sure you have already generated a sample project viaopenfin-js-clior usehttps://github.com/openfin-js-app/openfin-react-concise as a helper for simplicity.

First of all, thanks tomaterial-ui, a awesome more-than-style lib help us materialize our projects.

If you check the modules I installed in the package.json, you might find out there are two modules which are part ofopenfin-js-app.

• react-openfin-mat-impl

react-openfin-mat-impl, you can tell by the name, it is an implementation ofreact-openfin viamaterial-ui. And,it is due to this, thatreact-openfin-mat-impl internally control the version ofreact-openfin it wanna implement.And app developer does not have to includereact-openfin specifically! Besides these, the primary task ofreact-openfin-mat-impl is to provide reusable components to simplify the openfin app developing. All the details andprops of the components exported will be covered in the latterreact-openfin-mat-impl section.

• react-openfin-scripts

react-openfin-scripts is likereact-scripts, but it does one more thing,react-openfin-scripts enhances thedefault setting to adapt the new openfin app requirements, also provide few additional tasks to aid openfin app developing,like serving, packaging, start with openfin app, serve with app and a new dot env profile variableREACT_APP_ENV to loaddifferent dotenv config.

• react-openfin

Since you do not have to installreact-openfin but it exists already brought byreact-openfin-mat-impl. In the professionalsection, we might encounterreact-openfin more frequency for advance features. Thus it is not harm to know it for now.react-openfin just provides few react contexts and helper event format to scandalize the way to useOpenfin js api. It onlyfocus on the logic instead of views. Andreact-openfin-mat-impl materialize the viewsreact-openfin trying to expresss.

In a nutshell,

• if wanna seize a reusable component, checkreact-openfin-mat-impl.
• if wanna tweak communicate with the openfin settings, checkreact-openfin instead.
• need to write a script to do some scaffolding tasks, checkreact-scripts, it might already have one already.

With a big pic of what is what. Time to get hands dirty a little bit.

A regular react-app cannot be an openfin js app, thus we need some general initialization step. Thanks toReact &react-openfin, this procedure could be very simple.

import*asReactfrom'react';import*asReactDOMfrom'react-dom';import{InitializeReactOpenfin,ReactOpenfin}from'react-openfin';importi18nfrom'./i18n';importhistfrom'./utils/history';importAppfrom'./App';declareconstwindow:any;InitializeReactOpenfin({fin:window.fin,finUuid:process.env.REACT_APP_FIN_UUID,    i18n,    hist});ReactDOM.render(<ReactOpenfin><Suspensefallback={<CircularProgress/>}><I18nextProvideri18n={i18n}><App/></I18nextProvider></Suspense></ReactOpenfin>,document.getElementById('root'));

All app developers need to do is import initializerInitializeReactOpenfin and wrapperReactOpenfin fromreact-openfinand fill in the init argument ofInitializeReactOpenfin and useReactOpenfin to wrap all your components. That is it.

However, you might also notice there are two other pals called i18n and history required in the init argument.i18n is instance of thei18next lib to support multi-lang and hist is a js libhistory that lets use easily manage sessionhistory anywhere. And their setup codes can be find over herei18n.ts andhistory.ts

Oncereact-openfin is initialized, it is the time to start the it. The best place to start it is undoubtedlythe root entryApp component.

import*asReactfrom'react';import{useContext,useEffect}from'react';import{Router,Route,Switch,Redirect}from'react-router-dom';import{ApplicationContext,ConfigContext,MuiTheme}from'react-openfin';import{buildMuiTheme}from'react-openfin-mat-impl';importCssBaselinefrom'@material-ui/core/CssBaseline';import{MuiThemeProvider,createMuiTheme}from'@material-ui/core/styles';import{ThemeProvider}from'@material-ui/styles';importindexRoutesfrom'./routes';importhistfrom'./utils/history';constApp:React.FunctionComponent<{}>=({})=>{const{state:{            loading,},actions:{            onApplicationStart,            onChildWinStart,            onNotificationStart,}}=useContext(ApplicationContext);useEffect(()=>{console.log("App Entry::init effect");// !!!README!!!// make sure to start the application/childWindow/Notification at the Entry component to boot react-openfinif(window.name===process.env.REACT_APP_FIN_UUID){onApplicationStart();}elseif(window.location&&window.location.pathname.toLowerCase().indexOf('notification')>-1){onNotificationStart();}else{onChildWinStart();}},[]);const{config:{application:{                theme}}}=useContext(ConfigContext);constmuiTheme=buildMuiTheme(theme);return(<React.Fragment><CssBaseline/><Routerhistory={hist}><MuiThemeProvidertheme={muiTheme}><ThemeProvidertheme={muiTheme}><Switch>{                                indexRoutes.map((prop:any,key)=>{if(prop.redirect)return<Redirectfrom={prop.path}to={prop.to}key={key}/>;return<Routepath={prop.path}component={prop.component}key={key}/>;})}</Switch></ThemeProvider></MuiThemeProvider></Router></React.Fragment>);}exportdefaultApp;

We import the two context apiApplicationContextConfigContext fromreact-openfin.ApplicationContext containsthe functions to start the openfin js app.

• onApplicationStart
• onNotificationStart
• onChildWinStart

You can tell by name, one to start main window application, one to start a regular notification and one to start aregular child window.

Since the react app is a SPA, we do not want build each one SPA for each window or app; better share and reuse as much codeas possible. Thus for the same App component, we have to make decision and tell them apart from MainWindow, Child Window orNotification.

• If current window is the only one main window,Openfin will popluate the window.name field with UUID
• Mentioned in the section, the router path for notification will contain the string of notificaiton.
• Besides main window and notification, the rest should be the child window.

Thus basing on these condition, we triggered corresponding init function.

As we are going to reuse components fromreact-openfin-mat-impl, we need to initialize a theme to formaterial-ui also.react-openfin-mat-impl provides an expected theme builderbuildMuiTheme, with the dark/light theme identifier, amuiTheme is created and app developer can still modify the theme before giving to the ThemeProvider.

The rest of children components are loaded routing children viareact-router-dom. We will cover the routing comps inthe next section.