Admin

Install @myparcel-pdk/admin with your package manager:

npm install @myparcel-pdk/admin

// <workspace root>/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 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().

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.

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.

  // CustomModal.vue
  <template>
    <div>
      <!-- This will render the button you have defined in your config -->
      <PdkButton>Click me</PdkButton>
    </div>
  </template>
  
  <script lang="ts" setup>
  // no import!
  </script>
  

Then register your component in the components property of createPdkAdmin().

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:

npm install vitest @vue/testing-utils @myparcel-pdk/admin-component-tests

Example

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/<preset>/src/components.

# Optional components

• PdkBadge
• PdkButtonGroup
• PdkPluginSettingsWrapper
• PdkSettingsDivider
• PdkTabNavButtonWrapper
• PdkTabNavContentWrapper
• PdkTableCol
• PdkTableRow

The following components need

• PdkConceptBoxWrapper
• PdkShipmentLabelWrapper

# Default

npm install @myparcel-pdk/admin-preset-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
• DefaultButtonGroup
• DefaultCurrencyInput
• DefaultDropdownButton
• DefaultBox
• DefaultSelectInput
• DefaultModal
• DefaultImage
• DefaultRow
• DefaultTableRow
• DefaultLoader
• DefaultBadge
• DefaultTable
• DefaultCheckboxGroup
• DefaultNotification
• DefaultCol
• DefaultTableCol
• DefaultSettingsDivider
• DefaultTabNavButton
• DefaultCheckboxInput
• DefaultFormGroup
• DefaultTextInput
• DefaultButton
• DefaultMultiSelectInput
• DefaultLink
• DefaultTextArea
• DefaultTimeInput
• DefaultDropOffInput
• DefaultHeading
• DefaultNumberInput
• DefaultToggleInput
• DefaultIcon
• DefaultRadioGroup
• DefaultCodeEditor

# Bootstrap 4

npm install @myparcel-pdk/admin-preset-bootstrap4

This preset is based on Bootstrap 4. The missing components can be taken from the default preset. Bootstrap is not included.

• Bootstrap4Badge
• Bootstrap4Box
• Bootstrap4Button
• Bootstrap4ButtonGroup
• Bootstrap4CheckboxInput
• Bootstrap4Col
• Bootstrap4DropdownButton
• Bootstrap4FormGroup
• Bootstrap4Image
• Bootstrap4Modal
• Bootstrap4Notification
• Bootstrap4RadioInput
• Bootstrap4Row
• Bootstrap4SelectInput
• Bootstrap4Table
• Bootstrap4TextArea
• Bootstrap4TextInput

# Dashicons

npm install @myparcel-pdk/admin-preset-dashicons

This preset contains a PdkIcon replacement for use with Dashicons. Dashicons is not included.

• Dashicon

# Fontawesome

npm install @myparcel-pdk/admin-preset-fontawesome

This preset contains a PdkIcon replacement for use with Fontawesome. Fontawesome is not included.

• FontAwesomeIcon