Handling notifications

Vue Storefront makes creating and customizing front-end notifications extremely easy. This guide presents several ways of leveraging them for the sake of improving the user experience.

Good to know

This guide assumes you have the following files in your project:

• ~/composables/useUiNotification/index.ts
• ~/plugins/notifications/index.ts
• ~/plugins/notifications/notifications.ts

useUiNotification composable

The most basic way of showing UI notifications to your user would be leveraging the useUiNotification composable defined in the ~/composables/useUiNotification directory. Its send() method allows you to dispatch any notification of type success, danger or info from virtually any component of your application. You can

Example

In the following example, we are sending a UI notification after a user adds his review on a Product Details Page.

<script>
import { useContext } from '@nuxtjs/composition-api';
import { useCartEntries } from '@vsf-enterprise/sapcc';
import { useUiNotification } from '~/composables';

export default {
  setup() {
    const { i18n } = useContext();
    const { add } = useCartEntries('main');
    const { send: sendNotification } = useUiNotification();

    const addToCart = async (product) => {
      /** Add product to cart */
      const { code: productCode } = product;
      await add({ productCode, quantity: 1 })
      
      /** Notify the user about success */
      sendNotification({ type: 'success', message: i18n.t('Product has been added to cart!') });
    }

    return { addToCart };
  }
};
</script>

The result will look like this:

The useUiNotification composable also allows you to show confirm pop-ups. They come in handy in situations where an additional user confirmation before performing some operation is required.

Example

In the following example, we are dispatching a persistent notification asking the user for confirmation before removing all products from the cart.

<script>
import { useContext } from '@nuxtjs/composition-api';
import { useUiNotification } from '~/composables';

export default {
  setup() {
    const { i18n } = useContext();
    const { send } = useUiNotification();

    const clearCart = () => {
      send({
        type: 'info',
        message: i18n.t('Are you sure you want to remove all products from your cart?'),
        persist: true,
        action: {
          text: i18n.t('Yes, I am sure.'),
          onClick: async () => {
            // execute the logic deleting all products from the cart
          }
        }
      });
    };

    return { clearCart };
  },
};
</script>

The result will look like this:

Remember about localization!

If your app has multiple locales available, strive for using i18n helpers (such as t from the example above) for dynamic translations wherever possible.

Central notifications plugin

Leveraging the useUiNotification composable directly is convenient. However, it requires you to import it in multiple components, scattering the notification logic all over the project.

To centralize that logic, the default Vue Storefront setup ships with a plugin located inside the ~/plugins/notification directory. It allows us to send notifications about either successful or unsuccessful requests sent to our API Middleware. It leverages the useUiNotification composable and Axios interceptors (opens new window) under the hood.

The pattern is very simple. Every request has its corresponding object inside the ~/plugins/notification/notifications.ts file where we can register error or success callbacks. The callbacks need to return a notification string we wish to show to the users. No success callback means no notification for the given request. No error callback means the default error message returned by SAP will be displayed.

Good to know

If you want to show no error message for the given request, simply register an error callback returning an empty string.

Example

In the following example, we are defining a notification for the successful updateCartEntry request. The request can be responsible for either updating the entry's quantity or its deliveryPointOfService. Therefore, the callback logic needs to be smart enough to recognize which case we are dealing with and return an appropriate notification message.

// ~/plugins/notification/notifications.ts

const NOTIFICATION_CALLBACKS {
  updateCartEntry: {
    success: (response) => response.config.data.includes('quantity')
      ? 'Prouct quantity has been updated!'
      : ''
  }
};

Example

In the following example, we are turning off any notifications for the OAuthUserTokenRefresh endpoint responsible for refreshing customers' tokens.

// ~/plugins/notification/notifications.ts

const NOTIFICATION_CALLBACKS = {
  OAuthUserTokenRefresh: {
    error: () => ''
  }
};

Good to know

All of the files mentioned in this guide can be subject to your changes. Feel free to modify their logic in a way that suits your needs best.