Best Practices

Adding a shopping cart context to an Elephant site
Bona pràctica
BS.F - BrightSide Financials » Projectes « JavaEE « BrightSide

Lluís Turró Cutiller
Creació
15
juny
2016
Activitat
08
gen.
2018
0 revisio(ns)

BrightSide Financials includes shopping cart and checkout macros. Both will expand in a normal Elephant context and both will read the same shop configuration. Let's see this configuration and macros interactions.

Shopping cart configuration

The shopping cart configuration file is located at WEB-INF/elephant/conf/shop.xml. Here is an example:

<elephant-shop version="1.0">
  <CartPath value="/cart"/>
  <CheckoutPath value="/cart/checkout"/>
  <NotificationPath value="/cart/checkout/"/>
  <OKPath value="/cart/OK"/>
  <KOPath value="/cart/KO"/>
  <Store value=""/>
  <Bank value=""/>
  <Delivery value="Delivery"/>
  <Fiscal value="Fiscal"/>
  <Logistic value=""/>
  <ContactPhone value="Contact phone"/>
  <Locale value="en"/>
  <Currency value="EUR"/>
  <MerchantCode value=""/>
  <MerchantTerminal value=""/>
  <MerchantCurrency value=""/>
  <MerchantKey value=""/>
  <MerchantKeyType value=""/>
  <MerchantKeyLanguage value=""/>
  <MerchantTestScope value="true"/>
  <DeliveryByZipcode value="" product=""/>
</elephant-shop>

Field meaning

  • CartPath, the web path to the shopping cart.
  • CheckoutPath, the web path to checkout.
  • NotificationPath, the web path where POS notifications will be sent. Notice the last slash. In most cases should be included to avoid losing notification parameters.
  • OKPath, the web path where POS will redirect once the payment is completed.
  • KOPath, the web path where POS will redirect when payment is cancelled.
  • Store, the BS Financials contract number where sales will be stored.
  • Bank, the BS Financials contract number where POS payments will be stored.
  • Delivery, the BS Contacts address name for delivery purposes.
  • Fiscal, the BS Contacts address name for billing purposes.
  • Logistic, the email for delivering follow-up logistic messages.
  • ContactPhone, the BS Contacts connector name for phone contacting.
  • Locale, the BS Contacts locale for contract purposes.
  • Currency, the BS Contacts currency for contract purposes.
  • MerchantCode, provided by POS.
  • MerchantTerminal, provided by POS.
  • MerchantCurrency, provided by POS.
  • MerchantKey, provided by POS.
  • MerchantKeyType, provided by POS.
  • MerchantKeyLanguage, provided by POS.
  • MerchantTestScope, true for testing purposes.
  • DeliveryByZipcode, list of zipcodes that, when matching whith delivery address, will add product to the cart on the last step of confirmation.

The shopping cart context

BrightSide Financials products can be added to the shopping cart. To create the shopping cart context, simply create a normal context with the path configured in CartPath. Once created, edit adding this content:

{@cart:[path-to-product-listing]}

Save. That's all. Now all product listings can include the Add to cart button.

Is important to notice that path-to-product-listing isn't forced in configuration file. The reason is you can create as many product listing contexts as you want. They will add to the same shopping cart, no matter where they come from.

The checkout context

In order to send the shopping cart to the POS, you need a checkout context. Checkout context will:

  • Check contact phone.
  • In case some product needs delivery, check delivery address.
  • In case user wants a bill instead of a ticket, check the fiscal address and fiscal identifier.
  • Show user total amounts and taxes and ask for confirmation.
  • Send required data to the POS.
  • Validate payment in a silent and unattended notification.
  • Generate BS Finnacials contract and documents, as necessary.
  • Generate document and delivery follow-up.

Now, create a checkout context with the path configured in CheckoutPath. In most cases, NotificationPath will be exactly the same value with a final slash. If in doubt, follow this guide. Once created, edit and add this content:

{@checkout}

Now you have a checkout context.

The notification URLs

The POS will redirect to OKPath or KOPath, depending on payment success. Create both contexts with according messages.

Few words on above contexts and their content

The shopping cart and the checkout contexts were both created with a single macro as content. That's correct for most cases, since messages are already configured. Because there is a single macro, we don't need wiki syntax thus, the first line deactivate it.

If you feel the user may need more information, you're free to add the macro within more rich content. Avoid mixing both macros in the same context.

Both macros expand to default templates. If you need to modify inside content, simply edit this templates.

Comentaris