تصميم مبدّلات عملات مخصصة باستخدام ملفات القوالب

تحتاج العديد من المواقع والقوالب إلى مبدّل عملات يتناسب مع تصميمها المخصص. تعلّم كيفية بناء مبدّل العملات الخاص بك باستخدام PHP.

فهم قوالب PHP لمبدّلات العملات

إليك مثال أساسي لقالب PHP لمبدّل عملات:

<?php
/**
 * @var string $css_classes
 * @var string $format
 * @var string $selected_currency
 * @var string[] $currencies
 */
?>
<div class="<?php echo esc_attr( $css_classes ) ?>">
	<ul>
		<li class="wcml-cs-active-currency">
			<a class="wcml-cs-item-toggle"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $selected_currency, $format ) ); ?></a>
			<ul class="wcml-cs-submenu">
				<?php foreach ( $currencies as $currency ) : ?>
					<?php if ( $currency != $selected_currency ) : ?>
						<li>
							<a rel="<?php echo esc_attr( $currency ); ?>"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ) ); ?></a>
						</li>
					<?php endif; ?>
				<?php endforeach; ?>
			</ul>
		</li>
	</ul>
</div>

يقوم هذا القالب بما يلي:

• يفتح وسوم HTML للحاوية <div> و <ul> التي تهيكل المبدّل
• يعرض العملة المحددة
• يمر عبر العملات المتاحة
• يُخرج عنصر قائمة HTML <li> لكل عملة (باستثناء العملة المحددة حالياً)
• يُخرج روابط قابلة للنقر لتبديل العملة

الآن، دعنا نستعرض كيفية إنشاء مثل هذه القوالب لمبدّلات العملات الخاصة بك.

إضافة قالب مبدّل العملات إلى قالبك

يمكنك إضافة دليل إلى قالبك ليحتوي على قوالب مبدّل العملات المخصصة.

• إذا كنت تطور قالباً تخطط لتوزيعه أو بيعه، فقم بتضمين القوالب مباشرة في القالب. بهذه الطريقة، سيتمكن جميع مستخدمي قالبك من استخدام مبدّلات العملات التي تنشئها.
• إذا كنت تخصص قالباً موجوداً، فأنشئ القوالب داخل قالب ابن. يمنع هذا الكتابة فوق تغييراتك عند تحديث القالب الأب.

استخدم بنية المجلدات التالية لقوالب المبدّل المخصصة الخاصة بك:

my-theme/wpml/templates/currency-switchers/my-template

لبناء هذه البنية:

1. داخل قالبك (أو القالب الابن)، أنشئ مجلداً باسم wpml. تستخدم إضافة WPML Multilingual & Multicurrency for WooCommerce اصطلاح التسمية هذا لأنها تعمل مع WPML.
2. داخل wpml، أنشئ مجلداً باسم templates.
3. داخل templates، أنشئ مجلداً باسم currency-switchers.
4. داخل currency-switchers، أنشئ مجلداً فرعياً واحداً لكل مبدّل مخصص تبنيه—على سبيل المثال، my-template.

داخل كل مجلد مبدّل مخصص (على سبيل المثال، my-template)، ستحتاج إلى:

• template.php — مطلوب. هذا هو ملف قالب PHP الرئيسي الخاص بك.
  
• config.json — مطلوب. يوفر هذا الملف لـ WCML بيانات وصفية حول مبدّل العملات الخاص بك.
  
• أي ملفات CSS أو JS اختيارية — قم بتضمينها إذا كان المبدّل الخاص بك يستخدم تنسيقاً أو تفاعلاً مخصصاً.

تصميم ملف template.php

يحدد ملف template.php تخطيط وسلوك مبدّل العملات المخصص الخاص بك. يستخدم لغة PHP القياسية ويُخرج كود HTML الذي سيتم عرضه في الواجهة الأمامية.

داخل قالبك، يمكنك استخدام المتغيرات التالية التي توفرها WPML Multilingual & Multicurrency for WooCommerce:

• $css_classes (سلسلة نصية): فئات CSS المطبقة على الحاوية الرئيسية.
• $currencies (مصفوفة): قائمة بالعملات المتاحة.
• $selected_currency (سلسلة نصية): العملة المحددة حالياً.
• $format (سلسلة نصية): سلسلة نصية تحدد كيفية عرض العملة.
• WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ): طريقة ثابتة تُستخدم لتنسيق وعرض كل تسمية عملة.

عند كتابة قالبك، اتبع أفضل ممارسات واجهة مستخدم WordPress لضمان إمكانية الوصول إلى المبدّل الخاص بك واتساقه مع عناصر القالب الأخرى. تأكد أيضاً من تخطي (escape) المخرجات الديناميكية باستخدام دوال مثل esc_attr() و wp_kses_post() للحفاظ على أمان الكود الخاص بك.

ضبط الخيارات في ملف config.json

يجب أن يتضمن كل مبدّل عملات مخصص ملف config.json. يوفر هذا الملف لـ WPML Multilingual & Multicurrency for WooCommerce معلومات أساسية حول مبدّل العملات الخاص بك، مثل اسمه وأي أصول CSS أو JS يحتاجها.

الحقول المطلوبة

يجب أن يحدد الملف اسم مبدّل العملات:

{
  "name": "My custom switcher"
}

لا تحتاج إلى إضافة بادئة للاسم. ستتولى WPML Multilingual & Multicurrency for WooCommerce التعامل مع ذلك تلقائياً بناءً على القالب أو الإضافة التي ينتمي إليها المبدّل.

الحقول الاختيارية

بالإضافة إلى الاسم المطلوب، يمكنك تضمين حقلين اختياريين:

• css: قائمة بملفات CSS لتحميلها من مجلد القالب الخاص بك. افتراضياً، ستقوم WPML Multilingual & Multicurrency for WooCommerce بإدراج جميع ملفات .css الموجودة في مجلد القالب تلقائياً، ولكن يمكنك تجاوز هذا السلوك باستخدام هذا الحقل.

"css": ["style.css", "responsive.css"]

• js: قائمة بملفات JavaScript لتحميلها من مجلد القالب الخاص بك. استخدم فقط JavaScript عادي (plain JavaScript) ما لم يكن قالبك أو إضافتك تتضمن بالفعل مكتبة JS مثل jQuery.

"js": ["script.js", "click-handler.js"]

إليك ملف config.json كامل يتضمن جميع الحقول:

{
"name":           "My custom Vertical List",
"css":            ["style.css"],
"js":             ["script.js"],
}

إضافة قوالب مبدّل العملات إلى مجلد uploads

يمكنك أيضاً تخزين قوالب مبدّل العملات المخصصة في مجلد uploads الخاص بـ WordPress. هذا مفيد إذا كنت ترغب في الحفاظ على القوالب آمنة من تحديثات القالب أو الإضافة.

ضع قوالب المبدّل الخاصة بك في المسار التالي:

../wp-content/uploads/wpml/templates/currency-switchers/

تقوم إضافة WPML Multilingual & Multicurrency for WooCommerce بفحص هذا المسار تلقائياً بحثاً عن قوالب مبدّل العملات.

إضافة قوالب مبدّل العملات إلى إضافة

إذا كنت تبني إضافة وترغب في تضمين مبدّلات عملات مخصصة، فأنت بحاجة إلى إخبار WPML Multilingual & Multicurrency for WooCommerce بمكان العثور عليها.

استخدم المرشِّح wcml_cs_directories_to_scan لتسجيل دليل القالب. أضف هذا الكود إلى ملف الإضافة الرئيسي الخاص بك:

function myplugin_wcml_cs_dirs_to_scan( $dirs ) {
    $folder_name = basename( dirname( __FILE__ ) );
    $dirs[] 	= trailingslashit( WP_PLUGIN_DIR ) . $folder_name . '/templates/';
    return $dirs;
}
add_filter( 'wcml_cs_directories_to_scan', 'myplugin_wcml_cs_dirs_to_scan' );

ستقوم WPML Multilingual & Multicurrency for WooCommerce بعد ذلك بفحص مجلد templates داخل إضافتك. تحتاج إلى وضع كل مبدّل عملات مخصص في مجلده الفرعي الخاص، هكذا:

my-plugin/templates/my-template/

مثال كامل: مبدّل عملات مخصص

يوضّح هذا المثال كيفية إنشاء مبدّل عملات كامل بمجلده الخاص، وقالبه، وملف تكوينه، وتنسيقاته الاختيارية.

1. في قالبك أو القالب الابن، أنشئ المجلد التالي:

wpml/templates/currency-switchers/custom-currency-switcher/

1. أنشئ ملف config.json داخل المجلد:

{
"name": "Custom currency switcher"
}

1. أنشئ ملف template.php لعرض العملة المحددة وقائمة بالعملات الأخرى:
   

<?php
/**
* @var string $css_classes
* @var string $format
* @var string $selected_currency
* @var string[] $currencies
*/
?>
<div class="<?php echo esc_attr( $css_classes ) ?>">
	<ul>
		<li class="wcml-cs-active-currency">
			<a class="wcml-cs-item-toggle"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $selected_currency, $format ) ); ?></a>
			<ul class="wcml-cs-submenu">
				<?php foreach ( $currencies as $currency ) : ?>
					<?php if ( $currency != $selected_currency ) : ?>
						<li>
							<a rel="<?php echo esc_attr( $currency ); ?>"><?php echo wp_kses_post( WCML_Currency_Switcher_Template::get_formatted_price( $currency, $format ) ); ?></a>
						</li>
					<?php endif; ?>
				<?php endforeach; ?>
			</ul>
		</li>
	</ul>
</div>

1. إذا كنت ترغب في تخصيص المظهر، أضف ملف style.css:

.your-custom-class li {
  list-style: none;
  float: left;
  margin: 0 3px;
}

استخدام مبدّلات العملات المخصصة في قوالب PHP

بمجرد إنشائك لمبدّل عملات مخصص، يمكنك استخدامه في قوالب PHP الخاصة بك عن طريق استدعاء الإجراء wcml_currency_switcher.

do_action('wcml_currency_switcher', array(
  'format' => '%name% (%symbol%)',
  'switcher_style' => 'twenty-seventeen-my-custom-switcher'
));

تعتمد قيمة switcher_style على شيئين: موقع المبدّل والاسم المحدد في ملف config.json الخاص به. تقوم WCML بإنشاء المعرّف النصي للرابط تلقائياً باستخدام هذا التنسيق:

موقع مبدّل العملات المخصص	كيفية إنشاء المعرّف النصي للرابط
مجلد القالب	المعرّف النصي للرابط للقالب + اسم المبدّل المنقّح
مجلد الإضافة	المعرّف النصي للرابط للإضافة + اسم المبدّل المنقّح
مجلد «uploads»	«uploads-» + اسم المبدّل المنقّح

لنفترض إذن ما يلي:

• قالبك هو Twenty Seventeen
• يحتوي ملف config.json لمبدّل العملات الخاص بك على:

{ "name": "My custom switcher" }

عندها سيكون المعرّف النصي للرابط الذي تم إنشاؤه هو:

twenty-seventeen-my-custom-switcher

استخدم هذا كقيمة لـ switcher_style في مقتطف الكود أعلاه.