Implementing a NopCommerce 3.9 Custom Plugin

This document outlines my process used to intially create a NopCommerce plugin. This is just the starting point for your plugin and you will need to implement an interface for the type of plugin you are implementing after this.

For Reference: The official "How to write a nopCommerce plugin" tutorial

Create a New Class Project

Create a new Class Library Project inside the Plugins Directory of the NopCommerce Solution.
You absolutely MUST change the location of the project to ~\[ProjectName]\Plugins\ as it will default to be in ~\[ProjectName]\.

The naming convention for the ProjectName is Nop.Plugin.[PluginType].[ProjectName]

Important Note:
If you do not place the project in the \Plugins\ directory your files will not be where nop expects them. So your plugin structure will be off and it will cause problems when you want to run, install your plugin, or put it in source control.

Prepare the Project for Development

1. Remove the file Class1.

2. Add references: You need to add references for use in development for the application.

Important Note:
It is absolutely crucial that any library referenced in the \Presentation\Nop.Web\bin\ directory have the property of CopyLocal set to False. If this is not set correctly a conflict of files/versions can cause a presentation dll to be overwritten and this can bring down a production NopCommerce server. As a rule of thumb look at the \Presentation\Nop.Web\bin\ directory for any library you add and see if it already exists, if it does set CopyLocal to False.

Typically you will need to add at least the below libraries used by NopCommerce as references in your plugin project. Again, make certain they are not copying locally on build if they are already present in nop's presentation bin directory.

  • Nop.Core: via Project Reference
  • Nop.Data: via Project Reference
  • Nop.Services: via Project Reference
  • Nop.Web.Framework: via Project Reference
  • System.Web: via Assembly Reference
  • Browse to reference the following:
    • \packages\Microsoft.AspNet.WebPages.3.2.3\lib\net45\System.Web.WebPages.dll
    • \packages\Microsoft.AspNet.WebPages.3.2.3\lib\net45\System.Web.WebPages.Razor.dll
    • \packages\Microsoft.AspNet.Razor.3.2.3\lib\net45\System.Web.Razor.dll
    • \packages\Microsoft.AspNet.Mvc.5.2.3\lib\net45\System.Web.Mvc.dll
    • \packages\EntityFramework.6.1.3\lib\net45\EntityFramework.SqlServer.dll
    • \packages\EntityFramework.6.1.3\lib\net45\EntityFramework.dll

3. Set Ouptut Directory in Project Settings

  1. Right click your project and select Properties
  2. Go to the Build tab
  3. Set Configuration to All Configurations
  4. Set the output path as ..\..\Presentation\Nop.Web\Plugins\[PluginType].[PluginName]\

4. Add Web.Config

  1. Copy the Web.Config from another plugin into the plugin's root directory
  2. Include it in the solution.
  3. Right Click the file and select Properties
    • Set Build Action to Content
    • Set Copy to Output Directory to Copy if Newer

5. Add Description.txt

  1. Add a text file to your plugin's root directory.
  2. Include it in the solution.
  3. Right Click the file and select Properties
    • Set Build Action to Content
    • Set Copy to Output Directory to Copy if Newer
  4. Fill out the contents of the file using the template below.
Group: [PluginType]
FriendlyName: [PluginName]
SystemName: Nop.Plugin.[PluginType].[PluginName]
Version: 1.0
SupportedVersions: [CurrentNopVersion, ex. 3.08]
Author: [YourName]
DisplayOrder: 1
FileName: Nop.Plugin.[PluginType].[PluginName].dll

Plugin Type Definitions:

  • IExternalAuthenticationMethod: For creating external authentication methods such as Facebook, Twitter, OpenID, etc.
  • IWidgetPlugin: Allows you to create widgets. Widgets are rendered within widget zones on your site.
  • IExchangeRateProvider: For getting currency exchange rate.
  • IDiscountRequirementRule: Allows you to create new discount rules such as "Billing country of a customer should be…"
  • IPaymentMethod: Plugins which are used for payment processing.
  • IShippingRateComputationMethod: These plugins are used for retrieving accepted delivery methods and appropriate shipping rates. For example, UPS, UPS, FedEx, etc.
  • ITaxProvider: Tax providers are used for getting tax rates.
  • IMiscPlugin: Any other type of plugin that does not meet the above criteria and functionality.

Important Note:
If you do not add this file and it is not set to output on build you will not see your plugin in NopCommerce's plugin list.

  1. Add a jpg file named logo.jpg as your plugin's logo to the plugin's root directory
  2. Include it in the solution.
  3. Right Click the file and select Properties
    • Set Build Action to Content
    • Set Copy to Output Directory to Copy if Newer

7. CustomViewEngine and Plugin File Structure

  • Create a new folder in the root directory of your plugin called Infrastructure and within it create a new file called CustomViewEngine.cs containing the following code
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Nop.Web.Framework.Themes;

namespace Nop.Plugin.[PluginType].[PluginName].Infrastructure
{
    public class CustomViewEngine : ThemeableRazorViewEngine
    {
        public CustomViewEngine()
        {
            ViewLocationFormats = new[] {
                "~/Plugins/[PluginType].[PluginName]/Views/{1}/{0}.cshtml",
                "~/Plugins/[PluginType].[PluginName]/Views/{0}.cshtml"
            };
            PartialViewLocationFormats = new[] {
                "~/Plugins/[PluginType].[PluginName]/Views/{1}/{0}.cshtml",
                "~/Plugins/[PluginType].[PluginName]/Views/{0}.cshtml"
            };
        }
    }
}
  • In the root directory of your plugin create a file called RouteProvider.cs containing the following code:
using System.Web.Mvc;
using System.Web.Routing;
using Nop.Plugin.[PluginType].[PluginName].Infrastructure;
using Nop.Web.Framework.Mvc.Routes;

namespace Nop.Plugin.[PluginType].[PluginName]
{
    public class RouteProvider : IRouteProvider
    {
        public int Priority => 0;

        public void RegisterRoutes(RouteCollection routes)
        {
            ViewEngines.Engines.Insert(0, new CustomViewEngine());
        }
    }
}

  • In the root directory of your plugin create the following directories:

    • Controllers
    • Models
    • Views
      • Shared
      • [PluginName]

  • In the Controllers directory create a file called [PluginName]Controller.cs that inherits BasePluginController and include the using for System.Web.Mvc and Nop.Web.Framework.Controllers. Within the controller you can now return View() of the method/route name as you would in a normal MVC project. This simplifies having to put the path relative to the presentation project in every route as most of the Nop documentation directs you to do.

using System.Web.Mvc;
using Nop.Web.Framework.Controllers;

namespace Nop.Plugin.[PluginType].[PluginName].Controllers
{
    public class [PluginName]Controller : BasePluginController
    {...

8. Create Plugin class

Create the main class for your plugin. See specific plugin type tutorials for how to create and implement the different plugin interfaces.

Other Tutorials

Implementing a Misc NopCommerce Plugin

Documentation and Notes by Lee Jones July-2017

results matching ""

    No results matching ""