افزونهٔ نرخ ارز وردپرس؛ نصب NetArz FX و شورت‌کد [netarz_rate]

در نرخ ارز در وردپرس و ووکامرس نشان دادیم چطور با چند تابع در functions.php نرخ را بگیرید و کش کنید. آن راه برای کسی خوب است که با کد قالب راحت است. اما اگر مدیر یک سایت خبری، یک فروشگاه کوچک یا وبلاگ شخصی هستید و نمی‌خواهید به فایل‌های قالب دست بزنید، یک افزونهٔ آماده همان کار را با یک صفحهٔ تنظیمات انجام می‌دهد.

افزونهٔ «نرخ ارز نِت اَرز» (NetArz FX Rates) متن‌باز است و نرخ دلار، یورو، درهم، لیر و ارزهای دیگر را از API نرخ ارز نِت اَرز می‌گیرد؛ همان عددهایی که روی تابلوی نرخ ارز می‌بینید. در این راهنما از نصب تا اولین نرخ روی صفحه را قدم‌به‌قدم می‌رویم و می‌گوییم هر گزینهٔ تنظیمات چه می‌کند.

پیش از نصب: یک اپ و یک کلید

1. در نِت اَرز ثبت‌نام کنید و به پنل «API نرخ ارز» بروید. یک اپ بسازید و دامنهٔ سایت وردپرسی خودتان را رویش بنویسید.
2. کلید fx-ntz-v1-… را کپی کنید. این کلید فقط همان یک بار کامل نمایش داده می‌شود.
3. مالکیت دامنه را تأیید کنید. فایل آماده را از صفحهٔ اپ دانلود کنید و بدون ویرایش در پوشهٔ .well-known ریشهٔ سایت بگذارید، یا رکورد TXT بسازید. تایپ دستی کد تأیید رایج‌ترین علت تأیید نشدن است.

طرح رایگان برای بیشتر سایت‌ها کافی است: فقط عضویت می‌خواهد و نرخ را با پانزده دقیقه تأخیر می‌دهد. چون افزونه کش دارد، در هر دورهٔ کش فقط یک درخواست می‌فرستد و سهمیهٔ روزانه عملاً پر نمی‌شود. جزئیات دو طرح در صفحهٔ طرح‌ها آمده است.

نصب از فایل ZIP

افزونه در مخزن افزونه‌های وردپرس (wordpress.org) نیست؛ آن را از گیت‌هاب می‌گیرید. به صفحهٔ netarz/netarz-fx-wordpress بروید، دکمهٔ سبز «Code» را بزنید و «Download ZIP» را انتخاب کنید. بعد در پیشخوان وردپرس از «افزونه‌ها ← افزودن ← بارگذاری افزونه» همان فایل را بدهید و افزونه را فعال کنید. فایل را از هیچ سایت دیگری نگیرید؛ نسخهٔ رسمی فقط همین مخزن است.

افزونه به وردپرس ۶ یا تازه‌تر و PHP ۷.۴ یا تازه‌تر نیاز دارد. ترجمهٔ فارسی همراهش است و اگر زبان سایت فارسی باشد، همهٔ برچسب‌ها فارسی نمایش داده می‌شوند.

صفحهٔ تنظیمات، گزینه به گزینه

بعد از فعال‌سازی، در «تنظیمات ← نرخ ارز نِت اَرز» این گزینه‌ها را می‌بینید:

بعد از ذخیره، دکمهٔ «آزمایش اتصال» را بزنید. اگر همه‌چیز درست باشد، نام اپ، طرح و تعداد درخواست باقی‌ماندهٔ امروز را می‌بینید. اگر نِت اَرز درخواست را نپذیرد، افزونه دقیقاً همان IPی را نشان می‌دهد که ما از سرور شما دیده‌ایم. همان را در «IPهای مجاز» اپ بگذارید؛ IP دامنه، مثلاً IP کلادفلر، ملاک نیست.

سه شورت‌کد برای سه جای صفحه

نرخ را با کد کوتاه (شورت‌کد) در نوشته، برگه یا هر جای دیگری که شورت‌کد می‌پذیرد بگذارید:

[netarz_rate currency="usd"]
[netarz_rate currency="eur" field="buy" show_name="1"]
[netarz_rates currencies="usd,eur,aed,try" fields="buy,sell"]

• netarz_rate یک عدد را داخل متن می‌گذارد، مثل «دلار امروز … تومان». با field می‌گویید کدام نرخ: sell (فروش، پیش‌فرض)، buy (خرید) یا mid (میانگین). show_name="1" نام ارز را هم کنار عدد می‌آورد.
• netarz_rates جدول چند ارز را می‌سازد. کدها را با کاما جدا کنید و با fields بگویید کدام ستون‌ها نمایش داده شوند.
• ارزی مثل دینار عراق که قیمتش برای ۱۰۰ واحد است، خودکار با توضیح «برای ۱۰۰ واحد» نمایش داده می‌شود تا خواننده اشتباه نکند.

در قالب‌های بلوکی (ویرایشگر گوتنبرگ)، بلوک «کد کوتاه» را اضافه کنید و شورت‌کد را داخلش بنویسید.

ابزارک ستون کناری

اگر می‌خواهید تابلوی نرخ در همهٔ صفحه‌ها کنار محتوا باشد، از «نمایش ← ابزارک‌ها» ابزارک «نرخ ارز نِت اَرز» را به ستون کناری اضافه کنید. عنوان، فهرست ارزها و ستون‌های نمایش را همان‌جا تعیین می‌کنید. ابزارک و شورت‌کدها از یک نسخهٔ کش‌شده می‌خوانند، پس گذاشتن هر دو در یک صفحه درخواست اضافه‌ای نمی‌فرستد.

از سرور یا از مرورگر؟

این مهم‌ترین تصمیم تنظیمات است. در حالت سرور، سایت شما هر چند دقیقه یک بار کل تابلو را می‌گیرد و همهٔ بازدیدکننده‌ها همان را می‌بینند. کلید هرگز به مرورگر نمی‌رسد، عدد در خود HTML صفحه چاپ می‌شود و گوگل هم آن را می‌بیند. شرطش این است که IP خروجی هاست ثابت باشد و در پنل ثبتش کنید.

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

وقتی به‌جای نرخ پیام خطا می‌بینید

• «نرخ در دسترس نیست»: یا کلید وارد نشده، یا هنوز هیچ نرخی گرفته نشده. «آزمایش اتصال» علت دقیق را می‌گوید.
• domain_not_verified: تأیید مالکیت دامنه در پنل کامل نشده.
• origin_required یا ip_not_allowed: IPی را که «آزمایش اتصال» نشان می‌دهد به اپ اضافه کنید، یا حالت مرورگر را انتخاب کنید.
• origin_not_allowed در حالت مرورگر: دامنه‌ای که سایت رویش باز می‌شود روی اپ نیست. رایج‌ترینش نسخهٔ www است؛ آن را به «دامنه‌های اضافی» اضافه کنید.

یک رفتار دیگر افزونه را هم بدانید: اگر وب‌سرویس یک لحظه جواب ندهد، افزونه آخرین نرخ سالمی را که گرفته نشان می‌دهد، نه یک جای خالی، و یک دقیقه بعد دوباره تلاش می‌کند. اگر هنوز نمی‌دانید عدد تابلو از کدام بازار می‌آید، چهار نرخ ارز در ایران را ببینید.

سه جای رایج برای نرخ، و کاری که افزونه نمی‌کند

بیشتر سایت‌ها نرخ را در یکی از این سه جا لازم دارند، و برای هرکدام یک شورت‌کد کافی است:

• داخل متن یک نوشته. مثلاً در راهنمای خرید یک اشتراک خارجی: «با نرخ امروز دلار، [netarz_rate currency="usd"]، هزینهٔ ماهانه تقریباً …». عدد هر بار که کش تازه شود، خودش عوض می‌شود و نوشتهٔ قدیمی با نرخ کهنه نمی‌ماند.
• برگهٔ «نرخ ارز امروز». یک برگه با [netarz_rates currencies="usd,eur,gbp,aed,try,cny" fields="buy,sell,mid"] و چند جمله توضیح دربارهٔ این‌که عددها از کدام بازارند. در حالت سرور، عددها در HTML همان برگه چاپ می‌شوند و موتور جست‌وجو آن‌ها را می‌بیند.
• ستون کناری همهٔ صفحه‌ها. ابزارک با سه یا چهار ارز پرکاربرد. بیشتر از این، ستون کناری را شلوغ می‌کند و روی موبایل پایین صفحه می‌رود.

یک چیز را هم روشن بگوییم: این افزونه نرخ را نمایش می‌دهد و به قیمت محصول‌های ووکامرس دست نمی‌زند. اگر قیمت کالاها را به دلار وارد می‌کنید و می‌خواهید هنگام نمایش به تومان تبدیل شوند، کدش را با فیلتر ووکامرس در نرخ ارز در وردپرس و ووکامرس نوشته‌ایم. آن‌جا هم تابع از همان کش استفاده می‌کند، پس با افزونه تداخلی ندارد.

اگر سایت چندزبانه دارید، گزینهٔ «ارقام» را روی «مطابق زبان سایت» بگذارید تا نسخهٔ فارسی رقم فارسی و نسخهٔ انگلیسی رقم لاتین نشان بدهد. برای سایتی که فقط فارسی است ولی جدول نرخ را برای کپی در اکسل می‌خواهد، رقم لاتین انتخاب بهتری است.

کد افزونه باز است

افزونه با مجوز GPL منتشر شده و همهٔ کدش در گیت‌هاب است: هر مقداری که چاپ می‌شود escape شده، کلید فقط در تنظیمات وردپرس ذخیره می‌شود و با حذف افزونه، تنظیماتش هم پاک می‌شود. لینک منبع زیر نرخ‌ها پنهان نیست و هر وقت خواستید از تنظیمات خاموشش کنید؛ توسعه‌دهنده‌ها می‌توانند با فیلتر netarz_fx_show_attribution هم این کار را بکنند. اگر فقط یک شورت‌کد بسیار کوچک برای functions.php می‌خواهید، فایل wordpress/netarz-fx-snippet.php در مخزن نمونه‌کدها همین است.

ایراد یا پیشنهاد دربارهٔ افزونه را در بخش Issues همان مخزن بنویسید. برای اپ، کلید و تأیید دامنه از پنل تیکت بزنید. بقیهٔ کدهای متن‌باز ما، از نمونه‌کد PHP و پایتون تا نمونه‌های وب‌سرویس هوش مصنوعی، در صفحهٔ کدهای متن‌باز نِت اَرز جمع شده‌اند. اگر سایتتان هنوز هاست ندارد یا دنبال سروری با IP ثابت هستید، دامنه و هاست خارجی نقطهٔ شروع خوبی است.