مقدمة بسيطة حول استخدام Quicktags API في الووردبريس

مقدمة بسيطة حول استخدام Quicktags API في الووردبريس
منذ الإصدار 4.0 للوردبرس تم إضافة 18 واجهة برمجية (API) هذه الواجهات البرمجية (API) أضافة مميزات مهمة جداً، لتخدم جوانب متعددة في نظام الوردبرس وتساعد نظام الوردبرس على أن يكون نظام إدارة المحتوى الأكثر مرونة في العالم.

واحدة من هذه الواجهات البرمجية (API) هي Quicktags، هذه الواجهة البرمجية تسمح لمطوري القوالب والإضافات على حد سواء من إضافة أزرار جديدة الى محرر النصوص في وضع التحرير النصي ( أو كما يسميه البعض وضع HTML ). في هذا المقالة سوف نتعرف على ماهي Quicktags وكيفية استخدامها لإنشاء أزرار جديدة لمحرر النصوص في وضع التحرير النصي.

ماهي Quicktags ؟

نظام الوردبرس تطور بشكل كبير ولم يعد نظام تدوين عادي، واصبح في معظم الاحيان يستخدم كنظام إدارة محتوى CMS، وبالتالي فإن نظام الوردبرس وفر أدوات تسمح للمستخدمين من تحرير المحتوى بسهولة وكفاءة. لهذا السبب يأتي نظام الوردبرس مع محرر النصوص TinyMCE، واحد من أفضل محررات النصوص (WYSIWYG ) على الإطلاق، ويمكن القول انه محرر النصوص الانسب لنظام الوردبرس. يجعل محرر النصوص TinyMCE تجربة تحرير النص سهلة وغير معقدة، ويمكن المستخدم من معاينة شكل النص قبل نشره.

لكن بعض المستخدمين لا يفضلون معاينة شكل النص اثناء التحرير. ويفضلون على ذلك تحرير الشفرة المصدرية للمقالة الذي يمكنهم من السيطرة الكاملة على محتوى المقالة. او ربما يقوم المستخدم بتحرير النص ومعاينة شكل النص أي في وضع التحرير “مرئي” ومن ثم يقوم بالتعديل على الشفرة المصدرية للمقالة في وضع التحرير “نص” وهنا يأتي دور وضع التحرير النصي او تحرير وسوم HTML عند تفعيل وضع التحرير “نص” يتم عرض شفرة HTML للمقالة فقط، بدون اي ادوات تحرير اضافية.

في وضع HTML، توجد هناك أزرار في اعلى المحرر هذه الأزرار تدعى أزرار Quicktag، والتي تسمح للمستخدم من إضافة وسوم HTML دون الحاجة الى الرجوع للوضع المرئي. وحتى يتمكن المطورين من التحكم بهذه الازار وإنشاء ازرار خاصة بهم تم إضافة الواجهة البرمجية Quicktags API التي تتيح للمطورين التحكم بهذه الأزرار بكل سهولة.

كيفية استخدام
Quicktags API

إن استخدام
Quicktags API سهل للغاية ويعود الفضل الى ملف quicktags.js فهو يختزل الكثير من الأسطر البرمجية في دالة واحدة فقط، كل ما عليك هو استخدام دالة ()QTags.addButton

اذا كنت تفضل كتابة أكواد Javascript في ملف منفصل ( وهو الاستخدام الموصي به ) استخدم الكود التالي :

<?php

function load_my_quicktags() {

    // Load the `my-quicktags.js` file with the `QTags.addButton()` functions.
    wp_enqueue_script( 'my-quicktags', 'http://the.url/to/my-quicktags.js', array( 'quicktags' ) );
}
add_action( 'admin_enqueue_scripts', 'load_my_quicktags' );

?>

لكن اذا كنت تفضل كتابة اكواد الجافاسكربت ضمن ملف php فقم باستخدام الكود التالي :

<?php

function load_my_quicktags_inline() {

    if ( wp_script_is( 'quicktags' ) ) { ?>
    
        <script>
        
            // The `QTags.addButton()` functions go here.
        
        </script>
    
    <?php }

}

add_action( 'admin_print_footer_scripts', 'load_my_quicktags_inline' );

?>

الأمر سهل للغاية، أليس كذلك ؟ و لاحظ اننا قمنا باستخدام الاكشن admin_print_footer_scripts هذه المرة.

التعامل مع دالة ()QTags.addButton

هناك ثمانية معاملات (Parameters) يمكن التحكم فيها مع دالة ()QTags.addButton وهي كالتالي :

QTags.addButton( 
    id, 
    display, 
    arg1, 
    arg2, 
    access_key, 
    title, 
    priority, 
    instance
);

• ID ( نصي، مطلوب ): الاسم الفريد للزر، والذي يتم إسناده الى خاصية id في وسم HTML لأزرار Quicktag. ( ملاحظة : يقوم نظام الوردبرس بإضافة '_qt_content' قبل أسم الـ ID لكل الأزرار بشكل تلقائي )
• display ( نصي، مطلوب ): الاسم الذي سيظهر على الزر.
• arg1 ( نص او دالة، مطلوب ): وسم البداية الذي سيتم إضافته عند النقر على الزر، او بإمكانك إضافة دالة يتم استدعاؤها عند النقر على الزر.
• arg2 (نصي، اختياري): وسم الإغلاق الذي سيتم اضافته بعد وسم arg1.
• access_key ( نصي، اختياري ): مفتاح الوصول للزر الذي يمكنك من الوصول الى ازرار اخرى من أزرار Quicktag.
• title ( نصي، أختياري): العنوان التوضيحي الذي سيظهر عند تمرير مؤشر الماوس على الزر والذي سيكون على خاصية title للزر بالنسبة لكود HTML.
• priority ( رقمي، اختياري ): من هذا المعامل يمكنك ترتيب عرض الازرار، من 1 الى 9 للمكان الأول، من 11 الى 19 للمكان الثاني، من 21 الى 29 للمكان الثالث، وهكذا.
• instance (نصي، اختياري): لإظهار زر واحد فقط في حالة كان هناك أكثر من زر متشابه. (إذا لم تعيين قيمة، سيتم إضافة الزر الى كافة الحالات )

مثال بسيط : إنشاء أزرار بشكل مبسط

اذا لم تكن لديك خلفية مسبقة عن لغة Javascript قد تبدو لك إنشاء زر Quicktags معقد نوعا ما، لكن لا تقلق من المثال التالي ستعرف ان الامر سهل للغاية ولن تحتاج لكتابة أسطر برمجية كثيرة لإنشاء زر Quicktag.

في هذا المثال سنقوم بشرح كيفية إضافة زرين، الاول لفتح وسم shortcode والثاني لإغلاق الوسم. وسنقوم باستخدام الكود التالي :

QTags.addButton(
    'info-box', 
    'info box', 
    '[infobox]', 
    '[/infobox]'
);

لاحظ الامر سهل للغاية ؟ في البداية عرفنا الـ ID للزر وهو info-box ثم قمنا بإضافة أسم للزر info box ثم عند النقر على الزر يقوم بطباعة [infobox]. لاحظ انك لست بحاجة الى اضافة قيمة الى المعامل arg2 اذا لم تكن بحاجة الى استخدام وسم إغلاق، مثل المثال التالي :

QTags.addButton(
    'signature', 
    'signature', 
    '[signature]'
);

لقد قمنا بإنشاء زر بشكل مبسط وهذا ادنى ما يمكنك معرفته لإنشاء زر Quicktag.

مثال متقدم : استدعاء دالة عند النقر على الزر.

في المثال السابق قمنا بإنشاء زر quicktag بسيط، فقط يقوم بإدراج وسم shortcode مع وسم إغلاقه، وبالتأكيد لا يتم أنشاء جميع الأزرار بهذه الطريقة البسيطة. قد تحتاج الى انشاء ازرار أكثر تعقيداً وبعمليات أكثر. ولتنفيذ عمليات اكثر عند النقر على الزر يتم الأمر عبر استدعاء دالة Javascript تنفذ عند حدث النقر على الزر.

سوف نقوم باستعراض مثال بسيط لهذا، لكن الخيار مفتوح لخيالك لأنشاء ازرار Quicktag اكثر تعقيداً باستخدام دوال الـ JavaScript.

حسناً، سوف نقوم بعمل مثالين. الأول عبارة عن زر يقوم بإظهار نافذة منبثقة alert:

QTags.addButton(
    'alert', 
    'alert', 
    my_alert
);

function my_alert() {
    alert( 'Hello Quicktag!' );
}

وكما تلاحظ، النافذة المنبثقة تقوم بإظهار رسالة مكتوب عليها Hello Quicktag! حسناً، في المثال التالي سوف نتعامل مع الموجه prompt

QTags.addButton( 
    'my_prompt', 
    'alert', 
    my_prompt
);

function my_prompt() {
    var my_class = prompt( 'Enter a class name:', '' );
    
    if ( my_class ) {
        QTags.insertContent('<div class="' + my_class +'"></div>');
    }
}

قد يبدو المثال السابق معقد نوع ما: فهو يطلب منك كتابة اسم الفئة class، ومن ثم طباعة div مع الفئة class التي حددتها.

الخاتمة

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

ما هو رأيك حول API Quicktags ؟ هل تفكر في استخدامها، أو هل لديك أي شيء اخر تود اضافته لأثراء هذه المقالة ؟ أخبرنا برأيك من خلال التعليق أدناه. وإذا أعجبتك هذه المقالة، لا تنسى مشاركتها مع أصدقائك !