Categories

Shipping Plugin

1 Introduction

This document is a guide for developers to the shipping plugins of GrandNode.

Before you start reading this, I advise to look upon ShippingPoint Plugin and notice yourself major differences in plugin structure before I explicitly figure them out beneath.

The easiest/fastest way to make new Shipping Plugin, is to get already working ShippingPoint Plugin, and modify some parts* of it (that need to be changed in order to get target effect).

Besides Controller, the rest of classes inside plugin is pretty typical for plugins, so you should focus only on Controller and its Views.

2 The Admin Part

You can make Shipping Plugin by inheriting BasePluginController.

step1

The main change is here. All shipping plugins will need implement

step2

Controller will implement basic CRUD operations and custom Actions and Methods depending on your logic.

I hope  below picture will make Controller structure more clear.

step3

The first place where you should start writing your own code is admin configuration panel and GET Configure() Action Method.

step4

Configure() can return one prepared ViewModel or, if you have many shipping options – a List<SelectListItem> for DropDownList.

In this case (many shipping options), Configure() returns Confiugre.cshtm

step5

And then, inside Configure.cshtml, a script (kendo grid) calls the Controller.List() which renders table

step6

The GUI effect, rendered table

step7

3 The User Part

Checkout: 3 section

After installation and enabling plugin, in 3. Shipping Method section will appear new Shipping Method

GetFormPartialView() can return one or more shipping options and FormComboBox.cshtml (you can name it Form.cshtml If there is no DropDownList but only one Shipping Option)

step8

The effect

step9

In this case GetFormPartialView returns List<SelectListItem> and options are rendered inside <select> html tag. Any change in selection will fire function renderShippingOptionInfo()

step10

That will fire ajax request for GetShippingOptionPartialView() that will return one shipping option with matching id

RenderPartialViewToString makes it easy to render model of any type without having to explicitly declare Action’s return type (just declare generic JsonResult)

step11

It is worth to notice, that many essential for user information (look at price) are assigned inside GetShippingOptionPartialView()

step12

Shipping Option will be displayed in simple manner (only provide basic information)

step13

The  GUI effect

step14

You may notice that GetShippingOptionPartialView() isn’t declared in BaseShippingController, because plugins may vary – some plugin can have only one Shipping Option, other will have plenty of them.

It doesn’t make sense to impose many-shipping-options structure.

To clarify it

  •                 one Shipping Option - use only GetFormPartialView() and return directly requested Shipping Option
  •                 many Shipping Options - additionally GetShippingOptionPartialView

GetFormPartialView and ValidateShippingForm are a necessity.

GetShippingOptionPartialView is helpful when you have many Shipping Options.

 

Checkout: 3 section continue

step15

After submit, the OpcSaveShippingMethod() will be called

step16

The vital piece in CheckoutController.cs is here

step17

ValidateShippingForm() is important method that makes this mechanism work (saving values to database)

step18

‘warnings’ is a collection that contains warning messages – one warning will block plugin’s code from executing

step19

Id is equal to 0? Let’s tell customer that he needs to choose any Shipping Option (it will be displayed to endcustomer)

step20

If collection count is equal to 0, there is nothing wrong with input and Checkout can proceed further

step21

Now, customer’s GenericAttributes needs to be assigned with new values

  •                 SystemCustomerAttributeNames.OfferedShippingOptions,                                  //only if there is more than 1 shipping option
  •                 SystemCustomerAttributeNames.ShippingOptionAttributeDescription,                 //value: customer friendly html string
  •                 SystemCustomerAttributeNames.ShippingOptionAttributeXml,                             //value: serialized xml

 

If you have more than one shipping option, then OfferedShippingOptions attribute has to be overridden with small change – you need to override your Shipping Method inside OfferedShippingOptions (yes, name inconsistency) with new price of chosenShippingOption.PickupFee

step22

Checkout: 6 section

In 6. Confirm Order information about shipping should be visible and valid for enduser

step23

step24

4 Appendix

*mentioned parts:
ShippingController

  •                                GET Configure()
  •                                POST Configure()                                       //optional, if you have one shipping option
  •                                POST List()                                                 //kendo grid, many shipping options
  •                                CRUD Actions
  •                                GetFormPartialView()                                  //get directly one or indirectly many shipping options
  •                                GetShippingOptionPartialView()                  //when you have more than 1 shipping option
  •                                ValidateShippingForm()                               //validate and then assign Customer.GenericAttribute

In case of many shipping options, View folder can look like this

step25

 

back to top