Documentation

@/application-shell-connectors

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

Installation

To install the @commercetools-frontend/application-shell-connectors package, run the following command:

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

Application and Custom View contexts

The Application context or Custom View context provides you with properties that you can access using one of the following hooks:

Properties

environment

Information about the runtime environment.

For Custom Applications, this information includes the Custom Application ID and the application entry point:

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

For Custom Views, this information includes the Custom View ID:

{
  "environment": {
    "customViewId": "ckw3vt1hv034901uzio4bkzc3",
    "applicationName": "My Custom View",
  }
}

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.

customViewConfig

This property applies only to Custom Views.

The Custom View configuration registered in the Merchant Center.

{
  "defaultLabel": "My Custom View",
  "id": "ckw3vt1hv034901uzio4bkzc3",
  "labelAllLocales": [
    { "locale": "en", "value": "My Custom View" },
    { "locale": "es", "value": "Mi vista personalizada" },
  ],
  "locators": ["products.product_details.general"],
  "permissions": [
    { "name": "view", "oAuthScopes": ["view_products"] },
    { "name": "manage", "oAuthScopes": ["manage_products"] },
  ],
  "type": "CustomPanel",
  "typeSettings": {
    "size": "LARGE"
  },
  "url": "https://my-custom-view.com"
}

hostUrl

This property applies only to Custom Views.

Since the Custom Views render within a Merchant Center built-in application, this property will contain the current URL of the built-in application.

This can be useful if you need to fetch data related to an entity, as you can get its ID from the URL.

{
  "hostUrl": "https://<merchant-center-domain>/<project-key>/orders/111111-2222-3333-444-5555555555/general"
}

Custom user properties

To inject properties specific to your customization in the context, you can add them to the additionalEnv object in your Custom Application config or Custom View config, and they will automatically be added to the context.environment value.

In the following examples, the trackingSentry property is added to the context.environment.

For Custom Applications:

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"
  }
}

For Custom Views:

custom-view-config.mjsJavaScript
const config = {
  name: 'My Custom View',
  cloudIdentifier: 'gcp-eu',
  additionalEnv: {
    trackingSentry: 'https://000@sentry.io/000',
  },
  // ...
};
context.environmentJavaScript
{
  "environment": {
    "customViewId": "ckw3vt1hv034901uzio4bkzc3",
    "applicationName": "My Custom View",
    "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);

useCustomViewContext

A React hook that lets you to access the CustomViewContext and selectively pick the necessary properties.

Access dataLocale from the Custom View contextJavaScript React
import { useCustomViewContext } from '@commercetools-frontend/application-shell-connectors';


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


export default 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 customization 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 MyCustomization() {
  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 MyCustomization() {
  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

This section applies only to Custom Applications.

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.