From 2b4a6f84a41152f1e9876e45feb77c80aaacf323 Mon Sep 17 00:00:00 2001 From: Edie Lemoine Date: Mon, 19 Jun 2023 15:15:30 +0200 Subject: [PATCH] docs: add pdk docs (#59) --- src/.vuepress/integrations.json | 28 +- src/documentation/52.pdk/10.backend.md | 360 ++++++++++++++++++ .../52.pdk/20.frontend/10.admin.md | 251 ++++++++++++ .../52.pdk/20.frontend/20.checkout.md | 150 ++++++++ .../52.pdk/20.frontend/readme.md | 77 ++++ src/documentation/52.pdk/readme.md | 70 ++++ src/documentation/readme.md | 7 + src/integrations.md | 6 + src/nl/integraties.md | 6 + 9 files changed, 951 insertions(+), 4 deletions(-) create mode 100644 src/documentation/52.pdk/10.backend.md create mode 100644 src/documentation/52.pdk/20.frontend/10.admin.md create mode 100644 src/documentation/52.pdk/20.frontend/20.checkout.md create mode 100644 src/documentation/52.pdk/20.frontend/readme.md create mode 100644 src/documentation/52.pdk/readme.md diff --git a/src/.vuepress/integrations.json b/src/.vuepress/integrations.json index cb84acd1..672939be 100644 --- a/src/.vuepress/integrations.json +++ b/src/.vuepress/integrations.json @@ -207,10 +207,30 @@ "documentation": "https://mijndomein.zendesk.com/hc/nl/sections/13019196364305-MyParcel", "image": "mijndomein.png" }, + { + "name": "php-pdk", + "title": "PHP PDK", + "internal": true, + "type": "pdk", + "repository": "myparcelnl/php-pdk", + "image": "php.svg", + "classes": "bg-goldfish-500 dark:bg-goldfish-700", + "documentation": "/documentation/52.pdk/" + }, + { + "name": "js-pdk", + "title": "JS PDK", + "internal": true, + "type": "pdk", + "repository": "myparcelnl/js-pdk", + "image": "js.svg", + "classes": "bg-goldfish-500 dark:bg-goldfish-700", + "documentation": "/documentation/52.pdk/" + }, { "name": "php-sdk", "internal": true, - "title": "PHP", + "title": "PHP SDK", "type": "sdk", "repository": "myparcelnl/sdk", "documentation": "/documentation/50.php-sdk.html", @@ -220,7 +240,7 @@ { "name": "javascript-sdk", "internal": true, - "title": "JavaScript/Node.js", + "title": "JavaScript/Node.js SDK", "type": "sdk", "repository": "myparcelnl/js-sdk", "documentation": "/documentation/51.javascript-sdk.html", @@ -229,14 +249,14 @@ }, { "name": "c-sharp-sdk", - "title": "C#/.net", + "title": "C#/.net SDK", "type": "sdk", "repository": "janssenr/MyParcelApi.Net", "image": "c-sharp.svg" }, { "name": "ruby-sdk", - "title": "Ruby", + "title": "Ruby SDK", "type": "sdk", "repository": "paypronl/myparcel", "image": "ruby.svg", diff --git a/src/documentation/52.pdk/10.backend.md b/src/documentation/52.pdk/10.backend.md new file mode 100644 index 00000000..f29feea8 --- /dev/null +++ b/src/documentation/52.pdk/10.backend.md @@ -0,0 +1,360 @@ +--- +title: PDK backend (PHP) +description: The PHP PDK is a library that contains all the logic for building a MyParcel plugin. +--- + + + + + + + +The PDK backend is a PHP library that contains all the logic for building a MyParcel plugin. It contains everything from the API communication to the logic for rendering the frontend components. It is built to be framework-agnostic and extremely extensible, so you can implement it in any PHP application. The PDK backend is built on top of [PHP-DI](https://php-di.org/), so it uses [dependency injection](#core-concepts) to make it easy to extend and configure. + +::: tip +The PDK backend is currently only available in PHP, but we intend on creating a Node.js version as well. + +If this is something you would like to use, [please tell us](/contact.md)! This will help us prioritize building it. +::: + +## Prerequisites + +For the backend to work, you need to have the following installed: + +- [PHP](https://www.php.net/) 7.4 or higher +- [Composer](https://getcomposer.org/) + +If you intend on using the frontend, you will also need to have the following installed: + +- [Node](https://nodejs.org/) 16 or higher (Lower versions may work, but this is not tested) + +## Installation + +Install [myparcelnl/pdk] using [Composer]: + +```bash +composer require myparcelnl/pdk +``` + +## Core concepts + +### Terminology + +See [the terminology section](./readme.md#terminology) for a list of generic terms used throughout the PDK and this documentation. + +::: expand h3: Dependency injection + +The PDK backend uses [PHP-DI](https://php-di.org/) for dependency injection. This means that you can use constructor injection to get access to the PDK backend's services. This is done through the [`Pdk`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Pdk.php) Facade. + +To read more about dependency injection, see the [PHP-DI documentation](https://php-di.org/doc/understanding-di.html). + +::: + +::: expand h3: Facades + +Facades are the main way to interact with the PDK. They provide a static interface to the underlying classes, which allows you to use them without having to instantiate them first. This is especially useful for classes that are used in many places, such as the `Logger`. The facades cannot be used until the PDK has been instantiated. + +The following facades are available: + +- [`\MyParcelNL\Pdk\Facade\AccountSettings`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/AccountSettings.php) +- [`\MyParcelNL\Pdk\Facade\Actions`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Actions.php) +- [`\MyParcelNL\Pdk\Facade\Config`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Config.php) +- [`\MyParcelNL\Pdk\Facade\Frontend`] +- [`\MyParcelNL\Pdk\Facade\Installer`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Installer.php) +- [`\MyParcelNL\Pdk\Facade\Language`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Language.php) +- [`\MyParcelNL\Pdk\Facade\Logger`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Logger.php) +- [`\MyParcelNL\Pdk\Facade\Notifications`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Notifications.php) +- [`\MyParcelNL\Pdk\Facade\Pdk`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Pdk.php) +- [`\MyParcelNL\Pdk\Facade\Platform`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Platform.php) +- [`\MyParcelNL\Pdk\Facade\Settings`](https://github.com/myparcelnl/pdk/blob/main/src/Facade/Settings.php) + +Source: [src/Facade](https://github.com/myparcelnl/pdk/blob/main/src/Facade) + +::: + +::: expand h3: Actions + +Actions are the core of all functionality. They are used for all behaviour in the plugin. Actions are divided into three categories: + +**Frontend actions**: Actions that are used in the frontend of your platform. These actions are used to communicate with the PDK backend and are used to render and update the frontend. + +**Backend actions**: Actions that are used in the backend of your platform. These actions are used to communicate with the MyParcel API and are needed for all functionality. + +**Shared actions**: Actions that can be used in both the frontend and backend of your platform. + +#### Backend actions + +| Domain | Action | Description | +| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ | +| Account | `UpdateAccount` | Saves account settings, such as the API key. Then fetches the account details from the API. | +| Orders | `DeleteShipments` | Deletes shipments from the App. | +| Orders | `ExportOrders` | Exports orders to the MyParcel API. Depending on the `mode` setting, exports as shipments or as full orders. | +| Orders | `ExportReturn` | Exports return shipments to the MyParcel API. | +| Orders | `FetchOrders` | Gets latest order data from the PDK. | +| Orders | `PrintOrders` | Prints labels of all shipments in given order(s). | +| Orders | `PrintShipments` | Prints labels of given shipment(s). | +| Orders | `UpdateOrders` | Gets latest order data from the MyParcel API. | +| Orders | `UpdateShipments` | Gets latest shipment data from the MyParcel API. | +| Plugin settings | `UpdatePluginSettings` | Saves plugin settings. | +| Product settings | `UpdateProductSettings` | Saves product settings for given product. | +| Webhooks | `CreateWebhooks` | Creates webhooks for given events. | +| Webhooks | `DeleteWebhooks` | Deletes webhooks for given events. | +| Webhooks | `FetchWebhooks` | Get all registered webhooks from the MyParcel API. | + +Please refer to [the default actions configuration](https://github.com/myparcelnl/pdk/blob/main/config/actions.php) for more information. + +::: + +::: expand h3: Frontend + +Use the [`\MyParcelNL\Pdk\Facade\Frontend`] facade to render the admin frontend. The frontend is divided into components, which can be rendered individually. The following components are available: + +#### Admin: InitScript + +Render the init script component. This component is responsible for initializing the javascript code needed to render the frontend. + +```php +Frontend::renderInitScript(): string +``` + +#### Admin: Modals + +The modals component renders all modals used in the frontend. This includes the settings modal and the order modal. + +```php +Frontend::renderModals(): string +``` + +#### Admin: Notifications + +Render the notifications component. This component is responsible for rendering the notifications reported by other parts of the frontend. + +```php +Frontend::renderNotifications(): string +``` + +#### Admin: OrderBox + +The order box is responsible for rendering detailed MyParcel information for a single order view. It contains a form to edit the delivery options and a table with created shipments. + +```php +Frontend::renderOrderBox(PdkOrder $order): string +``` + +#### Admin: OrderListItem + +The order list item is responsible for rendering MyParcel information for each order in the order list/grid of your app. + +```php +Frontend::renderOrderListItem(PdkOrder $order): string +``` + +#### Admin: PluginSettings + +```php +Frontend::renderPluginSettings(): string +``` + +#### Admin: ProductSettings + +```php +Frontend::renderProductSettings(PdkProduct $product): string +``` + +#### Checkout: DeliveryOptions + +Renders the delivery options component. This component is responsible for rendering the delivery options in the checkout. + +```php +Frontend::renderDeliveryOptions(PdkCart $cart): string +``` + +::: tip +πŸš€ To continue integrating the frontend into your application, continue reading the [PDK frontend documentation]. +::: + +## Implementation + +To use the PDK backend, you first need to instantiate it. This needs to happen before any of the Facades can be used. + +In the following examples, we're building a plugin for WordPress with WooCommerce, so we're prefixing all classes with `Wc`. You should replace this with your own prefix. This makes it easier to distinguish between your own classes and the PDK classes. + +::: tip +πŸ“š For more in-depth examples and to see the whole thing in action, check out our actual [WooCommerce plugin](https://github.com/myparcelnl/woocommerce/tree/alpha), which is built with the PDK. +::: + +### Configuration + +First, you should create a config file. We recommend you copy the [template configuration] and place it in `/config/pdk.php`. This template contains all classes you should extend to implement the PDK in your platform. Make sure to check each interface to see what it does and how to implement it. + +For example, to define your `WcOrderRepository`, create a class that extends `AbstractPdkOrderRepository` and implement all abstract methods: + +```php +use MyParcelNL\Pdk\Plugin\Repository\AbstractPdkOrderRepository; +use MyParcelNL\Pdk\Plugin\Model\PdkOrder; + +class WcOrderRepository extends AbstractPdkOrderRepository +{ + public function get($input): PdkOrder + { + return $this->retrieve((string) $order->id, function () use ($order) { + return new PdkOrder([ + // map your order data to PDK order data + ]); + }); + } +} +``` + +And then reference it in your PDK configuration: + +```php +return [ + // ... + PdkOrderRepositoryInterface::class => autowire(MyPlatformPdkOrderRepository::class), +]; +``` + +Repeat this for all required classes and any other classes you want to implement yourself. Keep in mind you must only extend interfaces, never classes. + +### Creating the bootstrapper + +The `PdkBootstrapper` is responsible for instantiating the PDK. You can extend it to add your own configuration. For example, to add your own configuration to the PDK, you can extend the `getAdditionalConfig` method: + +```php +use MyParcelNL\Pdk\Base\Pdk; +use MyParcelNL\Pdk\Base\PdkBootstrapper; + +namespace MyCompany\MyApp\Pdk\Base; + +class WcPdkBootstrapper extends PdkBootstrapper +{ + protected function getAdditionalConfig( + string $name, + string $title, + string $version, + string $path, + string $url + ): array { + return [ + 'mode' => value(WP_DEBUG ? Pdk::MODE_DEVELOPMENT : Pdk::MODE_PRODUCTION), + 'userAgent' => value([ + // User agents should be sorted from most specific to least specific. + 'MyParcelNL-WooCommerce' => $version, + 'WooCommerce' => defined('WOOCOMMERCE_VERSION') + ? constant('WOOCOMMERCE_VERSION') + : '?', + 'WordPress' => get_bloginfo('version'), + ]), + + // Here you can add any additional config you want to pass to the DI container. + ]; + } +} +``` + +This allows for easy access to the plugin name, title, version, path and URL. You can use this file along with the config file to instantiate the PDK. We recommend you put all interface overrides in the config file and all other configuration in the bootstrapper. + +### Instantiating the PDK + +Now you can call the bootstrapper to instantiate the PDK: + +```php +// /myparcelnl-woocommerce.php + +use MyParcelNL\WooCommerce\Pdk\WcPdkBootstrapper; + +class MyParcelNL { + public function __construct() { + WcPdkBootstrapper::boot( + 'myparcelnl', // Name of the plugin + 'MyParcel', // Title; will be shown in the admin panel + $this->getVersion(), // Plugin version from composer.json + plugin_dir_path(__FILE__), // Plugin path + plugin_dir_url(__FILE__) // Plugin URL + ); + } + // ... +} + +new MyParcelNL(); +``` + +This bootstraps the PDK and is required before you can use any functionality. This will allow you to use all facades and the service container in your own code as well. For example, to use our new `WcOrderRepository` class: + +```php +use MyParcelNL\Pdk\App\Order\Contract\PdkOrderRepositoryInterface; + +/** @var PdkOrderRepositoryInterface $orderRepository */ +$orderRepository = Pdk::get(PdkOrderRepositoryInterface::class); + +$order = $orderRepository->get(1); // PdkOrder +``` + +Or via constructor injection: + +```php +use MyParcelNL\Pdk\App\Order\Contract\PdkOrderRepositoryInterface; + +class MyClass { + private PdkOrderRepositoryInterface $orderRepository; + + public function __construct(PdkOrderRepositoryInterface $orderRepository) { + $this->orderRepository = $orderRepository; + } + // ... +} +``` + +### Setting up the PDK API + +::: note +If you do not intend to use the frontend, you can skip this step. +::: + +The `EndpointActionsInterface` interface has the following methods: + +```php +public function all(): Collection; +public function getBaseUrl(): string; +public function getEndpoints(): Collection; +``` + +When using `PdkEndpointActions`, `all` and `getEndpoints` are already implemented. That means you will only need to implement the `getBaseUrl` method. This method should return a full URL to your endpoint, without a trailing slash. + +For example: + +```php +class MyCustomEndpointActions extends \MyParcelNL\Pdk\Plugin\Action\PdkEndpointActions +{ + public function getBaseUrl(): string + { + return 'https://' . MY_DOMAIN . '/my-myparcel-pdk-endpoint'; + } +} +``` + +Now you need to register this class in your PDK [configuration]: + +```php +// config/pdk.php +return [ + // ... + EndpointActionsInterface::class => autowire(MyCustomEndpointActions::class), +]; +``` + +This allows the PDK to use your custom endpoint for all PDK API calls. Do not forget to implement the endpoint itself. This depends on your platform and is out of scope for this documentation. + +::: note +Note that you should never use the exact class names when injecting dependencies. Always use the interface. +::: + +### Next steps + +Create all required classes and register them in your [PDK configuration](#configuration). You can now use the PDK in your own code. To continue with the frontend part of the application, see the [PDK frontend documentation]. + +[template configuration]: https://github.com/myparcelnl/pdk/blob/main/config/pdk-template.php +[PDK frontend documentation]: 20.frontend/readme.md +[myparcelnl/pdk]: https://packagist.org/packages/myparcelnl/pdk +[`\MyParcelNL\Pdk\Facade\Frontend`]: https://github.com/myparcelnl/pdk/blob/main/src/Facade/Frontend.php diff --git a/src/documentation/52.pdk/20.frontend/10.admin.md b/src/documentation/52.pdk/20.frontend/10.admin.md new file mode 100644 index 00000000..fd1e153b --- /dev/null +++ b/src/documentation/52.pdk/20.frontend/10.admin.md @@ -0,0 +1,251 @@ +--- +title: Admin +description: The PDK frontend admin is a Vue 3 component that can be used in the backend of your platform. It contains all the logic to communicate with the PDK backend and to render the frontend components. +--- + +Install [@myparcel-pdk/admin](https://www.npmjs.com/package/@myparcel-pdk/admin) with your package manager: + + + +```json +// /views/admin/package.json +{ + "name": "@my-scope/admin", + "private": true, + "version": "1.0.0", + "dependencies": { + "@myparcel-pdk/admin": "^1.0.0-alpha.1" + } +} +``` + +## Introduction + +The PDK frontend admin is a Vue 3 component that can be used in the backend of your platform. It contains all the logic to communicate with the PDK backend and to render the frontend components. + +## How it works + +## Components + +The PDK admin comes with a lot of customizable components. You can use these components to build your own custom admin panel. + +### Registering components + +You can replace each defined component with a component of your own, or use the default components provided by the PDK. There are some built-in presets as well: + +- [`@myparcel-pdk/admin-preset-default`] + - Contains every available component. See the [component reference](#component-reference) for a list of all components. +- [`@myparcel-pdk/admin-preset-bootstrap4`] + - Contains components that are styled to match the Bootstrap 4 theme, and a default configuration. +- [`@myparcel-pdk/admin-preset-fontawesome`] + - Contains only a `PdkIcon` +- [`@myparcel-pdk/admin-preset-dashicons`] + - Contains only a `PdkIcon` + +To register components, you need to pass them to the `components` property when calling `createPdkAdmin()`. + +```ts +import {createPdkAdmin} from '@myparcel-pdk/admin'; + +createPdkAdmin({ + // ... + components: { + // Define every component here + }, +}); +``` + +Every component MUST be manually defined. This is for tree-shaking purposes. If you don't have (or want) a custom component for a certain component, you can use the default component provided by [`@myparcel-pdk/admin-preset-default`]. + +```ts +import {createPdkAdmin} from '@myparcel-pdk/admin'; +import {DefaultButton} from '@myparcel-pdk/admin-preset-default'; +import {MyModal} from './components/MyModal'; + +createPdkAdmin({ + // ... + components: { + Button: DefaultButton, + Modal: MyModal, + // All other components + }, +}); +``` + +### Writing custom components + +Keep the following guidelines in mind when writing your own components: + +- Make sure props, emits and slots match the ones defined in the default component. +- When referencing another component, use the `Pdk` prefix rather than importing the component. + + Example: Say you're creating `CustomModal`, and you want to add a button. Instead of importing `CustomButton`, use `PdkButton`. It does not need to be imported. If you're using eslint-plugin-vue, you may want to add an exception for this to avoid linting errors. + + ```vue + // CustomModal.vue + + + + ``` + +Then register your component in the `components` property of `createPdkAdmin()`. + +```ts +import {createPdkAdmin} from '@myparcel-pdk/admin'; +import {CustomButton, CustomModal} from './components'; + +createPdkAdmin({ + // ... + components: { + PdkButton: CustomButton, + PdkModal: CustomModal, + // All other components + }, +}); +``` + +#### Testing custom components + +Your custom components can all be tested against standard tests we have created. This way you can be sure that your components work as expected and contain the minimum functionality for the whole PDK frontend to work. You don't need to pass each component, you should only test the ones you've replaced with your own version. + +To do this, first install the following dependencies: + + + +**Example** + +```ts +import {runCommonComponentTests} from '@myparcel-pdk/admin-component-tests'; + +runCommonComponentTests({ + Accordion: MyPdkAccordion, + Alert: MyPdkAlert, + Button: MyPdkButton, + // Etc... +}); +``` + +### Component reference + +You can view the source code of each component in the [`@myparcel-pdk/admin-preset-default`] package. The pre-built components are located in the [`myparcelnl/js-pdk`] repository, in `apps//src/components`. + +::: tip +For more examples, here are the ones we've created for our own plugins so far: + +- [myparcelnl/woocommerce](https://github.com/myparcelnl/woocommerce/blob/alpha/views/backend/admin/src/components/pdk) +- [myparcelnl/prestashop](https://github.com/myparcelnl/prestashop/blob/alpha/views/js/admin/src/components/pdk) + +::: + +#### Optional components + +- PdkBadge +- PdkButtonGroup +- PdkPluginSettingsWrapper +- PdkSettingsDivider +- PdkTabNavButtonWrapper +- PdkTabNavContentWrapper +- PdkTableCol +- PdkTableRow + +The following components need + +- PdkConceptBoxWrapper +- PdkShipmentLabelWrapper + +#### Default + + + +This preset contains every component. Components have no styling, and are meant to be used as a base for other presets, or to only be used until you've created your own components. + +- [DefaultRadioInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultBadge.vue) +- [DefaultButtonGroup](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultBox.vue) +- [DefaultCurrencyInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultButton.vue) +- [DefaultDropdownButton](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultButtonGroup.vue) +- [DefaultBox](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultCheckboxGroup.vue) +- [DefaultSelectInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultCheckboxInput.vue) +- [DefaultModal](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultCodeEditor.vue) +- [DefaultImage](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultCol.vue) +- [DefaultRow](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultCurrencyInput.vue) +- [DefaultTableRow](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultDropOffInput.vue) +- [DefaultLoader](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultDropdownButton.vue) +- [DefaultBadge](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultFormGroup.vue) +- [DefaultTable](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultHeading.vue) +- [DefaultCheckboxGroup](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultIcon.vue) +- [DefaultNotification](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultImage.vue) +- [DefaultCol](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultLink.vue) +- [DefaultTableCol](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultLoader.vue) +- [DefaultSettingsDivider](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultModal.vue) +- [DefaultTabNavButton](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultMultiSelectInput.vue) +- [DefaultCheckboxInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultNotification.vue) +- [DefaultFormGroup](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultNumberInput.vue) +- [DefaultTextInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultRadioGroup.vue) +- [DefaultButton](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultRadioInput.vue) +- [DefaultMultiSelectInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultRow.vue) +- [DefaultLink](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultSelectInput.vue) +- [DefaultTextArea](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultSettingsDivider.vue) +- [DefaultTimeInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTabNavButton.vue) +- [DefaultDropOffInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTable.vue) +- [DefaultHeading](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTableCol.vue) +- [DefaultNumberInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTableRow.vue) +- [DefaultToggleInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTextArea.vue) +- [DefaultIcon](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTextInput.vue) +- [DefaultRadioGroup](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultTimeInput.vue) +- [DefaultCodeEditor](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-default/src/components/DefaultToggleInput.vue) + +#### Bootstrap 4 + + + +This preset is based on Bootstrap 4. The missing components can be taken from the default preset. Bootstrap is not included. + +- [Bootstrap4Badge](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Badge.vue) +- [Bootstrap4Box](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Box.vue) +- [Bootstrap4Button](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Button.vue) +- [Bootstrap4ButtonGroup](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4ButtonGroup.vue) +- [Bootstrap4CheckboxInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4CheckboxInput.vue) +- [Bootstrap4Col](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Col.vue) +- [Bootstrap4DropdownButton](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4DropdownButton.vue) +- [Bootstrap4FormGroup](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4FormGroup.vue) +- [Bootstrap4Image](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Image.vue) +- [Bootstrap4Modal](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Modal.vue) +- [Bootstrap4Notification](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Notification.vue) +- [Bootstrap4RadioInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4RadioInput.vue) +- [Bootstrap4Row](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Row.vue) +- [Bootstrap4SelectInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4SelectInput.vue) +- [Bootstrap4Table](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4Table.vue) +- [Bootstrap4TextArea](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4TextArea.vue) +- [Bootstrap4TextInput](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-bootstrap4/src/components/Bootstrap4TextInput.vue) + +#### Dashicons + + + +This preset contains a PdkIcon replacement for use with Dashicons. Dashicons is not included. + +- [Dashicon](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-dashicons/src/components/DashIconsIcon.vue) + +#### Fontawesome + + + +This preset contains a PdkIcon replacement for use with Fontawesome. Fontawesome is not included. + +- [FontAwesomeIcon](https://github.com/myparcelnl/js-pdk/blob/alpha/apps/admin-preset-fontawesome/src/components/FontAwesomeIcon.vue) + +[`@myparcel-pdk/admin-preset-default`]: https://npmjs.com/package/@myparcel-pdk/admin-preset-default +[`@myparcel-pdk/admin-preset-bootstrap4`]: https://npmjs.com/package/@myparcel-pdk/admin-preset-bootstrap4 +[`@myparcel-pdk/admin-preset-fontawesome`]: https://npmjs.com/package/@myparcel-pdk/admin-preset-fontawesome +[`@myparcel-pdk/admin-preset-dashicons`]: https://npmjs.com/package/@myparcel-pdk/admin-preset-dashicons +[@myparcel-pdk/admin]: https://npmjs.com/package/@myparcel-pdk/admin +[@myparcel-pdk/admin-component-tests]: https://npmjs.com/package/@myparcel-pdk/admin-component-tests +[`variant`]: #variant +[`myparcelnl/js-pdk`]: https://github.com/myparcelnl/js-pdk diff --git a/src/documentation/52.pdk/20.frontend/20.checkout.md b/src/documentation/52.pdk/20.frontend/20.checkout.md new file mode 100644 index 00000000..9e8a51fa --- /dev/null +++ b/src/documentation/52.pdk/20.frontend/20.checkout.md @@ -0,0 +1,150 @@ +--- +title: Checkout +description: The checkout modules of the MyParcel js-pdk are used to render the checkout components and functionality in your application. +--- + +The checkout modules of the MyParcel js-pdk are used to render the checkout components and functionality in your application. The checkout module of the js-pdk consists of four parts: + +- [checkout-core](#checkout-core) +- [checkout-delivery-options](#delivery-options) +- [checkout-separate-address-fields](#separate-address-fields) +- [checkout-tax-fields](#tax-fields) + +## Project structure + +### Checkout core + +The checkout core is needed for all other checkout functionality. It contains the logic to communicate with the PDK backend and to determine which fields are used. + +::: tip +Required for all other checkout functionality. +::: + + + +```json +// /views/checkout-core/package.json +{ + "name": "@my-scope/checkout-core", + "private": true, + "version": "1.0.0", + "dependencies": { + "@myparcel-pdk/checkout": "^1.0.0-alpha.1" + } +} +``` + +In `src/main.ts`, you can import the `checkout-core` module and use it in your application: + +```ts +import {createPdkCheckout} from '@myparcel-pdk/checkout'; + +createPdkCheckout({ + // configuration +}); +``` + +See the [PdkCheckoutConfig](https://github.com/myparcelnl/js-pdk/blob/alpha/libs/frontend/checkout-core/src/types.ts#L51) type for all available configuration options. + +### Delivery options + +The Delivery Options module is used to render the delivery options in your checkout. It uses [@myparcel/delivery-options](https://github.com/myparcelnl/delivery-options) to render the delivery options and communicates with the PDK backend. + +::: tip +Optional: Not required if you want to use the checkout functionality without delivery options. +::: + +```json +// /views/checkout-delivery-options/package.json +{ + "name": "@my-scope/checkout-delivery-options", + "private": true, + "version": "1.0.0", + "dependencies": { + "@myparcel-pdk/checkout": "^1.0.0-alpha.1" + } +} +``` + +Initialize the checkout delivery options module: + +```ts +// src/main.ts +import { + initializeCheckoutDeliveryOptions, + usePdkCheckout, +} from '@myparcel-pdk/checkout'; + +usePdkCheckout().onInitialize(initializeCheckoutDeliveryOptions); +``` + +### Separate address fields + +If you want to support our separate address fields, you need to set up this module. It contains logic to support the following fields: + +- `street` +- `number` +- `number_suffix` + +::: tip +Optional: Not required if you want to use the checkout functionality without separate address fields. +::: + +```json +// /views/checkout-separate-address-fields/package.json +{ + "name": "@my-scope/checkout-separate-address-fields", + "private": true, + "version": "1.0.0", + "dependencies": { + "@myparcel-pdk/checkout": "^1.0.0-alpha.1" + } +} +``` + +Initialize the checkout separate address fields module: + +```ts +// src/main.ts +import { + initializeCheckoutSeparateAddressFields, + usePdkCheckout, +} from '@myparcel-pdk/checkout'; + +usePdkCheckout().onInitialize(initializeCheckoutSeparateAddressFields); +``` + +### Tax fields + +The tax fields are two additional fields that can be used to collect the tax number of the customer. It contains logic to support the following fields: + +- `vat_number` +- `eori_number` + +::: tip +Optional: Not required if you want to use the checkout functionality without tax fields. +::: + +```json +// /views/checkout-tax-fields/package.json +{ + "name": "@my-scope/checkout-tax-fields", + "private": true, + "version": "1.0.0", + "dependencies": { + "@myparcel-pdk/checkout": "^1.0.0-alpha.1" + } +} +``` + +Initialize the checkout tax fields module: + +```ts +// src/main.ts +import { + initializeCheckoutTaxFields, + usePdkCheckout, +} from '@myparcel-pdk/checkout'; + +usePdkCheckout().onInitialize(initializeCheckoutTaxFields); +``` diff --git a/src/documentation/52.pdk/20.frontend/readme.md b/src/documentation/52.pdk/20.frontend/readme.md new file mode 100644 index 00000000..c95a1a63 --- /dev/null +++ b/src/documentation/52.pdk/20.frontend/readme.md @@ -0,0 +1,77 @@ +--- +title: PDK Frontend +description: The frontend part of the PDK uses Vue.js 3 and provides certain components you can render in your application. It supports custom components, so you can style everything yourself. +--- + + + + + + + +The frontend part of the PDK uses Vue.js 3 and provides certain components you can render in your application. It supports custom components, so you can style everything yourself. + +### Prerequisites + +- Node.js 18 or higher (May work on lower versions, but not tested) +- Vue.js 3 or higher +- TypeScript 4.5 or higher + +## Project structure + +The PDK frontend works best in a [Yarn 2](https://yarnpkg.com/) workspace. Example workspace structure: + +``` +. +β”œβ”€β”€ package.json +└── views + β”œβ”€β”€ admin + β”‚ └── package.json + β”œβ”€β”€ checkout-core + β”‚ └── package.json + β”œβ”€β”€ checkout-delivery-options + β”‚ └── package.json + β”œβ”€β”€ checkout-separate-address-fields + β”‚ └── package.json + └── checkout-tax-fields + └── package.json +``` + +With this being the root `package.json`: + +```json +{ + "name": "@my-scope/monorepo", + "private": true, + "workspaces": ["views/*"] +} +``` + +### Admin + +The admin is the main component of the JS PDK. It contains all the logic to communicate with the PDK backend and to render components in your app's backend. + +It uses the following libraries: + +- vue^3 +- pinia +- @vueuse/core +- @tanstack/vue-query + + + +### Checkout + +The checkout part of the JS PDK is split up into multiple packages. This allows you to only use the parts you need and minimize bundle size. Only the delivery options component uses external libraries. The other components are written in pure JavaScript (TypeScript). + + diff --git a/src/documentation/52.pdk/readme.md b/src/documentation/52.pdk/readme.md new file mode 100644 index 00000000..869a8d4e --- /dev/null +++ b/src/documentation/52.pdk/readme.md @@ -0,0 +1,70 @@ +--- +title: Plugin Development Kit (PDK) +description: The MyParcel Plugin Development Kit (PDK) is a set of tools to quickly build a MyParcel plugin for your e-commerce platform. +--- + +The MyParcel Plugin Development Kit (PDK) is a set of tools to quickly build a MyParcel plugin for your e-commerce platform. The backend is written in PHP and the frontend is written in JavaScript. + +## Features + +- Easy to use API +- Feature equality between all implementations +- Automated building using a configuration file +- Easily configurable +- Extensible: If the default implementation does not fit your needs, you can modify it + +## Terminology + +The following terms are used throughout the documentation: + +| Term | Description | +| -------------: | :----------------------------------------------------------------------------------------------- | +| _App_ | Your implementation of the PDK. This is your plugin, app, module or extension that uses the PDK. | +| _PDK backend_ | The PDK backend is the part of the PDK that is written in PHP. | +| _PDK frontend_ | The PDK frontend is the part of the PDK that is written in JavaScript. | +| _Admin_ | The admin is the admin panel, dashboard or backend of your app. | +| _Checkout_ | The checkout is the checkout page of your app. | + +## Getting started + +To get started with the PDK, you need to set up the backend and (optionally) the frontend. The backend is required for all other PDK functionality. The frontend is only required if you want to use custom checkout functionality. + + + + + + +## Examples + +The PDK is used in the following plugins: + +- [MyParcel WooCommerce](https://github.com/myparcelnl/woocommerce/tree/alpha) (currently in alpha) +- [MyParcel PrestaShop](https://github.com/myparcelnl/prestashop/tree/alpha) (currently in pre-alpha) + +## FAQ + +::: expand h3: Why use the PDK over an SDK? +The PDK is a central codebase that contains all logic to scaffold a MyParcel plug-in. It uses our SDKs under the hood, but contains a lot of additional logic to make it easier to build a plugin. + +The PDK is not a replacement for our SDKs. It is a tool to make it easier to build a plugin. +::: + +## Contributing + +We welcome contributions to the PDK. Please read our [developer guide](https://github.com/myparcelnl/developer/blob/main/DEVELOPERS.md) to get started. + +## License + +The MyParcel PDK is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). + +## Security + +If you discover a security vulnerability within the PDK, please let us know via our [contact form](/contact.md). diff --git a/src/documentation/readme.md b/src/documentation/readme.md index a2c66086..57d2dda1 100755 --- a/src/documentation/readme.md +++ b/src/documentation/readme.md @@ -28,6 +28,13 @@ Here you can find our documentation for various plugins and our own SDKs. +## PDK (Plugin Development Kit) + + + + + + ## Other integrations diff --git a/src/integrations.md b/src/integrations.md index 22cffcd3..52c20a96 100644 --- a/src/integrations.md +++ b/src/integrations.md @@ -23,6 +23,12 @@ that comes with manually developing an API integration. +### Plug-in Development Kit (PDK) + +The [MyParcel PDK](/documentation/52.pdk/) is how we develop our own plug-ins. The PDK provides a lot of the boilerplate code needed to create a plug-in and allows us to focus on the integration itself. + + + ## API integrations These integrations can be installed and configured in our Backoffice and diff --git a/src/nl/integraties.md b/src/nl/integraties.md index 14948b1b..43da1416 100644 --- a/src/nl/integraties.md +++ b/src/nl/integraties.md @@ -23,6 +23,12 @@ te slaan dat komt kijken bij het handmatig ontwikkelen van een API-integratie. +### Plug-in Development Kit (PDK) + +De [MyParcel PDK](/documentation/52.pdk/) is hoe we onze eigen plug-ins ontwikkelen. De PDK biedt veel van de boilerplate code die nodig is om een plug-in te maken en stelt ons in staat om ons te concentreren op de integratie zelf. + + + ## API integrations Deze integraties kunnen in onze Backoffice worden geΓ―nstalleerd en