Create your first plugin

Note: We recommend to install your first Surikata online store locally before you read this guide. Follow this Installation guide to proceed.

Prepare the folder structure for the plugin

Each plugin must be located in a separate folder. You can create a multilevel folder structure to better tidy up your plugins. For example, there is a plugin WAI/Product/Detail for rendering the detail of the product item in the basic package:

src/
  Plugins/
    WAI/
      Product/
        Detail/

You can similarly create your own structure. Let's start with:

src/
  Plugins/
    MyCompany/
      HelloWorld

Create the Main.php file

In this folder you have to create a Main.php file (be careful about case sensitive names) with following contents:

<?php

namespace Surikata\Plugins\MyCompany {

  class HelloWorld extends \Surikata\Core\Web\Plugin {
    public function getWebPageUrlFormatted($urlVariables, $pluginSettings = []) {
      return "";
    }

    public function getTwigParams($pluginSettings) {
      return [];
    }

  }

}

namespace ADIOS\Plugins\MyCompany {

  class HelloWorld extends \Surikata\Core\AdminPanel\Plugin {
    public function getSiteMap($pluginSettings = [], $webPageUrl = "") {
      return [];
    }

    public function getSettingsForWebsite() {
      return [];
    }

  }

}

Keep in mind:

Create the TWIG template file

Each plugin that wants to render something on the website needs a corresponding TWIG template file.

Note: There are plugins that do not need to render anything, like plugins for exporting some data in XML format. These plugins do not need a TWIG template file.

A corresponding TWIG template file is located in a Themes/YOUR_THEME/Templates/Plugins folder and in the same subfolder as the plugin. For example we would have our template located here:

src/
  Themes/
    YOUR_THEME/
      Templates/
        Plugins/
          MyCompany/
            HelloWorld.twig

Add some content to be rendered

Now, put following content in the HelloWorld.twig template file:

Hello World! Today is {{ currentDate }}.

Documentation for TWIG files you can find at twig.symfony.com

Configure the sitemap - create the URL

If you want your plugin to be rendered on some URL, you have to create a corresponding web page and configure it to use your plugin. There are two ways how to achieve this:

Option 1: Create the URL programmatically

As the name of the method suggests, it is called after the default routing have been performed. And also, as you can see in the code above, the "hello-world" URL will contain content generated by following plugins:

Option 2: Create the URL in administration panel's UI

Test the URL

Now, if you navigate to the created website (the URL should be something like https://localhost/my_first_surikata/hello-world, but this strongly depends on the configuration of your development environment), you should see your first content rendered by your first plugin.

But there is still something missing - the value of {{ currentDate }}. This is where the getTwigParams() method of your plugin takes place.

Pass current date to the TWIG template

Open Main.php file of your plugin and change the getTwigParams() method followingly:

public function getTwigParams($pluginSettings) {
  return [
    "currentDate" => date("Y-m-d"),
  ];
}

Now, refresh the hello-world web page and enjoy the results.

getTwigParams(.) is very important function, because this function provides data for the front-end TWIG file.

Asynchronous page rendering

You can create data for website asynchronously by using function renderJSON in frontend namespace:

public function renderJSON() {
    $returnArray = [];
    return $returnArray;
}

renderJSON function takes returned data and create a JSON format from them. On client side, you can simply use prepared Javascript function:

Surikata.prototype.renderPluginJSON = function (pluginName, requestData, success, fail, error) {
    requestData.__renderOnlyPlugin = pluginName;
    requestData.__output = 'json';

    $.getJSON(
        '',
        requestData
        ).done(function (data) {
            if (data.status == 'FAIL') {
                if (typeof fail == 'function') {
                    fail(data);
                } else {
                    let msg = 'Error: ' + data.exception;
                    if (data.error != '') {
                        msg += '\nDescription: ' + data.error;
                    }

                    alert(msg);
                }
            } else if (typeof success == 'function') {
              success(data);
            }
        }).fail(function (data) {
            if (typeof error == 'function') {
                error(data);
            } else {
                console.log('renderPluginJSON Error', pluginName, requestData, data);
            }
        });
    }
}

Learn more

Congratulations!

You have successfuly created your first Surikata plugin.

There are some other things to learn if you want to become a master, e.g.:

Surikata
E-commerce development framework