Skip to content

Commit

Permalink
docs(delivery-options): update delivery options documentation (#72)
Browse files Browse the repository at this point in the history
  • Loading branch information
@EdieLemoine
EdieLemoine authored Aug 31, 2023
1 parent 12c65bb commit c151acf
Showing 1 changed file with 133 additions and 76 deletions.
209 changes: 133 additions & 76 deletions src/documentation/60.delivery-options.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,42 +9,93 @@ title: Delivery Options
<GitHubShield repo="myparcelnl/delivery-options" link="pulls" />
</Stack>

This is the MyParcel delivery options module for use in any e-commerce
platform's checkout, by <DataType type="platform" name="myparcel" />
, <DataType type="platform" name="belgie" />
and <DataType type="platform" name="flespakket" /> customers. It's used to show
your customers the possible delivery and/or pickup options for their location,
based on your settings. It only has the bare minimum css styling, so it should
integrate with the design of your webshop easily.
This is the MyParcel delivery options module for use in any e-commerce platform's checkout, by <DataType type="platform" name="myparcel" /> , <DataType type="platform" name="belgie" /> and <DataType type="platform" name="flespakket" /> customers. It's used to show your customers the possible delivery and/or pickup options for their location, based on your settings. It only has the bare minimum css styling, so it should integrate with the design of your webshop easily.

## Browser support
## Sandbox

This app runs on [Vue.js](https://vuejs.org/) 2.6.14, it supports IE9 and up.
An example of the delivery options functionality can be found in our [sandbox](https://myparcelnl.github.io/delivery-options/). Here you can try out every combination of settings and copy the code for use in your project.

## Sandbox
## Demo

An example of the delivery options functionality can be found in
our [sandbox](https://myparcelnl.github.io/delivery-options/). Here you can try
out every combination of settings and copy the code for use in your project.
We've made a tiny [vanilla js demo on Codesandbox](https://codesandbox.io/s/myparcel-delivery-options-demo-plain-js-m7vzlk) which you can use to see how the delivery options work in a simple environment.

## Installation

### Dependencies

We recommend using a CDN to load Vue.js 2.6 and the delivery options. If you're using a package manager, you can also install it locally.

#### CDN

```html
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script src="https://unpkg.com/@myparcel/delivery-options@^5/dist/myparcel.lib.js"></script>
```

#### Package manager

Install [@myparcel/delivery-options] with your package manager:

<InstallNode package="@myparcel/delivery-options" />

If Vue.js 2.6 is already loaded in your page, you can import the delivery options without Vue.js included:

```js
import '@myparcel/delivery-options/dist/myparcel.lib.js';
```

Otherwise, use the following import to load Vue.js and the delivery options:

```js
import '@myparcel/delivery-options';
```

::: note
Vue.js 2.7 and 3 are currently **not** supported.
:::

### Usage

1. Is [Vue.js](https://vuejs.org/) ^2.6.0 present on the page you want to use the Delivery Options on?
- Yes: Include `dist/myparcel.lib.js`.
- No: Include `dist/myparcel.js`.
1. Include Vue.js 2.6 and the delivery options in your page (see [Dependencies]).
2. Place `<div id="myparcel-delivery-options"></div>` in your HTML.
3. Trigger the following event:
3. Provide a configuration via a `CustomEvent`:

```js
document.dispatchEvent(new Event('myparcel_update_delivery_options'));
document.dispatchEvent(
new CustomEvent('myparcel_update_delivery_options', {
detail: {
config: {
platform: 'myparcel',
carrierSettings: {
postnl: {
allowDeliveryOptions: true,
},
},
},
address: {
cc: 'NL',
city: 'Hoofddorp',
postalCode: '2132JE',
street: 'Antareslaan 31',
},
},
}),
);
```

> This is the most minimal configuration. For the delivery options to work:
>
> - `config.platform` must be set to `'myparcel'` or `'belgie'`.
> - At least one carrier must be present in `config.carrierSettings` which:
> - Has either delivery options or pickup locations enabled (`allowDeliveryOptions` or `allowPickupLocations`)
> - Is available in the current platform (`config.platform`)
> - Is available in the current country (`address.cc`)
> - `address` must be set to an object with the following properties:
> - `cc` (country code)
> - `city`
> - `postalCode`
> - `street`
4. The delivery options will be rendered inside the div you created before.

::: tip
Expand All @@ -54,7 +105,8 @@ Check out the [available options] and [usage examples] for further configuration
## Available options

```js
window.MyParcelConfig = {
/** @type {import('@myparcel/delivery-options').MyParcelDeliveryOptions.Config} */
const config = {
config: {
platform: 'belgie',

Expand Down Expand Up @@ -129,6 +181,7 @@ window.MyParcelConfig = {
cc: 'BE',
city: 'Antwerpen',
postalCode: '2000',
street: 'Adriaan Brouwerstraat 16',
},
};
```
Expand All @@ -152,97 +205,100 @@ const obj = JSON.parse(data);

## Usage Examples

These examples assume you've already loaded the delivery options in your page. See [Installation] if you haven't. You have to provide a configuration file in the following format as `window.MyParcelConfig` and initialize the delivery options with an event.
These examples assume you've already loaded the delivery options in your page. See [Installation] if you haven't. You have to provide a configuration via sending a `CustomEvent`.

### Setting up the configuration

This is an example.

```js
window.MyParcelConfig = {
/** @type {import('@myparcel/delivery-options').MyParcelDeliveryOptions.Config} */
const config = {
config: {
platform: 'belgie', // REQUIRED!
platform: 'myparcel', // REQUIRED!
// platform: 'belgie', // For MyParcel BE. Note the platform affects which carriers are available.
carrierSettings: {
bpost: {
postnl: {
allowDeliveryOptions: true,
allowPickupLocations: true,
},
dpd: {
dhlforyou: {
allowDeliveryOptions: true,
allowPickupLocations: true,
},
},
},
address: {
cc: 'BE',
city: 'Antwerpen',
postalCode: '2000',
cc: 'NL',
city: 'Hoofddorp',
postalCode: '2132JE',
street: 'Antareslaan 31',
},
};

// Trigger this event on the document to tell the delivery options to update.
// Usually only needed on initializing and when the address changes.
document.dispatchEvent(new Event('myparcel_update_delivery_options'));
// Only needed on initializing and when the address changes.
document.dispatchEvent(
new CustomEvent('myparcel_update_delivery_options', {detail: config}),
);
```

### Getting the address from your environment

1. Set up the link between the address fields and the delivery options:
Set up the link between the address fields and the delivery options:

```js
/**
* Get data from form fields and put it in the global MyParcelConfig.
*/
function updateAddress() {
window.MyParcelConfig.address = {
cc: document.querySelector('#country').value,
postalCode: document.querySelector('#house_number').value,
number: document.querySelector('#postcode').value,
city: document.querySelector('#address_1').value,
};

/*
* Send the event that tells the delivery options module to reload data.
*/
document.dispatchEvent(new Event('myparcel_update_delivery_options'));

// IE9–11 compatible example
var event = document.createEvent('HTMLEvents');
event.initEvent('myparcel_update_delivery_options', true, false);
document.querySelector('body').dispatchEvent(event);
}
```
```js
const countryField = '<Country field selector>';
const cityField = '<City field selector>';
const postalCodeField = '<Postal code field selector>';
const addressLine1Field = '<Address line 1 field selector>';

/**
* Sends the event with the new address to the delivery options.
*
* @note `myparcel_update_delivery_options` can't update the config. Use `myparcel_update_config` for that.
*/
function updateAddress(myAddress) {
// Get the address parts from your fields.
const countryCode = document.querySelector(countryField).value;
const city = document.querySelector(cityField).value;
const postalCode = document.querySelector(postalCodeField).value;
const addressLine1 = document.querySelector(addressLine1Field).value;

document.dispatchEvent(
new CustomEvent('myparcel_update_delivery_options', {
detail: {
address: {
cc: countryCode,
city: city,
postalCode: postalCode,
street: addressLine1,
},
},
}),
);
}

2. Add event listeners to each address field to execute this function:
// Listen to changes in the fields and update the delivery options when they change.
const addressFields = [countryField, postalCodeField, addressLine1Field];

```js
// ES6 example, use var for older environments.
const addressFields = [
'<Country field selector>',
'<Postal code field selector>',
'<Address line 1 field selector>',
];

addressFields.forEach((field) => {
document.querySelector(field).addEventListener('change', updateAddress);
});
```
addressFields.forEach((field) => {
document.querySelector(field).addEventListener('change', updateAddress);
});
```

3. Now, when a user changes the value in any of the fields set in `addressFields` the `window.MyParcelConfig` will be updated and the delivery options module will receive the event that tells it to update. The delivery options will reload and fetch the available options for the new address.
Now, when a user changes the value in any of the fields set in `addressFields` the delivery options module will receive the new address. The delivery options will reload and fetch the available options for the new address.

### Usage in forms

You'll often want to use the delivery options module in a checkout form in your webshop software. Below are some things to keep in mind, but if you're interested in doing this you should check out our Magento2 and WooCommerce plugins locally and read through these implementations. You can find the best files to get started with in [Integration examples]. We also recommend you join our [Slack] support channel to get (fast!) answers to any questions you might have.

1. Follow the steps in [Installation] and copy `myparcel.js` (Vue included)
or `myparcel.lib.js` (Vue not included)
from `node_modules/@myparcel/delivery-options/dist` to your js folder.
1. Follow the steps in [Installation]
2. The things you'll need to do :

- Have either a `window.MyParcelConfig` or dispatch a `CustomEvent` with the settings you want in the page where you're loading the delivery options.
- Send events to the delivery options telling it when to update or rerender.
- Listen to the delivery options' events to update your application according to the changes.
- Attach the output data to the order that is being created.
- Dispatch a `CustomEvent` with the settings you want in the page where you're loading the delivery options.
- Send events to the delivery options telling it when to update or rerender.
- Listen to the delivery options' events to update your application according to the changes.
- Attach the output data to the order that is being created.

### Allowing or disallowing settings for specific countries

Expand All @@ -251,7 +307,8 @@ Let's say you want to disallow delivery to the Netherlands, only allow pickup in
The configuration would look like this:

```js
window.MyParcelConfig = {
/** @type {import('@myparcel/delivery-options').MyParcelDeliveryOptions.Config} */
const config = {
config: {
platform: 'belgie',
carrierSettings: {
Expand Down

0 comments on commit c151acf

Please sign in to comment.