[Checkout] feature components

[andrzejewsky]

As some of the parts in VSF are really complicated and most of the logic belongs to the components, it's better to provide entire components with the ability for customizations instead of just composables.

Considering payment - we have a lot of variety of implementing such a thing, and each depends on the payment provider. Clearly, most of logic is hidden inside the components, while the composables are handling only a small piece of it.

To solve that issue we can introduce feature components, or agnostic (to some extend) components that are handling a implementation of this specific case, just based on the platform we integrate with.

We can assume that kind of component should take some input props (that comes from integration) and emits some predefined events that are mandatory to be consistent with a platform.

Example:

<template>
  <div>
    <input name="firstName" />
    <input name="lastName" />

    <PaymentProvider
      :data="shipping"
      @initialized="handleInitialize"
      @loaded="handleLoaded"
      @payment:beforePay="handleBeforePay"
      @payment:afterPay="handleAfterPay"
      @methods:loaded="handleMethodsLoaded"
      @methods:selected="handleSelectMethod"
      @methods:changed="handleChangeMethod"
    >
      <tepmlate #method="{ id, name, price }">
        <div>render single payment method</div> 
      </template>

      <tepmlate #methods="{ methods }">
        <div>render entire methods container</div> 
      </template>

      <tepmlate #applePay="{ id, name, apple }">
        <div>render specific method</div> 
      </template>

      <tepmlate #error="{ message }">
        <div>render error</div> 
      </template>

      <tepmlate #submit="{ next }">
        <div>render submit button</div> 
      </template>
    </PaymentProvider
  </div>
</template>

<script>
import { PaymentProvider } from '@vue-storefront/checkout-com'
import { useShipping, useOrder } from '@vue-storefront/commercetools'

export default {
  components: {
    PaymentProvider
  },
  setup(props, ctx) {
    const { shipping } = useShipping();
    const { placeOrder } = useOrder()

    // called on initialization, we can change configuration if it's needed
    const handleInitialize = (config) => {
      return config
    }

    // called once payment sdk is loaded
    const handleLoaded = (sdk) => {

    }

    // returns arguments to the `pay` inside of PaymentProvider
    const handleBeforePay = async (currentArgs) => {
      const { order } =  await placeOrder()

      return { ...curentArgs, order }
    }

    // called after payment request has been sent, we can react on response
    const handleAfterPay = async (paymentResponse) => {
      ctx.root.$router.redirect('/checkout/next-step')
      // or:
      ctx.root.$router.redirect(paymentResponse.redirectUrl)
    }

    // called when payment methods are loaded
    const handleMethodsLoaded = async () => {

    }

    // called when user pick payment method
    const handleSelectMethod = async (method) => {

    }

    // called when user configure method. eg. fill card details
    const handleChangeMethod = async (method) => {

    }

    return {
      shipping,
      handleInitialize,
      handleLoaded,
      handleBeforePay,
      handleAfterPay,
      handleMethodsLoaded,
      handleSelectMethod,
      handleChangeMethod
    }
  }
}

</script>

We have the following parts:

• this is an example of shipping page withing integartion
• shopping page is implemented normally but payment is delegated to the external component that is imported from a payment library (checkout-com as example)
• the PaymentProvider component is a feature components that always stick to the criteria (emited events and received prop)
• PaymentProvider has also ability to extend the UI, the developer is able to inject into all of necessary scope of the UI such as single field, multiple field, specific field and also button
• when it comes to emited events - those are responsible for telling the developer what's happening with a payment, we can react on: initializing form, loading payment methods, selecting payment methods etc. - the state is handled inside of the component as developer we only have to react on certain events (that's it)
• PaymentProvider is not fully agnostic: the slot params, input prop, event args etc. can be different and are depending on integation
• some integrations can implement more events if it worth it, but we demand at least these mentioned (convention)

Utilities

• Sometimes, for some reason someone don't want to use that component and wants to implement own one
• To solve that kind of customization we can share the implementation functions that were used inside of PaymentProvider so the developer/client can built it on the own way
• Those utilities are just a simple functions that simplifies the usage of given payment provider. Considering stripe it can be: initForm, selectMethod, loadMethods, makePayment etc.

import { createStripe } from '@vue-storefront/stripe'

const sdk = createStripe({ ... })

sdk.initForm()

const methods = sdk.loadMethods()

const selected = sdk.selectMethod({ method: {} })

const paymentResp = sdk.makePayment()

But based on integration the flow can be different which comes with different functions:

import { createCheckoutCom } from '@vue-storefront/checkout-com'

const sdk = createCheckoutCom({ ... })

const form = sdk.loadForm()

onMouted(() => {
  form.Init();
})

const paymentResp = sdk.makeCardPayment({ cardToken: '' })

const paymentResp = sdk.makeApplePayPayment()

[andrzejewsky]

Meeting nodes:

• one slot instead of scoped (as default)
• emit errors
• initialized -> beforeLoad
• loaded -> afterLoad
• methods:loaded -> methods:beforeLoad, methods:afterLoad
• methods:changed -> methods:selectedDetailsChanged
• PaymentProvider -> VsfPaymentProvider
• VsfShippingProvider -> for future

[filrak]

use enums for event types

[Fifciu]

We will share const like:

const PaymentProviderEvents = {
  BEFORE_PAY: 'payment:beforePay',
  AFTER_PAY: 'payment:afterPay,
  BEFORE_LOAD: 'methods:beforeLoad',
  AFTER_LOAD: 'methods:afterLoad',
  SELECTED: 'methods:selectedDetailsChanged',
  CHANGED: 'methods:selectedDetailsChanged'
}

Then developer will just use

import { PaymentProviderEvents } from '...';

// ...
const onLoaded = () => {
  context.emit(PaymentProviderEvents.LOADED)
}

[Fifciu]

I imagine component will be mounted only after selection:

VsfShippingProviders.vue

<template>
  <div>
    <VsfShippingProvider 
      v-for="shippingProvider in shippingProviders"
    >
      <template #selected>
        <component
          :key="shippingProvider.id"
          :is="shippingProviderToComponentName(shippingProvider)"
          :data="shippingProvider"
          :finished.sync="isShippingFinished"

          :beforeLoad="config => ({...config, overwritenSmth: 12})"
          @afterLoad="afterLoaded"
          @method:selected="afterSelectedMethod"
          @method:selectedDetailsChanged="afterSelectedDetailsChanged"
        />
      </template>
    </VsfShippingProvider>
    <GoToBillingButton :disabled="!isShippingFinished" />
  </div>
</template>

<script>
export default {
  components: shippingProviderComponents,
  setup () {
    const isShippingFinished = ref(false);
    const onChangeShippingProvider = () => {
      isShippingFinished.value = false;
    }

    return {
      isShippingFinished
    }
  }
}
</script>

Each shipping provider:

• view - [Name]ShippingProvider.vue
• logic checker - [Name]ShippingProviderMapper

Hooks:

• Listeners could be done through emit & v-on
• Modifiers has to be sent as props: e.g. initialized method. Otherwise, we won't be able to use what's handler returns.

// shippingProviderToComponentName.ts
import { upsShippingProviderMapper } from 'ups';
// upsShippingProviderMapper = {
//   componentName: 'UpsShippingProvider',
//   checker: (shippingMethod: SHIPPING_METHOD) => Boolean
// }
import { dhlShippingProviderMapper } from 'dhl';
import { pdpShippingProviderMapper } from 'pdp';
import { inpostShippingProviderMapper } from 'inpost';
import { plainShippingProviderMapper } from '@vue-storefront/commercetools';

const providersMappers = [
  upsShippingProviderMapper,
  dhlShippingProviderMapper,
  pdpShippingProviderMapper,
  inpostShippingProviderMapper,
  plainShippingProviderMapper
];

export const shippingProviderComponents = {
  UpsShippingProviderComponent: () => import('ups/component'),
  DhlShippingProviderComponent: () => import('dhl/component'),
  PdpShippingProviderComponent: () => import('pdp/component'),
  InpostShippingProviderComponent: () => import('inpost/component'),
  PlainShippingProviderComponent: () => import('@vue-storefront/commercetools/component'),
};

export const shippingProviderToComponentName = (shippingProvider: SHIPPING_PROVIDER) => {
  const providerMapper = providersMappers.find(providersMapper => providersMapper.checker(shippingProvider));
  if(!providerMapper) {
    throw new Error(`No matching component for ${shippingProvider.name} shipping method`);
  }
  return providerMapper.componentName;
}

[Fifciu]

Simple draft o shippingProvider

<template>
  <ShippingProvider
    :finished.sync="isShippingFinished"
    :methods:beforeLoad="beforeLoad"
    @methods:afterLoad="onAfterLoad"
    @methods:selected="handleSelectMethod"
    @methods:selectedDetailsChanged="handleChangeMethod"
    @error="onError"
  >
    <template #default="{ name, price }">
      Method {{ name }}, price: {{ price }}
    </template>
  </ShippingProvider>
</template>

methods:beforeLoad handler's signature: ()
methods:afterLoad handler's signature: ({ shippingMethods: SHIPPING_METHODS_RESPONSE })
methods:selected handler's signature: ({ shippingMethod: SHIPPING_METHOD })

[bloodf]

This issue has been closed due to inactivity.

If you want to re-open the issue, please re-create the issue, and post newer information on this problem.