procore-environment

Disclaimer: Meant for Procore internal use only.

Description

Install

yarn add @procore/labs-procore-environment

Usage

Utility to provide Procore Environment for the decoupled frontend applications, aka "hydra clients".
As part of the initiative to move outside the monolith, this package provides functionality to fetch Procore Environment for a given client.

As of now, the provider accepts a optional config object that has projectId or companyId. If you are on the company level, you can pass in a config object that contains the companyId. If you are on the project level, you can pass in a config object that contains the projectId. However, if no config is passed in, the package will try to get the projectId or companyId by parsing the browser url. For example, if the current url is /23/company/directory, the package will use 23 as the companyId to fetch the Procore Environment.

Wrap your application with ProcoreEnvironmentProvider

import { render } from 'react-dom';
import { ProcoreEnvironmentProvider } from '@procore/labs-procore-environment';
import { Application } from './Application';
import CustomLoadingScreen from './CustomLoadingScreen';
import ErrorScreen from './ErrorScreen';

// Just need to pass either projectId or companyId, if both are passed in
// it will fallback to projectId. If no config is passed in, the package
// will parse the projectId or companyId from current browser url.
const config = isProject ? { projectId } : { companyId };

render(
  <ProcoreEnvironmentProvider
    config={config}
    loader={CustomLoadingScreen}
    errorFallback={ErrorScreen}
  >
    <Application />
  </ProcoreEnvironmentProvider>,
  document.getElementById('root')
);

To consume Procore Environment in your child components

import * as React from 'react';
import { useProcoreEnvironment } from '@procore/labs-procore-environment';

const YourComponent = () => {
  const procoreEnvironment = useProcoreEnvironment();

  return <div>{procoreEnvironment.currencySymbol}</div>;
};

Procore Environment Shape

The Procore Environment returned from the package could be different from the window.Procore.Environment, the new shape looks like:

type ProcoreEnvironment = {
  companyId: ID;
  companyName: string;
  currencySymbol: string;
  dateFormat: string;
  locale: string;
  projectId: ID | null;
  projectName: string | null;
  timeZone: string;
  userId: ID;
};

Props

Context

• config ({ projectId?: number, companyId?: number }, default: undefined)
  The config object that contains either projectId or companyId for the package to fetch the procore environment. If config is not being passed, the projectId or companyId will be parsed from the current browser URL.

• loader (React.ReactElement?, default: <Loading />)
  Customized loading screen while the package is fetching the Procore Environment. If not provided, it will fallback to a default one.

• errorFallback (React.ReactElement?, default: null)
  Customized error screen when the package failed to fetch the Procore Environment. If not provided, the default behavior is to display an empty screen.