Is this article helpful?
 
(optional) let us know why:

Introducing the plentymarkets plugin interface

The plentymarkets plugin interface is a collection of interfaces representing the modules and sub-modules available in plentymarkets. The plugin interface defines the core services for plentymarkets plugins and contains all necessary methods for your plugin to communicate with plentymarkets. For each module of plentymarkets, individual interfaces are available. The documentation for these interfaces can be accessed via the Interface drop-down menu in the navigation bar. Learn how to integrate the plentymarkets plugin interface into your IDE to support auto-completion.

Overview of interfaces

Find an overview of all available interfaces below:

Interface Description
Account Contains sub-modules for Addresses and Contacts. This interface is the counterpart to the plentymarkets CRM module.
Accounting Contains a sub-module for VAT and classes for determining the VAT.
Authentication Interface for user authentication.
Authorization Interface for user permissions and user roles.
Basket Contains sub-modules for determining the basket and the items within the basket.
Category Interface with sub-modules and models for categories.
Cloud Interface for cloud services, e.g. ElasticSearch and Storage.
Cron Interface for accessing cron jobs.
Comment Contains the Comment model.
DataExchange Interface for exchanging data. Contains models for export and filters.
Document Contains the document model.
EventProcedures Interface with events and services for event procedures.
Export Contains the Export model.
Frontend Interface with services for the online store.
Helper Interface with contracts, models and services for helpers.
Item Contains sub-modules for attributes, availability, item and variation data, manufacturers, shipping and units.
ItemSet Interface for item sets. Contains methods to get and create item sets and item set components.
Market Contains the sub-module Ebay for fitments and fitment items.
Order Contains contracts and models for orders and order items as well as the sub-modules Currency, Payment and Shipping. This interface is the counterpart to the plentymarkets order module.
Payment Contains the sub-modules for payment methods, the payment history, as well as contracts and models for payments and payment properties.
Plugin Contains the sub-modules for storing data in a plugin database or accessing external SDKs.
StockManagement Contains contracts and models for stock management and storage data.
System Contains the Webstore model.
Template Contains contracts and models for the design and design configuration.
Ticket Contains contracts and models related to the plentymarkets ticket system.
Miscellaneous Contains interfaces that cannot be organised in the listed interfaces.

Plugin structure

All plugins need to be organised in a specific structure.

Make sure that you use these folder names for your plugin to avoid unpredicted behaviour!
PluginDirectory/
    ├── meta/
    │   ├── images/
    │   │   │   // preview images showing this plugin
    │   │   ├── preview_[0-6].[png │ jpeg]
    │   │   │   // plugin icons
    │   │   ├── icon_plugin_[xs │ sm │ md].[png │ jpeg]
    │   │   │   // authors logo
    │   │   └── icon_author_[xs │ sm │ md].[png │ jpeg]
    │   └── documents/
    │       └── user_guide_[en │ de │ etc].md // user guide for the plugin
    │
    ├── resources/
    │   ├── css/
    │   │   └── // .css and .scss files
    │   ├── images/
    │   │   └── // images
    │   ├── js/
    │   │   └── // JavaScript and CoffeeScript
    │   ├── lang/
    │   │   └── // language files
    │   ├── documents/
    │   │   └── // fonts, pdf-files or other resources
    │   └── views/
    │       └── // twig templates (can be organised in sub-folders)
    │
    ├── src/
    │   └── // plugin source code
    │
    ├── tests/
    │   └── // tests will be executed before build
    │
    ├── ui/
    │   └── // files for back end views
    │
    ├── config.json // admin's plugin options
    ├── plugin.json // plugin information
    ├── ui.json // back end menu information
    ├── README.md
    └── CHANGELOG.md // change log for the plugin

For detailed information about the different plugin features, refer to the Template plugin guide or Payment plugin guide.

For detailed information on writing tests, refer to the PHPUnit documentation. To compose a test suite for a plugin, use the tests/ folder. When uploading a plugin to a Git repository, the test folder will be included, making your quality assurance process more transparent.

Plugin information

All information about your plugin is defined in a plugin.json file. This file defines the service provider of your plugin, which will be called by plentymarkets to register and run your plugin. For more information, see this page.

Plugin configuration

You can define multiple options that will be displayed in the Plugins » Plugin overview menu to be configured by users. The value of each option can be accessed in your PHP code by using the ConfigRepository or from Twig templates by using the config() macro. For more information about the plugin configuration, see this page.

Multilingualism

You can enter translations for the configuration file both with the old and the new structure. The properties label, caption and tooltip of an entry can be translated. Note: Every translation key must feature the prefix Config.. For more information about multilingualism, see this page.

Back end menu information

All information about the back end menu entries is saved in a ui.json file. This file defines the entry points for the plugin. Views are then available at the respective menus. Find a list of possible menu entry points below.

PluginXY/ui.json
{
    "defaultEntryPoint" : "index.html",
    "namespace"         : "MyFirstView",
    "icon": "icon-plugin",
    "menuEntries"       : [
                            {
                              "label": "Hello World",
                              "menu": "start",
                              "urlKey": "hello-world",
                              "entryPoint": "index.html",
                              "icon": "icon-add"
                            }
                          ]
}
Property Description
defaultEntryPoint The default entry point of your plugin
namespace The namespace of your plugin
menuEntries The menu entries of your plugin. The following information is saved for a menu entry:
  • label: The label to be displayed in the back end
  • menu: The menu that can be accessed by a plugin via entry points. Find a list of available entry points below.
  • urlKey: The route for the view in our plentymarkets back end, e.g. http://your-plentystore.co.uk/plenty/ui-backend/start/hello-world
    Note: For the URL key of the plugin, only use hyphens.
  • entryPoint: The entry point of your plugin
  • icon: The icon for your the menu entry in the system tree. If no icon is specified, the standard plugin icon is displayed. To not display any icon, use "icon": "none". Find a list of all icons here.

Menu entry points

Back end views can be integrated in the plentymarkets main menu and in the system tree. The following menus can be accessed by a plugin via entry points. You can find a list with eligible system tree entries here.

  • start
  • start/account
  • item
  • item/lionbridge
  • listing
  • listing/main-batch-processing
  • stock
  • stock/purchase
  • stock/returns
  • crm
  • order
  • order/scheduler
  • data-exchange
  • data-exchange/export
  • data-exchange/import
  • cms

Plugin deployment

After creating a plugin with the respective structure and files, the plugin needs to be added to your system and deployed. There are two ways to accomplish this:

If you use plentyDrive and activated the automatic build function in your back end, plugin sets will be deployed automatically after each sync. If you use Git webhooks, you must deploy plugin sets manually before changes become visible. To do this, in your back end, go to the Plugins » Plugin overview menu and, in the plugin sets containing your developed plugin, click the Save & publish plugins button.

  • Clicking on the Save & publish plugins icon will start the deployment process for all plugins that have a check mark in the Active column of the plugin set.
    → You can not start the deployment process for individual plugins.

You need to deploy the plugins if one of the following has occurred since the last deployment process:

  • new plugins were added and activated
  • plugins were updated
  • plugins were activated
  • plugins were deactivated
  • deployment errors were fixed
  • currently deployed plugins were deleted

Recommended IDEs

We recommend using an IDE which supports the PHP language and Twig syntax. For this purpose, we suggest using one of the following IDEs.

PhpStorm

PhpStorm is a comprehensive IDE which supports all PHP language features. PhpStorm also includes a wide range of leading edge front-end technologies, such as CSS, Sass, Javascript, as well as Twig syntax highlighting.

Installation

  1. Download and install PhpStorm
  2. Install Twig Plugin for Twig syntax highlighting

Atom

Atom is a customisable editor working across operating systems. It can be extended to also support Twig syntax.

Installation

  1. Download and install Atom IDE
  2. Install Twig Plugin* for Twig syntax highlighting

*) All required Atom packages can be found using the embedded package control pane of the Atom IDE. This pane can be found in Atom: Settings > Install.

Sublime Text

As an alternative to the PhpStorm and Atom IDEs, we also recommend Sublime Text with the respective plugins for syntax highlighting.

Installation

  1. Install Sublime Text
  2. Install Sublime Text's Package-Control
  3. Install Twig Plugin