Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

@/application-shell-connectors

Complementary tools for the @commercetools-frontend/application-shell.

Installation

yarn add @commercetools-frontend/application-shell-connectors


# or


npm --save install @commercetools-frontend/application-shell-connectors

Additionally install the peer dependencies (if not present).

yarn add react @apollo/client


# or


npm --save install react @apollo/client

Application context

This section describes different parts of the information provided through the application context and how to access them.

Application properties

This is the list of the main properties you can access in the application context.

environment

The information about the runtime application environment such as the application ID or the application entry point.

{
  "environment": {
    "applicationId": "ckw3vt1hv034901uzio4bkzc3:my-custom-application",
    "applicationName": "My Custom Application",
    "entryPointUriPath": "my-custom-application"
  }
}

user

The information about the logged in user.

{
  "user": {
    "id": "3mj76c04-f910-4223-84e1-f97b0fe291c2",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "businessRole": "Consultant",
    "locale": "en-GB",
    "timeZone": "Europe/Berlin",
    "projects": [
      { "key": "my-project-A", "name": "My Project A" },
      { "key": "my-project-B", "name": "My Project B" }
    ]
  }
}

If the user logged into the Merchant Center using Single Sign-On, we expose an additional property idTokenUserInfo which contains some of the user info claims (OpenID Connect) from the user's Identity Provider.

{
  "user": {
    "id": "3mj76c04-f910-4223-84e1-f97b0fe291c2",
    "email": "aHR0cHM6Ly9kZXYt0udXMuYXVLzphdXRoiMDljMjYzZWQwOTg4MmU2OGU=@3241a8e3-cc17-4e7e-b6vz-1d0fdb.sso",
    "firstName": "John",
    "lastName": "Doe",
    "businessRole": "Consultant",
    "locale": "en-GB",
    "timeZone": "Europe/Berlin",
    "projects": [
      { "key": "my-project-A", "name": "My Project A" },
      { "key": "my-project-B", "name": "My Project B" }
    ],
    "idTokenUserInfo": {
      "iss": "<the-issuer>",
      "sub": "<the-subject>",
      "aud": "<the-audience>",
      "exp": 1665076522603,
      "iat": 1665040077648,
      "email": "john.doe@example.com",
      "name": "John Doe"
    }
  }
}

This feature is available from version 21.17.0 onwards.

project

The information about the currently selected project.

{
  "project": {
    "countries": ["DE", "US"],
    "currencies": ["EUR", "USD"],
    "key": "project-a",
    "languages": ["de-DE", "en-US"],
    "name": "Project A",
    "ownerId": "3mj76c04-f910-4223-84e1-f97b0fe291c2",
    "ownerName": "My Organization"
  }
}

dataLocale

The selected data locale that is used to render localized data in your application. You should include it as the selected language in components like LocalizedTextField.

{
  "dataLocale": "de"
}

This is not the value used for the Merchant Center language, which is based on the user.locale.

Custom user properties

On top of the default properties in the context.environment object, any property defined in the additionalEnv object will be available in the context.environment object as well.

This is useful to inject values specific to your application. For example:

custom-application-config.jsonjson
{
  "name": "My Custom Application",
  "entryPointUriPath": "my-custom-application",
  "cloudIdentifier": "gcp-eu",
  "additionalEnv": {
    "trackingSentry": "https://000@sentry.io/000"
  }
}

The context.environment object will then include the trackingSentry property:

{
  "environment": {
    "applicationId": "ckw3vt1hv034901uzio4bkzc3:my-custom-application",
    "applicationName": "My Custom Application",
    "entryPointUriPath": "my-custom-application",
    "trackingSentry": "https://000@sentry.io/000"
  }
}

Usage

useApplicationContext

A React hook that allows to access the ApplicationContext and selectively pick the necessary properties.

import { useApplicationContext } from '@commercetools-frontend/application-shell-connectors';


const DisplayLocale = () => {
  const dataLocale = useApplicationContext((context) =>
    applicationContext.dataLocale
  );
  render() {
    return (
      <div>
        <h1>Current data locale: {dataLocale}</h1>
      </div>
    );
  }
}


export default DisplayLocale;

withApplicationContext

A higher-order component (HOC) that allows to access the ApplicationContext and selectively pick the necessary properties. This is the equivalent of the React hook useApplicationContext.

import { withApplicationContext } from '@commercetools-frontend/application-shell-connectors';


class DisplayLocale extends React.Component {
  render() {
    return (
      <div>
        <h1>Current data locale: {this.props.dataLocale}</h1>
      </div>
    );
  }
}


export default withApplicationContext((applicationContext) => ({
  dataLocale: applicationContext.dataLocale,
}))(DisplayLocale);

Project image settings

Product images can be uploaded to Composable Commerce or referenced from external sources.

By default, images referenced from external sources are not displayed in the Merchant Center. This avoids possible performance issues in case the size of those images is big.

To display images referenced from external sources, you must define a configuration that rewrites the URL of the images to versions of the image that have a smaller size. You can configure that in the Merchant Center Settings > Project settings > Miscellaneous.

This configuration can be fetched from your Custom Application using the following components.

Usage

ProjectExtensionProviderForImageRegex

This is the React context provider that loads the image regex configuration and exposes it via a React context so that children can access the configuration.

This component must be defined in a parent component where children of this component need to access the configuration.

Properties

PropsTypeRequiredValuesDefaultDescription
childrenReactNode✅--Components that should be rendered within the scope of this provider.
skipboolean--falseDisables loading images configuration.

useProjectExtensionImageRegex

A React hook that allows accessing the project images configuration.

import { useProjectExtensionImageRegex } from '@commercetools-frontend/application-shell-connectors';


function MyComponent() {
  const { isLoading, imageRegex } = useProjectExtensionImageRegex();


  if (isLoading) return <LoadingSpinner />;


  return (
    <div>
      <h1>Project images regex: {JSON.stringify(imageRegex)}</h1>
    </div>
  );
}


function MyApp() {
  return (
    <ProjectExtensionProviderForImageRegex>
      <MyComponent />
    </ProjectExtensionProviderForImageRegex>
  );
}

GetProjectExtensionImageRegex

Use this component to access the project images configuration, using a render prop function.

function MyComponent() {
  return (
    <GetProjectExtensionImageRegex
      render={({ isLoading, imageRegex }) => {
        if (isLoading) return <LoadingSpinner />;


        return (
          <div>
            <h1>Project images regex: {imageRegex}</h1>
          </div>
        );
      }}
    />
  );
}


function MyApp() {
  return (
    <ProjectExtensionProviderForImageRegex>
      <MyComponent />
    </ProjectExtensionProviderForImageRegex>
  );
}

Properties

PropsTypeRequiredValuesDefaultDescription
renderFunction
See signature.		✅--Function to render children component with the image regex configuration.

Signature render

(
  render: (imageRegexContextData: TImageRegexContext) => ReactNode
) => void

This is the shape of the parameter provided in the render prop:

type TImageRegexContext = {
  isLoading: boolean;
  imageRegex?: {
    small?: {
      flag: string;
      replace: string;
      search: string;
    } | null;
    thumb?: {
      flag: string;
      replace: string;
      search: string;
    } | null;
  } | null;
};

withProjectExtensionImageRegex

A higher-order component (HOC) to access the image regex configuration.

class MyComponent extends React.Component {
  render() {
    const { imageRegexData } = this.props;
    return (
      <div>
        <h2>Project images regex is loading?: {imageRegexData.isLoading}</h2>
        <h2>Project images regex: {imageRegexData.imageRegex}</h2>
      </div>
    );
  }
}


const WrappedComponent = withProjectExtensionImageRegex()(MyComponent);


class MyApp extends React.Component {
  render() {
    return (
      <ProjectExtensionProviderForImageRegex>
        <MyComponent />
      </ProjectExtensionProviderForImageRegex>
    );
  }
}

Properties

PropsTypeRequiredValuesDefaultDescription
propKeystring--imageRegexDataName of the prop in which the context data of the regular expression for the image is passed to the wrapped component.