در پردازش، یک پلاگین (یا افزونه) مجموعه ای از اجزای نرم افزاری است که توانایی های خاصی را برای برنامه نرم افزاری بزرگتر اضافه می کند. (ویکی پدیا)

پلاگین ها برای افزایش کارایی ناپ کامرس بکار می رود. ناپ کامرس دارای انواع مختلفی از پلاگین ها است. به عنوان مثال، روش های پرداخت (مانند PayPal)، ارائه دهندگان مالیات، روش های محاسبه روش حمل و نقل (مانند UPS، USP، FedEx)، ویجت ها (مانند بلوک چت زنده) و بسیاری دیگر. ناپ کامرس در حال حاضر با بسیاری از پلاگین های مختلف منتشر شده است. شما همچنین می توانید پلاگین های مختلف را در سایت رسمی ناپ کامرس جستجو کنید تا ببینید آیا کسی قبلا پلاگین ای را که نیازهای شما را برآورده میکند، ایجاد کرده است. اگر نه، این مقاله شما را در فرآیند ایجاد پلاگین خود هدایت خواهد کرد.

ساختار پلاگین، فایل های مورد نیاز و موقعیت ها.

1. اولین چیزی که باید انجام دهید این است که یک پروژه جدید «کتابخانه کلاس» در solution ایجاد کنید. این یک عمل خوب است که تمام پلاگین ها را در ریشه solution خود قرار دهید (در زیر شاخه \ Plugins واقع در دایرکتوری \ Nop.Web که برای پلاگین هایی که قبلا استفاده شده است مخلوط نکنید). ین یک تمرین خوب است که همه پلاگین ها را به پوشه "Plugins" راه حل انتقال دهید. (شما می توانید اطلاعات بیشتری در مورد پوشه های راه حل در اینجا پیدا کنید).

نام پیشنهادی برای یک پروژه پلاگین "Nop.Plugin {Group}. {Name}" است. {Group} گروه پلاگین شما (به عنوان مثال، «Payment» یا «Shipping») است. {Name} نام پلاگین شما (به عنوان مثال، "PayPalStandard") است. به عنوان مثال، پلاگین پرداخت استاندارد PayPal دارای نام زیر است: Nop.Plugin.Payments.PayPalStandard. اما لطفا توجه داشته باشید که این الزام نیست. و شما می توانید هر نامی برای پلاگین را انتخاب کنید. به عنوان مثال، "MyGreatPlugin".

 

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

<Project Sdk="Microsoft.NET.Sdk">

 <PropertyGroup>

   <TargetFramework>net461</TargetFramework>

 </PropertyGroup>  

 <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">

   <OutputPath>..\..\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath>

   <OutDir>$(OutputPath)</OutDir>

 </PropertyGroup>

 <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">

   <OutputPath>..\..\Presentation\Nop.Web\Plugins\PLUGIN_OUTPUT_DIRECTORY</OutputPath>

   <OutDir>$(OutputPath)</OutDir>

 </PropertyGroup>

 <!-- This target execute after "Build" target -->

 <Target Name="NopTarget" AfterTargets="Build">

   <!-- Delete unnecessary libraries from plugins path -->

   <MSBuild Projects="$(MSBuildProjectDirectory)\..\..\Build\ClearPluginAssemblies.proj" Properties="PluginPath=$(MSBuildProjectDirectory)\$(OutDir)" Targets="NopClear" />

 </Target>

</Project>

 

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

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

 

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

{

 "Group":"Payment methods",

 "FriendlyName": "PayPal Standard",

 "SystemName": "Payments.PayPalStandard",

 "Version": "1.42",

 "SupportedVersions": [ "4.00" ],

 "Author": "nopCommerce team",

 "DisplayOrder": 1,

 "FileName": "Nop.Plugin.Payments.PayPalStandard.dll",

 "Description": "This plugin allows paying with PayPal Standard"

}

 در واقع تمام زمینه ها خود توصیفی هستند، اما در اینجا نکاتی وجود دارد. فیلد SystemName باید منحصر به فرد باشد. بخش نسخه یک شماره نسخه افزونه است؛ شما می توانید آن را به هر مقدار که دوست دارید تنظیم کنید. فیلد SupportedVersions می تواند شامل لیستی از نسخه های پشتیبانی شده ناپ کامرس با استفاده از کاما  باشد. (حاوی اطمینان از اینکه نسخه فعلی nopCommerce در این لیست گنجانده شده است، در غیر این صورت، آن بارگذاری نمی شود). فیلد FileName دارای فرمت زیر است: Nop.Plugin. {Group}. {Name} .dll (این نام فایل اسمبلی پلاگین شما است). اطمینان حاصل کنید که «کپی به دایرکتوری خروجی» از این فایل به «کپی اگر جدیدتر» تنظیم شده باشد.

4. آخرین مرحله مورد نیاز برای ایجاد یک کلاس پیاده سازی رابط IPlugin (Nop.Core.Plugins namespace) است. فروشگاه ناپ کامرس دارای کلاس BasePlugin است که در حال حاضر برخی از روش های IPlugin را اجرا می کند و به شما اجازه می دهد تا از تکراری شدن کد منبع جلوگیری کنید. ناپ کامرس همچنین برخی از رابط های خاص که از IPlugin مشتق شده است را برای شما فراهم می کند.  به عنوان مثال، ما رابط کاربری "IPaymentMethod" داریم که برای ایجاد پلاگین های جدید روش پرداخت استفاده می شود. این شامل برخی از روشهایی است که فقط برای روش های پرداخت مانند ProcessPayment () یا GetAdditionalHandlingFee () استفاده می شود. ناپ کامرس در حال حاضر دارای رابط های پلاگین خاص زیر است:
   1. IExternalAuthenticationMethod. مورد استفاده برای ایجاد روش های احراز هویت خارجی مانند فیس بوک، توییتر، OpenID و غیره
   2. IWidgetPlugin. به شما امکان ایجاد ویجت ها را می دهد.  ابزارک ها در برخی از قسمت های سایت شما ارائه می شوند. به عنوان مثال، می تواند یک بلوک گفتگوی زنده در ستون سمت چپ سایت شما باشد.
   3. IExchangeRateProvider. برای بدست آوردن نرخ ارز استفاده می شود.
   4. IDiscountRequirementRule. به شما امکان می دهد قوانین تخفیف جدید مانند «کشور صورتحساب یک مشتری باید ...» ایجاد کنید.
   5. IPaymentMethod. پلاگین هایی که برای پردازش پرداخت استفاده می شوند.
   6. IShippingRateComputationMethod. این پلاگین ها برای بازیابی روش های پذیرفته شده و نرخ حمل و نقل مناسب استفاده می شوند. به عنوان مثال، UPS، UPS، FedEx و غیره
   7. ITaxProvider. ارائه دهندگان مالیات برای دریافت نرخ مالیات استفاده می شود.

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

Important note: پس از ساخت هر پروژه، قبل از انجام تغییرات، solution را پاک کنید. بعضی از منابع ذخیره می شوند و می توانند منجر به دردسر توسعه دهندگان شوند.

مدیریت درخواست ها کنترلرها، مدل ها و view ها

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

اکنون ما باید یک کنترل کننده، یک مدل و یک نمایه ایجاد کنیم.

1.  
   1. کنترل کننده MVC مسئول پاسخ دادن به درخواست های ساخته شده در برابر یک وب سایت ASP.NET MVC می باشد. هر درخواست مرورگر به یک کنترل کننده خاص نگاشت می شود.
   2. نمایه حاوی نشانه گذاری HTML و محتوا است که به مرورگر ارسال می شود. نمایه (view) معادل یک صفحه است هنگام کار با یک برنامه ASP.NET MVC
   3. یک مدل MVC حاوی تمام منطق برنامه کاربردی شما است که در نمای یا کنترل کننده موجود نیست.

شما می توانید اطلاعات بیشتری در مورد الگوی MVC در اینجاپیدا کنید.

خب بیایید شروع کنیم:

1.  
   1. ایجاد یک مدل. یک پوشه مدل در پلاگین جدید اضافه کنید و سپس یک کلاس مدل جدید اضافه کنید که به نیاز شما بستگی دارد.
   2. ایجاد یک نمایه. یک پوشه Views در افزونه جدید اضافه کنید و سپس یک فایل cshtml به نام Configure.cshtml اضافه کنید. مشخصه "Build Action" از فایل نمایه بر روی "Content" تنظیم می شود، و ویژگی "کپی به خروجی دایرکتوری" تنظیم می شود به "کپی اگر جدیدتر موجود بود". توجه داشته باشید که صفحه پیکربندی باید از طرح _ConfigurePlugin استفاده کند.
      همچنین اطمینان حاصل کنید که فایل _ViewImports را در فهرست \ Views خود دارید. شما فقط می توانید آن را از هر پلاگین موجود دیگر کپی کنید.
   3. ایجاد یک کنترلر. یک پوشه Controllers را در پلاگین جدید اضافه کنید و سپس یک کلاس کنترل جدید اضافه کنید. یک عمل خوب اینست که کنترلرهای پلاگین را نام ببرید {Group} {Name} Controller.cs. به عنوان مثال، PaymentPayPalStandardController. البته این یک ضرورت نیست که کنترل کننده ها را به این طریق نام گذاری کنید (فقط یک توصیه است). سپس یک روش عملی مناسب برای صفحه پیکربندی (در قسمت مدیریت) ایجاد کنید. نام آن را "پیکربندی" میگذاریم.  یک کلاس مدل را آماده کرده و با استفاده از یک مسیر نمایش فیزیکی به دید زیر بروید: - "~/Plugins/{PluginOutputDirectory}/Views/Configure.cshtml". 
      از ویژگی های زیر برای روش عمل خود استفاده کنید:

[AuthorizeAdmin] - confirms access to the admin panel

[Area(AreaNames.Admin)] - specifies the area containing a controller or action

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

سپس برای هر پلاگین که یک صفحه پیکربندی دارد، شما باید یک آدرس پیکربندی مشخص کنید. کلاس پایه به نام BasePlugin دارای روش GetConfigurationPageUrl است که یک آدرس پیکربندی را برمیگرداند:

return $"{_webHelper.GetStoreLocation()}Admin/ControllerName/ActionName";

جایی که ControllerName نام کنترل کننده شما است و ActionName نام عمل است (معمولا "Configure").

هنگامی که پلاگین خود را نصب کرده اید و روش پیکربندی را اضافه می کنید، یک لینک برای پیکربندی پلاگین خود را در قسمت Admin> Configuration> Plugins پیدا خواهید کرد.

نکته: ساده ترین راه برای تکمیل مراحل فوق، باز کردن هر پلاگین دیگری و کپی کردن این فایل ها به پروژه پلاگین شما است. سپس کلاس ها و دایرکتوری ها را تغییرنام دهید.

به عنوان مثال، ساختار پروژه پلاگین PayPalStandard شبیه تصویر زیر است:

مدیریت روش های "نصب" و "حذف"

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

1.  
   1. نصب. این متد در هنگام نصب افزونه فراخوانی خواهد شد. شما می توانید هر تنظیماتی را در اینجا راه اندازی کنید، منابع جدید محلی را وارد کنید، یا برخی از جداول پایگاه داده جدید (در صورت لزوم) ایجاد کنید.
   2. حذف. این روش در هنگام حذف پلاگین مورد استفاده قرار خواهد گرفت.

نکته مهم: اگر یکی از این روش ها را بازنویسی می کنید، پیاده سازی پایه خود را پنهان نکنید. به عنوان مثال، روش بازنویسی "Install" باید شامل روش زیر است: base.Install (). روش "نصب" پلاگین PayPalStandard مانند کد زیر است

public override void Install()

        {

            var settings = new PayPalStandardPaymentSettings()

            {

                UseSandbox = true

            };

            _settingService.SaveSetting(settings);

...

base.Install();

}

نکته: لیست پلاگین های نصب شده در \ App_Data \ installedPlugins.json قرار دارد. این لیست در طول نصب ایجاد می شود.

مسیرها

در اینجا ما نگاهی به نحوه ثبت مسیرهای افزونه ها خواهیم داشت. مسیریابی هسته ASP.NET مسئول نگاشت درخواست های مرورگر ورودی به اقدامات کنترل کننده MVC خاص است. شما می توانید اطلاعات بیشتری در مورد مسیریابی اینجا پیدا کنید. بنابراین مراحل بعدی را دنبال کنید:

1.  
   1. اگر شما نیاز به اضافه کردن یک مسیر سفارشی دارید، فایل RouteProvider.cs را ایجاد کنید. این امر به سیستم ناپ کامرس درباره مسیرهای افزونه اطلاع می دهد. به عنوان مثال، کلاس RouteProvider زیر مسیر جدیدی را می افزاید که با باز کردن مرورگر وب و مرور URL به آدرس http://www.yourStore.com/Plugins/PaymentPayPalStandard/PDTHandler (که توسط پلاگین PayPal استفاده می شود) قابل دسترسی است:

<>b.public partial class RouteProvider : IRouteProvider

<>c.   {

<>d.        public void RegisterRoutes(IRouteBuilder routeBuilder)

        {

             routeBuilder.MapRoute("Plugin.Payments.PayPalStandard.PDTHandler", "Plugins/PaymentPayPalStandard/PDTHandler",

             new { controller = "PaymentPayPalStandard", action = "PDTHandler" });

        }

        public int Priority

        {

            get

            {

                return -1;

            }

        }

    }

ارتقاء ناپ کامرس ممکن است پلاگین ها را خراب کند

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

جمع بندی

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