My first plugin

This tutorial is aimed at plentymarkets users who are getting started with plugin development. You will only need basic knowledge of creating and editing files in an integrated development environment (IDE) as well as using plentymarkets.

In six simple steps, we will walk you through creating your first plugin that displays Hello World! in your browser when adding /hello to your domain.

Step 1: Setting up an IDE

We recommend using an IDE which supports the PHP language and Twig syntax. To get started, install Atom. It can be extended to support Twig syntax.

Installing Atom

Download and install the Atom IDE.
Install the Twig plugin^* for Twig syntax highlighting.

*) All required Atom packages can be found in the embedded package control pane of the Atom IDE. To access this pane, open the Atom » Preferences menu and click on Install.

Step 2: Setting up Git

Sign up for a hosting provider for your plugin, e.g. GitHub. You will need the login details when cloning your plugin to your plentymarkets inbox in step 5.

Creating a repository

Log in to your GitHub account.
Click on Create new... » New repository.
Enter a repository name.
→ Name the repository, e.g. HelloWorld.
Click on Create repository.
→ We have now set the basis for our plugin.

Installing GitHub Desktop

Install a desktop client for GitHub in order to clone the repository to your local computer.

Install GitHub Desktop.
Open your HelloWorld repository on GitHub.
In the Code tab of your repository, click on Set up in Desktop.
Select GitHub Desktop and clone the repository to a location on your hard drive.
→ We set up the repository clone in our desktop. The folder is still empty, so let's start filling it.

Step 3: Creating the plugin components

The components of your plugin are the foundation for the communication between the plugin and plentymarkets. A ServiceProvider is needed for registering the plugin in plentymarkets. A RouteServiceProvider creates and registers the output route. And a ContentController renders and displays your content in your template.

Creating the folders

All plugins need to be organised in a specific structure. We only need the following folders for our plugin. The resources folder can be organised in sub-folders. Here, we save our template. The src folder can also be organised in sub-folders and contains the plugin source code.

HelloWorld/
    ├── resources/
    │   └── views/
    │       └── content/
    │           └── // twig templates (can be organised in sub-folders)
    │
    ├── src/
    │   ├── Providers/
    │   └── Controllers/
    │
    └── plugin.json // plugin information

Creating the plugin.json

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.

Open Atom and click on Add Project Folder.
Select your plugin folder and click on Open.
Create a new json file in the plugin folder.
→ Name the file, e.g. plugin.json.
Insert the code sample below into the file.
Enter your name under author and save the file.

HelloWorld/plugin.json

{
    "name"              :"HelloWorld",
    "description"       :"My first plugin",
    "namespace"         :"HelloWorld",
    "author"            :"Your name",
    "type"              :"template",
    "serviceProvider"   :null
}

Important notice: Do not use special characters or spaces for the name attribute, otherwise your plugin will not be read properly. We recommend using camel case notation, for example: MyFirstPlugin

Creating the ServiceProvider

Create a new Providers folder in the src folder.
Create a new file in the Providers folder.
→ Name the file, e.g. HelloWorldServiceProvider.php.
Insert the code sample below into the file and save it.

HelloWorld/src/Providers/HelloWorldServiceProvider.php

<?php

namespace HelloWorld\Providers;


use Plenty\Plugin\ServiceProvider;

class HelloWorldServiceProvider extends ServiceProvider
{

    /**
     * Register the service provider.
     */

    public function register()
    {

    }
}

Explanation: We recommend that you use the name of the plugin folder as the namespace root. This service provider is the central location to register services in the plugin.

Creating the RouteServiceProvider

Create a new file in the Providers folder.
→ Name the file, e.g. HelloWorldRouteServiceProvider.php.
Insert the code sample below into the file and save it.

HelloWorld/src/Providers/HelloWorldRouteServiceProvider.php

<?php

namespace HelloWorld\Providers;


use Plenty\Plugin\RouteServiceProvider;
use Plenty\Plugin\Routing\Router;

class HelloWorldRouteServiceProvider extends RouteServiceProvider
{
    public function map(Router $router)
    {

    }
}

Registering the RouteServiceProvider

Now we have to register the RouteServiceProvider in the ServiceProvider. To do so, add a line in the code of HelloWorldServiceProvider.php.

HelloWorld/src/Providers/HelloWorldServiceProvider.php

...

        public function register()
        {
            $this->getApplication()->register(HelloWorldRouteServiceProvider::class);
        }

Creating the ContentController

Create a new Controllers folder in the src folder.
Create a new file in the Controllers folder.
→ Name the file, e.g. ContentController.php.
Insert the code sample below into the file and save it.

HelloWorld/src/Controllers/ContentController.php

<?php

namespace HelloWorld\Controllers;


use Plenty\Plugin\Controller;
use Plenty\Plugin\Templates\Twig;

class ContentController extends Controller
{
    public function sayHello(Twig $twig):string
    {
        return $twig->render('HelloWorld::TEMPLATE');
    }
}

Explanation: In this code example, we define the sayHello function that renders a twig template. The render method specifies the template location: 'PLUGINNAME::TEMPLATE'. Since templates are always saved in the resources/views folder in your plugin, we only have to specify part of the template path. Note that PLUGINNAME is the name of the plugin folder. The name of the plugin folder and the plugin namespace may differ.

Mapping the ContentController

Now we have to map the route for the ContentController in the RouteServiceProvider. To do so, add a line in the code.

HelloWorld/src/Providers/HelloWorldRouteServiceProvider.php

...

    public function map(Router $router)
    {
        $router->get('hello','HelloWorld\Controllers\ContentController@sayHello');
    }

Explanation: We use the get method to pass two parameters. The first parameter 'hello' defines the route. The second parameter consists of the Fully-Qualified Class Name and the @ controller method that is called when the route is called.

Creating the twig template

Create a new content folder in the resources/views folder.
Create a new file in the content folder.
→ Name the file, e.g. hello.twig.
Enter the content that you want to display in your browser into this file and save the file.
→ We simply enter <h1>Hello World!</h1>.

Specifying the template path

Here, we have to specify the template path in the ContentController. Simply replace TEMPLATE with the correct path.

HelloWorld/src/Controller/ContentController.php

...

    public function sayHello(Twig $twig):string
    {
        return $twig->render('HelloWorld::content.hello');
    }

Updating the plugin.json

Open the plugin.json file.
Enter the value for serviceProvider and save the file.
→ We enter the namespace of our ServiceProvider. In our case, the namespace is "HelloWorld\\Providers\\HelloWorldServiceProvider".

Step 4: Updating the repository

Next, the files in your local HelloWorld folder must be pushed into your Git repository.

Open GitHub Desktop.
→ The plugin files are now visible in GitHub Desktop.
Enter a commit message into the Description field.
Click on Commit to master.
→ The changes made to the repository are displayed in the overview.
Click on Publish.
→ Our plugin content is now pushed into the repository on GitHub.
Reload the GitHub website to see the changes.

Step 5: Cloning the plugin

In this step, you have to clone the Git repository into your plentymarkets inbox. You will need the remote URL from GitHub as well as your login details.

Open the plentymarkets back end.
Go to Plugins » Git.
Click on Add plugin.
→ The Settings window will open.
Enter the remote URL.
→ You can copy the URL by clicking on Clone or download in the repository on GitHub.
Enter your user name and password.
Click on Test connection.
→ Connectivity to the Git repository is checked and established and the drop-down menu Branch can be selected.
Select the branch of the repository that you want to clone and edit.
→ In our case, Master is set by default.
Save the settings.
→ The plugin repository is cloned to the plentymarkets inbox and the plugin is added to the plugin list.

Step 6: Deploying the plugin

Deploy the plugin to integrate it with plentymarkets.

Go to Plugins » Plugin overview.
Select your plugin set.
Activate the plugin in the Active column.
In the toolbar, click on Save & publish plugins.
→ Once a success message is displayed, we are ready to check the output.

Reaping the rewards

Finally, open a new browser tab and type in your domain adding /hello at the end. And there it is, your first plugin.

Info: Once you have changed the files in your local HelloWorld folder, the changes must be pushed to GitHub. You also have to update the plugin in your plentymarkets inbox by pulling the changes from GitHub. Finally, you have to deploy the plugin again to display the changes in your browser.