# Application Shell connectors

Complementary tools for the [`@commercetools-frontend/application-shell`](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell.md).

## Installation

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

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

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

## Application and Custom View contexts

The Application context or Custom View context provides you with [properties](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell-connectors.md#properties) that you can access using one of the following hooks:

- For Custom Applications: [`useApplicationContext`](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell-connectors.md#useapplicationcontext)
- For Custom Views: [`useCustomViewContext`](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell-connectors.md#usecustomviewcontext)

### Properties

#### `environment`

Information about the runtime environment.

For Custom Applications, this information includes the [Custom Application ID](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#envproductionapplicationid) and the [application entry point](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#entrypointuripath):

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

For Custom Views, this information includes the [Custom View ID](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#envproductioncustomviewid):

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

#### `user`

The information about the logged in user.

```json
{
  "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](https://docs.commercetools.com/docs/identity/enterprise-sso/overview.md), we expose an additional property `idTokenUserInfo` which contains some of the user info claims (OpenID Connect) from the user's Identity Provider.

```json highlightedLines="14-22"
{
  "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.

```json
{
  "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](https://uikit.commercetools.com/?path=/story/components-fields--localizedtextfield).

```json
{
  "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.

```js
{
  "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.

```js
{
  "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](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config.md#additionalenv) or [Custom View config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config.md#additionalenv), and they will automatically be added to the `context.environment` value.

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

The following example shows the Custom Application Config:

```json title="custom-application-config.json" highlightLines="5-7"
{
  "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:

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

The following example shows the Custom View Config:

```js title="custom-view-config.mjs" highlightLines="4-6"
const config = {
  name: 'My Custom View',
  cloudIdentifier: 'gcp-eu',
  additionalEnv: {
    trackingSentry: 'https://000@sentry.io/000',
  },
  // ...
};
```

The following example shows the `context.environment`:

```js title="context.environment" highlightLines="5"
{
  "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.

```jsx highlightLines="4-6"
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`.

```jsx highlightLines="13-15"
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.

```jsx highlightLines="4-6" title="Access dataLocale from the Custom View context"
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 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

(a CSV formatted table follows. The first line are the column names.)
Props,Type,Required,Values,Default,Description
`children`,`ReactNode`,✅,-,-,Components that should be rendered within the scope of this provider.
`skip`,`boolean`,-,-,false,Disables loading images configuration.


#### useProjectExtensionImageRegex

A React hook that allows accessing the project images configuration.

```jsx highlightLines="4-6"
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.

```jsx
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

(a CSV formatted table follows. The first line are the column names.)
Props,Type,Required,Values,Default,Description
`render`,`Function`See [signature](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell-connectors.md#signature-render).,✅,-,-,Function to render children component with the image regex configuration.


##### Signature `render`

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

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

```ts
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.

```jsx
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

(a CSV formatted table follows. The first line are the column names.)
Props,Type,Required,Values,Default,Description
`propKey`,`string`,-,-,`imageRegexData`,Name of the prop in which the context data of the regular expression for the image is passed to the wrapped component.

## Related pages

- [Section overview page](https://docs.commercetools.com/merchant-center-customizations.md)
- [Previous page: Application Shell](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-shell.md)
- [Next page: Application components](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/commercetools-frontend-application-components.md)