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

Permissions

As we learned in OAuth Scopes and user permissions, each Custom View has a unique pair of default user permissions at its disposal: "view" and "manage." Additionally, you can use more granular permission groups to cover strict business requirements.

When developing a Custom View you might want to enforce these user permissions in some parts of your application. For example, performing certain actions like creating, updating, or deleting a resource should only be possible if the user has "manage" permission.

Defining constants

To avoid defining permissions manually, we recommend using the resolveCustomViewResourceAccesses function to define them in a constants.js file.

constants.jsJavaScript

import { resolveCustomViewResourceAccesses } from '@commercetools-frontend/application-config';

export const PERMISSIONS = resolveCustomViewResourceAccesses();

The PERMISSIONS variable contains a View and Manage properties:

PERMISSIONS.View: maps to View.
PERMISSIONS.Manage: maps to Manage.

You can then use the PERMISSIONS variable to reference the permission in the application code.

Additional permissions groups

When using additional permission groups, you must also provide the unique group to the resolveCustomViewResourceAccesses function to generate the correct permission keys.

The group names can be exported and referenced also in the Custom View config file.

constants.jsJavaScript

import { resolveCustomViewResourceAccesses } from '@commercetools-frontend/application-config';

export const PERMISSIONS_WITH_GROUPS = resolveCustomViewResourceAccesses(
  ['delivery', 'promotion']
);

In this scenario, the PERMISSIONS_WITH_GROUPS variable contains View, Manage, ViewDelivery, ManageDelivery, ViewPromotion and ManagePromotion properties, with the values being the computed values based on the provided permission group names.

Applying user permissions

A Custom View allows, for example, to check and evaluate if certain user permissions are assigned or not, making it possible to determine whether to render something or not, or to turn off some UI functionalities.

In routes

In case certain routes should not be accessible without proper user permissions, you can render the route conditionally based on the evaluated permission.

To do so, you can use the useIsAuthorized as follows:

routes.jsJavaScript React

import { Switch, Route, useRouteMatch } from 'react-router-dom';
import { useIsAuthorized } from '@commercetools-frontend/permissions';
import { PageUnauthorized } from '@commercetools-frontend/application-components';
import { PERMISSIONS } from './constants';
import ChannelsCreate from './components/channels-create';
import ChannelsList from './components/channels-list';

const CustomViewRoutes = () => {
  const match = useRouteMatch();
  const canManage = useIsAuthorized({
    demandedPermissions: [PERMISSIONS.Manage],
  });

  return (
    <Switch>
      <Route path={`${match.path}/new`}>
        {canManage ? (
          <ChannelsCreate />
        ) : (
          <PageUnauthorized />
        )}
      </Route>
      <Route>
        <ChannelsList>
      </Route>
    </Switch>
  );
};

In components

You can evaluate user permissions in your React components, for example to deactivate a button.

import { useIsAuthorized } from '@commercetools-frontend/permissions';
import PrimaryButton from '@commercetools-uikit/primary-button';
import { PERMISSIONS_WITH_GROUPS } from '../constants';

const MyComponent = () => {
  const canManage = useIsAuthorized({
    demandedPermissions: [PERMISSIONS_WITH_GROUPS.ManagePromotion],
  });

  return (
    <div>
      <PrimaryButton
        label="Create promotion"
        isDisabled={!canManage}
      />
    </div>
  )
}