Plugin Structure

Once we've setup our development environment, we can start with our plugin development. A plugin is a project of type class library with .NET SDK version 2.1 or higher depending on the EvenCart version. The class library project may reference the following projects depending on the type of plugin your are making.

EvenCart.Core - Contains core functionality for EvenCart system.

EvenCart.Data - Contains data entities for EvenCart system.

EvenCart.Services - Contains data access services for EvenCart system.

EvenCart.Infrastructure - Contains view system and routing functionality for EvenCart system.

DotEntity (for database plugins) - Required for data access plugins.

DotEntity.SqlServer (for database plugins) - Required for data access plugins which support SqlServer databases.

DotEntity.MySql (for database plugins) - Required for data access plugins which support MySql databases.

we may also wish to add additional references depending on our plugin's functionality.

Tip - Make sure that the libraries you reference in your plugin project do not have version conflicts with the same libraries on EvenCart version. Otherwise your plugin may not function correctly.

The following document describes the plugin structure of a typical plugin

Directory Structure

A plugin typically contains the following directories.

Controllers - Stores the controllers for the plugin. Depending on the plugin type, there may or may not be a need for controllers in our plugin. If our plugin however have some configuration options that store owner can setup, we'll need controllers to process that. The Controllers directory contains the controllers with actions that a user on store-front performs. The controller names follow same convention as standard ASP.NET Core MVC conventions.

Controllers\Administration - If our plugin has some configuration or setup that needs to be done by administrator, then those Controller-Actions should be placed in Controller\Administrator directory.

Components - Components are reusable views that we can use to render on client pages. we can read more about components at Microsoft site. If we are creating a widget plugin then the widget's class files are also placed in this directory.

Data - If our plugin requires database interaction, then our data entity classes should be placed in this directory.

Services - The services directory contains various service interfaces and their implementations. For plugins that require database interaction, the data access services should also be kept in this directory.

Models - The view models that are passed to our views from controller are kept in models directory.

Versions - The versions directory stores the data entity versions signatures as plugin is released. If we have previous worked with EntityFramework, this is similar to Code-First migrations except that it's easier and requires more manual work.

Views - The views directory contains the html views for the plugin. EvenCart uses [Liquid]() as it's templating language and the view files have extension .html. Only views that are accessible to store fronts are kept in this directory.

Views\Administration - If we have any Administrator controllers in our plugin, then their corresponding views should be kept in the Views\Administration directory.

Views\:Controller: - The views corresponding to each controller must essentially be kept in separate directories. The name of the directory should match the name of the controller without 'Controller' suffix. e.g. If our plugin has a UserController class in Controllers directory then it's views should be kept in Views\User directory.

Plugin Configuration File

Every plugin is described by it's configuration file. The name of the file must be config.json. The plugin file contains the following JSON object.

{
  "name": "Ui Slider",
  "description": "The plugin displays slider on store home page",
  "version": "1.0",
  "supportedVersions": ["1.0"],
  "assemblyName": "Ui.Slider.dll",
  "systemName": "EvenCart.Ui.Slider",
  "author": "RoastedBytes.com",
  "authorUri": "https://www.roastedbytes.com",
  "pluginUri": "",
  "tags": ["slider", "ui"]
}

Required Fields

name - The friendly name of the plugin.

description - A brief description about the plugin functionality.

version - The version of the plugin.

supportedVersions - The EvenCart versions that this plugin works on.

assemblyName - The assembly name of our plugin. EvenCart uses this information to load the assembly.

systemName - A unique name for the plugin. It's recommended that we keep it same as our namespace name, prefixed with our company name.

Optional Fields

author - The author of the plugin.

authorUri - The url of author's page.

pluginUri - The url of plugin's home page.

tags - A collection of strings that helps to categorize plugins. This helps to search the store owners appropriate plugins.

Plugin Class File

A plugin class file is a primary plugin file that identifies the overall plugin type(s). In a nutshell any class that inherits EvenCart.Core.Plugins.FoundationPlugin class or implements EvenCart.Core.Plugins.IPlugin interface is qualified to be a plugin class file.

Note that there can only be one plugin class file per plugin.

Tip - The FoundationPlugin class is an abstract class that implements IPlugin interface. That is why we can use either of the two to create a plugin class file.

The interface IPlugin has the following methods and properties signature.

The FoundationPlugin class provides empty implementations for these methods and properties. That is why it's better to create the plugin class by inheriting FoundationPlugin so that we only need to override the methods or properties that we need to modify.

There are also some more specialized classes and interfaces available to create some special types of plugins. The usage and syntax of those specialized constructs are described on their specific pages. we can create the following types of plugins.

• Database Access Plugin
• Payment Processing Plugin
• Widget Component
• Shipping Provider Plugin
• Authentication Provider Plugin

Build Settings

We recommend the following settings for your projects to speed up the development and debugging of your plugins.

Build Output Directory

The output directory of the plugin project build be set to the Plugins directory of EvenCart installation. It's found at your EvenCart website root\Plugins

To set build output directory in Visual Studio

1. Right click on your project and click Properties.
2. Click on Build tab page on the left.
3. Find the box Output Path and set the path to the recommended Plugins directory above.
4. Do the same for all the available project configurations.

Copy static files to local

All the static files such as stylesheets, javascript files and your html views should be copied to the build output directory.

To enable copy files on build,

1. Select the static files that need to be copied to output directory.
2. Right click and click Properties.
3. In the properties window, set Build Action to Content and Copy to Output Directory to Copy if newer.

Sample Plugins

To see how are typical plugin looks as a whole, visit our plugins repository.

Next steps

Now that you know about how to organize files around, let's understand the MVC structure we use for EvenCart.