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
To install the @commercetools-frontend/application-shell-connectors
package, run the following command:
npm --save install @commercetools-frontend/application-shell-connectors
Additionally, install the peer dependencies (if not present).
npm --save install react @apollo/client
Custom View context
The Custom View context provides you with the Custom View properties that you can access using the useCustomViewContext
hook.
useCustomViewContext
A React hook that lets you to access the CustomViewContext
and selectively pick the necessary properties.
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;
Custom View properties
environment
The information about the runtime environment such as 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
that 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",}}}
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
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
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 Custom View in the context, you can add them to the additionalEnv
object and they will automatically be added to the context.environment
value.
For example, for the following custom-view-config
the trackingSentry
property is added in the context.environment
.
{"name": "My Custom View","cloudIdentifier": "gcp-eu","additionalEnv": {"trackingSentry": "https://000@sentry.io/000",}}
{"environment": {"customViewId": "ckw3vt1hv034901uzio4bkzc3","applicationName": "My Custom View","trackingSentry": "https://000@sentry.io/000",}}
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 View 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
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.
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 MyCustomView() {return (<ProjectExtensionProviderForImageRegex><MyComponent /></ProjectExtensionProviderForImageRegex>);}
GetProjectExtensionImageRegex
Use this component to access the project images configuration, using a render
prop function.
function MyComponent() {return (<GetProjectExtensionImageRegexrender={({ isLoading, imageRegex }) => {if (isLoading) return <LoadingSpinner />;return (<div><h1>Project images regex: {imageRegex}</h1></div>);}}/>);}function MyCustomView() {return (<ProjectExtensionProviderForImageRegex><MyComponent /></ProjectExtensionProviderForImageRegex>);}
Properties
Props | Type | Required | Values | Default | Description |
---|---|---|---|---|---|
render | Function 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;}