إطار العمل Yii2: أدوات مهمّة - Select2 و Modal

عندما تريدُ بناء موقعٍ فلا بدّ من استعمال كثيرٍ من الأدوات التي تسهّل على المستخدم النهائي التعامل مع الموقع دون أن يُكثر من الضغط على الأزرار أو التنقّل بين صفحاتٍ لا داعٍ لها أو استغراق الوقت في البحث عن شيءٍ معيّن أو غيرها من الأمور.

إنّ استعمالك لأدواتٍ جاهزةٍ قام غيرك ببرمجتها مسبقاً ليس بالأمر المعيب ولا يُنقص من احترافيتك شيء طالما أنّك فاهمٌ لما تستخدم وقادرٌ على بناء أدواتٍ مشابهةٍ لتلك الأدوات الجاهزة التي تستعملها، فكما يُقال لستَ بحاجةٍ لإعادة صناعة العجلة من جديد ... يكفي أن تستخدمها عن فهم!

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

سنتناول الأداتَين:

• Select2
• Modal

 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

الأداة Select2:

هي عبارة عن قائمةٍ منسدلةٍ فيها مربّع للبحث، حيث تستطيع أن تكتب فيه بعض المحارف لفلترة العناصر الموجودة في القائمة وإرجاع العناصر التي تحوي تلك المحارف التي قمتَ بكتابتها، ممّا يسهّل عليكَ الوصول للعناصر التي تريدها بدلاً من تصفّح كامل العناصر.

هَب مثلاً أنّك تريد اختيار دولةٍ من قائمة الدول (والتي يفوق عددها الـ 200 دولة)، فلن تكون بحاجةٍ للمرور على كلّ الدول لتصل للدولة التي تريدها (ويزيد الأمر صعوبةً عندما لا تكون هذه الدول مرتّبةً ترتيباً هجائياً!)، عندها ستكتفي بكتابة حرفين أو ثلاثة مثلاً، فستتقلّص النتائج لتشمل فقط الدول التي فيها الأحرف المكتوبة.

لا توفّر Yii2 الأداة Select2 بشكلٍ مسبق، لذلك سنقوم بإضافتها للموقع عن طريق الـ composer.

يوجد العديد من أدوات Select2 الجاهزة والمبرمجة مسبقاً من قِبَل مطوّرين حول العالم، وكذلك الحال مع معظم الأدوات تقريباً، ولكن سنقوم بإضافة الأداة التي قام فريق Krajee بإنشائها، وهو فريقٌ قام بإنشاء الكثير من الأدوات المتوافقة مع Yii2، وهذا رابط موقعهم إذا أردتَ التعرّف على أدواتهم أكثر:

 http://demos.krajee.com/

سنقوم بتنفيذ التعليمة التالية لإضافة الأداة إلى الموقع الخاص بنا:

composer require kartik-v/yii2-widget-select2 "@dev"

ومن أجل استخدامها سنقوم بعمل use لها في صفحة الـ view التي نريدها:

use kartik\select2\Select2;

نستطيع استخدام الأداة باعتبارها إحدى attributes الـ model، فلنفرض أنّه يوجد لدينا model اسمه sUser، ونريد أن نعرض في الأداة select2 الخاصية username من الـ model السابق، فنقوم بعرضها كالتالي:

<?php $form = ActiveForm::begin() ?>

<?= $form->field($user, 'username')->widget(Select2::className(), [
	'data' => ArrayHelper::map(Users::find()->all(), 'id', 'username'),
	'options' => ['placeholder' => 'Select user…']
]); ?>

<?php ActiveForm::end() ?>

 

 

كنّا من قبل عندما نريد وضع drop down list نفوم باستدعاء التابع dropDownList ونربطه مع التابع field:

$form->field( … )->dropDownList( … )

أمّا هنا فقمنا باستدعاء التابع widget الذي يقوم بوضع الـ widget التي نمرّرها في الوسيط الأول، أما الوسيط الثاني فهو مصفوفة من الخيارات أو الإعدادات المتعلقة بالـ widget.

الخاصية data نقوم فيها بوضع العناصر التي تحتويها الأداة select2، وفي المثال السابق وضعنا العناصر على أنّها القيمة username المُستدعاة من الجدول users (عن طريق استدعاء التابع all من الـ Users model).

ومن أجل الربط بين حقل id وحقل username قمنا باستدعاء التابع map من الكلاس ArrayHelper، والذي يفيدنا بجعل الحقل id هو الـ value للعنصر item في القائمة المنسدلة، بينما الحقل username هو الـ string التي يتم عرضها في العنصر، وكأنّ الكود السابق يطابق تماماً كود Html التالي:

<select>
	<option value='1'>Salam</option>
	<option value='2'>Ahmad</option>
	<option value='3'>Akram</option>
</select> 

وإذا أردنا أن تكون الـ string المعروضة في العناصر عبارة عن قيمة أكثر من حقل سويةً فسيتحول الوسيط الثالث في التابع map إلى function نقوم من خلاله بإرجاع القِيَم التي نريدها:

<?= $form->field($user, 'username')->widget(Select2::className(), [
	'data' => ArrayHelper::map(Users::find()->all(), 'id', function($data){
        return $data->username . ' (' . $data->country . ' - ' . $data->city . ')';
    }),
	'options' => ['placeholder' => 'Select user…']
]); ?>

حيث أنّ الـ $data تمثّل الـ object الحالي من مصفوفة الـ objects التي ترجعها التعليمة find()->all() المُستدعاة من الـ model.

عندما تكتب بضعة أحرف في مربع البحث سترى أنّ النتائج يتم فلترتها تبعاً للأحرف التي كتبتها.

ويمكنك أيضاً أن تختار أكثر من عنصر بنفس الوقت، وذلك عن طريق تفعيل الخيار multiple:

<?= $form->field($user, 'username')->widget(Select2::className(), [
	'data' => ArrayHelper::map(Users::find()->all(), 'id', function($data){
        return $data->username . ' (' . $data->country . ' - ' . $data->city . ')';
    }),
	'options' => ['placeholder' => 'Select user…', 'multiple' => true]
]); ?>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

الأداة Modal:

من الأدوات المهمّة أيضاً في كل موقعٍ ولا غنى عنها هي أداة الـ Modal المعروفة في الـ Bootstrap كنافذة منبثقة تعرض محتوى معيّن يتم التركيز عليه دوناً عن المحتوى الموجود في الصفحة الأساسية.

تتوفّر الأداة Modal في الـ Yii2 بشكلٍ تلقائي ولا حاجة لإضافتها، ومن أجل أن نعرضها فنحن بحاجةٍ للقيام بعدّة خطوات كالتالي:

الـ Modal تتكوّن من قسمَين أساسييَن؛ الأول هو البنية الأولية للـ Modal والتي تحوي العنوان والـ container الذي يتم عرض المحتوى فيه، والقسم الثاني هو المحتوى، والذي -غالباً- يكون عبارة عن صفحة view مستقلّة يتم عرضها بشكلٍ ضمني.

لذلك نحن بحاجةٍ لإنشاء صفحة view لنضع فيها المحتوى الذي نريده، وعند الضغط على زرّ معيّن سنقوم بعرض الـ Modal (أي نقوم بإظهاره في الشاشة)، وبنفس الوقت سنقوم بجلب المحتوى لعرضه في جسم الـ Modal.

ملاحظة: نستطيع الاستغناء عن صفحة الـ view التي تمثّل المحتوى، حيث يمكننا وضع المحتوى الذي نريده مباشرةً، ولكن نستخدم هذه الطريقة كي نتمكّن من التعامل بشكلٍ ديناميكي مع المحتوى، والذي يمكن أن يمثّل form مرتبط بـ object من model مثلاً، أو يمكن أن يمثّل معلوماتٍ نجلبها من قاعدة البيانات اعتماداً على id، أو ما إلى ذلك.

 

الخطوة الأولى:

إنشاء صفحة view لعرض الـ Modal داخلها عند الضغط على زر:

ستكون صفحة بسيطة تحوي زرّاً وتحوي الكود الخاص ببنية الـ Modal الأساسية (والتي تكون مخفية حتى يتم الضغط على الزر فتصبح عندها ظاهرةً ومنبثقة على الشاشة).

<?php
use yii\bootstrap\Modal;
use yii\helpers\Html;
use yii\helpers\Url;
?>

<?= Html::button('Click me to show modal', 
	['value' => Url::to(['/users/show-modal', 'id' => 3]), 'class' => 'btn btn-primary', 'id' => 'show_modal_btn']
) ?>


//هذا الجزء لا يتم إظهاره في الصفحة إلا عند الضغط على الزر السابق

<?php
	Modal::begin([
		'header' => '<h3>The header of the modal</h3>',
		'id' => 'our_modal_id',
		'size' => 'modal-md'
    ]);

    //هذا الجزء يمثّل المكان الذي سيتم عرض المحتوى بداخله
    echo '<div id="our_modal_content"></div>';

    Modal::end();
?>

وضعنا زر من خلال الكلاس المساعد Html، وعند الضغط عليه سيتم تنفيذ الـ action التي قمنا بتمرير المسار إليها عن طريق التابع to من الكلاس المساعد أيضاً Url.

هذه الـ action سنقوم بإضافتها لاحقاً، والتي من خلالها سنقوم بإرجاع صفحة الـ view الأخرى التي ستتضمّن المحتوى الذي نريد عرضه (لاحظ أنّنا وضعنا قيمة للـ parameter الذي اسمه id ووضعنا قيمته 3، وهي قيمة عشوائية في مثالنا هنا، ولكنّها يمكن أن تكون أي قيمة، والهدف من وضعها هنا هو تبيان كيفية التعامل مع الـ parameter إن أردنا إرسالها إلى الـ Modal).

وضعنا id للزر لأنّنا سنقوم باستخدامه لاحقاً في كود jQuery كي نستطيع التقاط حدث الضغط على الزر لعرض المحتوى.

في الجزء الأسفل من الكود قمنا باستخدام الأداة Modal والتي فيها التابعَين begin و end، وبينهما قمنا بطباعة الـ div التي لها id (والتي سيتم تعبئتها بصفحة الـ view الأخرى التي فيها المحتوى).

 

الخطوة الثانية:

إنشاء صفحة الـ view التي فيها المحتوى:

سننشئ صفحة اسمها our-modal.php مثلاً، وسنضع فيها المحتوى البسيط التالي لطباعة اسم وإيميل مستخدم سنقوم بجلبه من قاعدة البيانات (المستخدم هو صاحب الـ id الذي قيمته تساوي 3؛ أي الـ id الذي قمنا بإرساله في الزر الذي سيتم الضغط عليه لعرض الـ Modal).

<p>The user that you have selected from database to show his/her name here in the modal is:</p> 
<h3><?= $user->username . ' - ' . $user->email ?> </h3>

المحتوى يمكن أن يكون أكثر تعقيداً مثل وضع form أو صور أو أي شيء آخر، ولكنّنا هنا للتبسيط اكتفينا بطباعة بعض القِيَم.

 

الخطوة الثالثة:

إضافة الـ action في الـ controller المسؤولة عن عرض صفحة الـ view ضمن الـ Modal:

في الخطوة الأولى عند إنشاء الزر جعلنا القيمة value تستدعي الـ action الذي أسميناه show-modal، والآن سنقوم بإنشاء هذه الـ action:

//In UsersController.php for example

public function actionShowModal($id){
	$user = Users::findOne($id);
	return $this->renderAjax('our-modal', ['user' => $user]);
}

هدفنا من جلب الـ user هو فقط لنبيّن أنّه يمكننا استخدام الـ parameters الموجودة في قيمة value الخاصّة بالزر الذي نريد الضغط عليه لعرض الـ Modal، وبالتالي إرسال هذه الـ parameters إلى الـ action التي نريد منها إرجاع صفحة الـ view التي تحوي المحتوى الخاص بالـ Modal.

هنا استخدمنا التابع renderAjax بدلاً من render، وذلك لأنّ عرض الـ Modal ما هو إلا إرسال Ajax request لجلب المحتوى.

 

الخطوة الرابعة:

وضع كود jQuery لالتقاط حدث الضغط على الزر من أجل عرض الـ Modal كخطوةٍ أولية (أي إظهاره في الشاشة)، ثمّ تعبئة محتوى الـ Modal من خلال الخاصية value في الزر التي تستدعي الـ action الموجودة في الـ controller.

اذهب إلى صفحة views/layout.php وضع فيها كود jQuery التالي (ضع الكود ضمن وسم <script> في نهاية الصفحة قبل إغلاق وسم body):

$(document).ready(function(){
	$('#show_modal_btn').ckick(function(){
		$('#our_modal_id').modal('show')
			.find('#our_modal_content')
			.load($(this).attr('value'));
    });
});

الكود السابق يعني أنّه عند الضغط على الزر الذي وضعناه في صفحة view الأولى، سيتم عرض البنية الأولية للـ Modal (من خلال التابع modal(‘show’))، وبعدها سيتم العثور على الـ div التي وضعناها بين تابعَي begin و end المُستدعيان من الأداة Modal، وسيتم تهيئة محتواها من خلال تنفيذ الـ action التي وضعناها في الخاصية value للزر.

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

من استخدامات هذه الأداة أن تعرضَ للمستخدم رسالة توكيد للقيام بحدثٍ معيّن مثل تأكيد حذف عنصر، أو مثلاً يمكنك استخدامها لتعبئة form ثانٍ ضمن form أساسي؛ فعلى سبيل المثال: إذا أردتَ تعبئة form يحوي العديد من الحقول، ومن ضمن هذه الحقول يوجد حقل لاختيار شركةٍ ما، ولكن ضمن الخيارات المتاحة لا توجد الشركة التي تريد اختيارها، فذلك يحتاج منك أن تذهب لتعبئة بيانات الشركة الجديدة، ومن ثمّ العودة إلى الـ form وتحديث الصفحة ربما من أجل عرض الشركة الجديدة، أمّا من خلال استخدام الـ Modal فيمكنك التوقف عن تعبئة الـ form الأساسي مؤقتاً ريثما تقوم بإدخال بيانات الشركة الجديدة من خلال النافذة المنبثقة والتي تجعل اهتمامك منصباً عليها، وعند الضغط على زر submit يمكنك من خلال تعليمة Ajax أن تجلب القيمة الجديدة وتضعها في الـ form الأساسي وتكمل تعبئته.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

تعرّفنا في هذا المقال على أداتَين من أكثر الأدوات استخداماً، ويوجد العديد من الأدوات الأخرى التي تسهّل عليك العمل، وأنصحك بزيارة رابط Krajee المذكور في بداية المقال للاطّلاع على الأدوات التي تمّت برمجتها مسبقاً، وأنصحك على وجه الخصوص أن تطّلع على الأداة editable من خلال الرابط التالي:

http://demos.krajee.com/editable

 

كلمات دليلية: modal select2 widgets yii yii2