چگونه برای ناپ‌کامرس پلاگین بنویسیم؟

پلاگین‌ها برای گسترش عملکرد ناپ‌کامرس ورژن 4.3 استفاده می‌شود، این پلاگین‌ها انواع مختلفی دارند به عنوان مثال روش پرداخت (مثل پی‌پال، درگاه‌های پرداخت بانکی)، سیستم مالیات، روش محاسبه حمل و نقل و دیگر ابزارهای مثل گفتگوی زنده و موارد دیگر. برای ناپ‌کامرس پلاگین‌های مختلفی توزیع شده که می‌توانید آن‌ها را در سایت رسمی آن جستجو کنید تا اگر کسی متناسب با نیاز شما پلاگینی ایجاد کرده از آن استفاده نمایید، اگر نه که این مقاله این روند را توضیح می‌دهد.

ساختار پلاگین، فایل‌های مورد نیاز و مکان‌ها

1. اولین کاری که باید انجام بدید ایجاد یک کلاس لایبراری در سولوشن است. بهتره که لوکیشن این کلاس لایبراری در پوشه plugins باشد. (نکته: با پوشه Plugins در زیر شاخه Nop.Web\ قاتی نکنید، پابلیش پلاگین‌ها در این پوشه قرار می‌گیرد). قرار دادن همه پلاگین‌ها در پوشه "Plugins" بهترین حالت است. نامگذاری پیشنهادی برای پروژه پلاگین شما به این شکل است:

"Nop.Plugin.{Group}.{Name}"

{Group}:

گروه پلاگین شما رو مشخص می‌کند برای مثال( "Payment" or "Shipping")

یعنی پلاگین شما مربوط به پرداخت یا حمل و نقل و ... . برای مثال پلاگین (PayPalStandard) نام سولوشن آن (Nop.Plugin.Payments.PayPalStandard) است.

اما این نکته را توجه داشته باشید که این اجباری نیست و هر نامی که دوست دارید را می‌توانید برای پلاگین خود انتخاب کنید.

2. پس از ایجاد پروژه پلاگین، باید فایل csproj. آن را در ویرایشگر متنی باز کرده و محتوای آن را با مورد زیر جایگزین کنید:

<Project Sdk=&quotMicrosoft.NET.Sdk&quot>
    <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
        <Copyright>SOME_COPYRIGHT</Copyright>
        <Company>YOUR_COMPANY</Company>
        <Authors>SOME_AUTHORS</Authors>
        <PackageLicenseUrl>PACKAGE_LICENSE_URL</PackageLicenseUrl>
        <PackageProjectUrl>PACKAGE_PROJECT_URL</PackageProjectUrl>
        <RepositoryUrl>REPOSITORY_URL</RepositoryUrl>
        <RepositoryType>Git</RepositoryType>
        <OutputPath>..\..\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath>
        <OutDir>$(OutputPath)</OutDir>
        <!--Set this parameter to true to get the dlls copied from the NuGet cache to the output of your    project. You need to set this parameter to true if your plugin has a nuget package to ensure that   the dlls copied from the NuGet cache to the output of your project-->
        <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
    </PropertyGroup>
    <ItemGroup>
        <ProjectReference Include=&quot..\..\Presentation\Nop.Web.Framework\Nop.Web.Framework.csproj&quot />
        <ClearPluginAssemblies Include=&quot$(MSBuildProjectDirectory)\..\..\Build\ClearPluginAssemblies.proj&quot />
    </ItemGroup>
    <!-- This target execute after &quotBuild&quot target -->
    <Target Name=&quotNopTarget&quot AfterTargets=&quotBuild&quot>
        <!-- Delete unnecessary libraries from plugins path -->
        <MSBuild Projects=&quot@(ClearPluginAssemblies)&quot Properties=&quotPluginPath=$(MSBuildProjectDirectory)\$(OutDir)&quot Targets=&quotNopClear&quot />
    </Target>
</Project>

جای PLUGIN_OUTPUT_DIRECTORY را با نام پلاگین جایگزین شود، به عنوان مثال، Payments.PayPalStandard

ما از این روش برای اضافه کردن رفرنس‌های دات‌نت کور به پروژه‌مون استفاده می‌کنیم و به این صورت لایبراری‌های که رفرنسش را گذاشتیم در فایل بطور خودکار لود می‌شوند و بسیار راحت است اما این روش اجباری نیست.

3. مرحله بعدی ایجاد یک فایل plugin.json مورد نیاز برای پلاگین است. این فایل شامل اطلاعات توصیف کننده پلاگین شما است. فقط کافی است این فایل را از هر پلاگین موجود دیگه کپی کرده و متناسب با نیاز خود اصلاح کنید. برای اطلاعات در مورد فایل plugin.json، لطفاً به فایل plugin.json در پروژه‌های دیگه پلاگین‌ها مراجعه کنید.

4. آخرین مرحله ایجاد یک کلاسی است که اینترفیس IPlugin را پیاده‌سازی کند. ناپ‌کامرس یک کلاس BasePlugin دارد که برخی متدهای IPlugin را پیاده‌سازی کرده که از تکرار کد جلوگیری کرده است. ناپ‌کامرس برخی از اینترفیس‌های مشتق شده از IPlugin را در اختیار شما قرار داده است. به عنوان مثال، ما اینترفیس "IPaymentMethod" داریم که برای ایجاد پلاگین‌های پرداخت استفاده می‌شود که شامل برخی از متدهای است که فقط برای پرداخت استفاده می‌شود برای مثال ()ProcessPayment یا ()GetAdditionHandlingFee. در حال حاضر ناپ‌کامرس دارای اینترفیس‌های پلاگین زیر است:

• IExternalAuthenticationMethod

برای متدهای احراز هویت کاربر مانند Facebook ،Twitter ،OpenID و غیره استفاده می‌شود.

• IWidgetPlugin

به شما امکان می‌دهد ابزار (ویجت) ایجاد کنید. ابزارها در برخی از قسمت‌های سایت شما ارائه می‌شوند. به عنوان مثال، می‌تواند یک بلوک "چت زنده" در ستون سمت چپ سایت شما باشد.

• IExchangeRateProvider

برای دریافت نرخ ارز استفاده می شود.

• IDiscountRequirementRule

به شما امکان می‌دهد قوانین تخفیف جدید خود را ایجاد کنید.

• IPaymentMethod

پلاگین‌هایی که برای پرداخت استفاده می‌شوند.

• IShippingRateComputationMethod

این پلاگین‌ها برای متدهای پرداخت و نرخ حمل و نقل استفاده می‌شود.

• ITaxProvider

برای گرفتن نرخ مالیات استفاده می‌شود.

• IMiscPlugin

اگر پلاگین شما با هیچ یک از اینترفیس‌های بالا در رابطه نیست از این استفاده کنید.

نکته مهم: پس از ساخت پروژه قبل از هر تغییری پروژه را clean کنید. بعضی از رفرنس‌ها کش می‌شود و باعث خطا و دیوانه شدن دولوپر می‌شود!

ممکنه بعد از اضافه کردن پروژه پلاگین به سلوشن، نیاز باشه که یکبار rebuild کنید. اگر شما Dll پلاگین خود را در Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY ندیدید لازمه که یکبار دیگه سولوشن را rebuild کنید. اگر dll پلاگین شما در پوشه درست در Nop.Web نباشد ناپ‌کامرس پلاگین را در لیست خودش نمیاره.

بررسی requests. Controllers ,models ,views

اکنون می‌توانید پلاگین را با رفتن به Admin area → Configuration → Local Plugins مشاهده کنید. اما همانطور که حدس زدید پلاگین ما هیچ کاری نمی‌کند. برای تنظیمات آن حتی رابط کاربری وجود ندارد. بیایید یک صفحه برای پیکربندی پلاگین ایجاد کنیم.

• ایجاد یک مدل: یک فولدر به اسم models در پلاگین خودتون ایجاد کنید و کلاس مربوط به مدلتون تنظیم کنید.
• ایجاد یک ویو: یک فولدر در پلاگین خود به اسم views ایجاد کنید و فایل chtml به نام Configure.chtml ایجاد نمایید. پراپرتی Build Action روی Content و پراپرتی Copy to Output Directory روی copy always تنظیم کنید. توجه داشته باشید صفحه configuration باید از لی‌اوت (Layout) "ConfigurePlugin_" استفاده کند.
• مطمئن شوید که فایل ViewImports.cshtml_ در پوشه ویو وجود داشته باشد در صورتی که وجود نداشت از پلاگین‌های دیگه ناپ‌کامرس کپی کنید.
• ایجاد کنترلر: فولدری به نام controllers در پلاگین خود ایجاد کنید و کنترلر جدید را ایجاد کنید.روش خوب این است که نام گذاری controllerها به این شکل باشد {Group}{Name}Controller.cs . برای مثال PaymentPayPalStandardController

البته که اجباری نیست برای این نوع نامگذاری و یک توصیه است.

اکشن متد مناسب برای صفحه configuration ایجاد کنید (در area admin). نام متد را configure بزارید. کلاس مدل را برای متد ارسال کنید به ویو با آدرس فیزیکی زیر:

~/Plugins/{PluginOutputDirectory}/Views/Configure.cshtml

• برای متد خود از attribute زیر استفاده کنید:

[AuthorizeAdmin] //confirms access to the admin panel
 [Area(AreaNames.Admin)] //specifies the area containing a controller or action

برای نمونه پلاگین پرداخت PayPalStandard باز کنید و نحوه پیاده سازی کنترلرهای آن را ببینید.

سپس برای هر پلاگین که یک صفحه پیکربندی یا configuration دارد باید url آن را مشخص کنید. کلاس BasePlugin متدی به نام GetConfigurationPageUrl دارد که url آن را برمی‌گرداند.

public override string GetConfigurationPageUrl()
  {
     return $&quot {_webHelper.GetStoreLocation()}Admin/{CONTROLLER_NAME}/{ACTION_NAME}&quot
  }

وقتی که پلاگین نصب می‌شود و متد بالا رو هم اضافه کرده باشید لینک پیکربندی یا configure اضافه می‌شود در زیر Admin → Configuration → Local Plugins

نکته: راحترین کار برای انجام مراحل بالا باز کردن پلاگین‌های دیگه و کپی کردن این فایل‌ها در پروژه خودتون است و بعد از آن نام‌ها را تغییر بدید.

برای مثال پلاگین PayPalStandard ساختار پروژه به این شکل است:

متدهای Install,Uninstall,Update

این مرحله اختیاری است. برخی از پلاگین‌ها می‌توانند در هنگام نصب منطق اضافی داشته باشند. به عنوان مثال، یک پلاگین می‌تواند ریسورس جدیدی را وارد کند. بنابراین پیاده‌سازی IPlugin خود را باز کنید (در بیشتر موارد از کلاس BasePlugin مشتق خواهد شد) و متدهای زیر را نادیده بگیرید:

• Install

این متد در زمان نصب فراخوانی می‌شود. می‌توانید تنظیمات اولیه پلاگین خود را انجام دهید مثلا اضافه کردن ریسورس جدید یا جدول در دیتابیس در صورتی که ضروری است.

• Uninstall

این متد زمانی که پلاگین را حذف نصب می‌کنید فراخوانی می‌شود مانند بالا اگر منابعی دارید که باید حذف شود می‌توانید اینجا تنظیم کنید.

• Update

این متد در زمان آپدیت پلاگین فراخوانی می‌شود (وقتی که نسخه پلاگین در فایل Plugin.json تغییر کرده باشد).

نکته مهم: اگر متدهای بالا را تغییر ندادید نباید پیاده‌سازیش را در کلاس حذف کنید. برای مثال در متد install باید ()base.install صدا زده شود. متد install پلاگین PayPalStandard به شکل زیر است:

public override void Install()
{
    var settings = new PayPalStandardPaymentSettings()
    {
        UseSandbox = true
    };
    _settingService.SaveSetting(settings);
    ...
    base.Install();
}

نکته: لیست پلاگین‌های نصب شده در این آدرس است، این لیست هنگام نصب ایجاد می‌شود

\App_Data\plugins.json

Routes

اینجا نگاهی داریم به نحوه ثبت مسیرهای پلاگین. ASP.NET Core Routing مسئول نگاشت درخواست‌ها از مرورگر به اکشن خاص آن می‌باشد.برای اطلاع بیشتر به این اینجا مراجعه کنید.

در صورتی نیاز به تنظیم route یک فایل به نام RouteProvider.cs ایجاد کنید. به عنوان مثال، کلاس RouteProvider زیر، یک مسیر جدید اضافه می‌کند که با باز کردن مرورگر وب و رفتن به آن می‌توانید به آن دسترسی پیدا کنید.

http://www.yourStore.com/Plugins/PaymentPayPalStandard/PDTHandler

public partial class RouteProvider : IRouteProvider
 {
    public void RegisterRoutes(IEndpointRouteBuilder endpointRouteBuilder)
    {
        //PDT
 endpointRouteBuilder.MapControllerRoute(&quotPlugin.Payments.PayPalStandard.PDTHandler&quot, &quotPlugins/PaymentPayPalStandard/PDTHandler&quot,
                new { controller = &quotPaymentPayPalStandard&quot, action = &quotPDTHandler&quot });
    }
    public int Priority => -1;
 }

آپدیت ناپ‌کامرس ممکن است پلاگین را خراب کند

برخی از پلاگین‌ها ممکن است منسوخ شده و دیگر با نسخه جدید nopCommerce کار نکنند. اگر پس از ارتقا به نسخه جدید با مشکلی روبرو شدید، پلاگین را حذف کرده و به وب سایت رسمی nopCommerce مراجعه کنید تا ببینید نسخه جدیدتری در دسترس است یا خیر. بسیاری از نویسندگان پلاگین‌ها برای جایگزینی نسخه جدیدتر، پلاگین‌های خود را ارتقا می‌دهند، با این حال، برخی از آنها این کار را نمی‌کنند و با پیشرفت nopCommerce، پلاگین آنها منسوخ می‌شود. اما در بیشتر موارد، می‌توانید به سادگی فایل plugin.json را باز کرده و قسمت SupportedVersions را بروز کنید.

نتیجه‌گیری

امیدوارم این مقاله به شما کمک کرده باشه که کار با ناپ‌کامرس شروع کنید و شما را برای ساخت پلاگین‌های پیچیده‌تر آماده کند.

پلاگین تمپلیت

برای پلاگین‌های جدید nopCommerce می‌توانید از Visual Studio Template ما استفاده کنید. این مورد می‌تواند در زمان شما صرفه جویی کند، زیرا اکنون نیازی به انجام دستی تمام مراحل اولیه ندارید. مانند ایجاد پوشه‌ها (کنترلرها ، ویوها ، مدل‌ها و غیره)، سایر فایل‌های مورد نیاز (DependencyRegistrar.cs , _ViewImports.cshtml ، ObjectContex ، plugin.json و غیره)، پیکربندی، ریسورس پروژه و غیره). لطفاً آن را پیدا کنید و دستورالعمل نصب را اینجا پیدا کنید.

منبع: