الطريقة الصحيحة لعرض شيفرات برمجية على مدونات ووردبريس

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

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

لماذا عرض الشيفرات البرمجية أمر صعب

تحتاج لفهم سبب صعوبة عرض الشيفرات البرمجيّة إلى معرفة بعض أساسيّات HTML. لجعل بعض النصوص عريضة (Bold) فعليك وضعها بين وسوم. من أجل جعل الخط عريضًا مثل هذا النصّ فسأحتاج إلى كتابة <strong>الخط عريضًا</strong> في محرّر ووردبريس الخاص بي.

الأمور إلى الآن جيّدة ولكن الجزء الصعب هو: ماذا لو أردتُ أن أريك كيف قمتُ بعمل ذلك؟

في أيّ وقت أقوم بكتابة <strong> في المحرّر سيتمّ ترجمتها كشيفرة HTML برمجيّة، يعني هذا أن الوسم سوف يختفي وفي المقابل سيتم إظهار النص عريضًا.

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

عرض الشيفرات البرمجية

أفضل طريقة لعرض الشيفرات البرمجيّة بالشكل الصحيح هي تحويل الرموز ذات المعاني المميّزة إلى HTML Entities (كيانات HTML). ربّما تكون على درايّة أنّه أحيانًا قد تحتاج إلى كتابة &amp; بدلاً من علامة العطف & العاديّة لجعلها تظهر على نحوٍ صحيح. يرجع هذا إلى أنّ &amp; هي كيان HTML الخاص بعلامة العطف &.

لا يتمّ ترجمة كيانات HTML إلى شيفرات برمجيّة وإنّما يتم عرضها مثل نظيراتها من غير الكيانات. من أجل أن تريني كيف تنشئ خطّ عريض فعليك أن تكتب شيء يشبه ما يلي:

<strong>bold text</bold>

&lt; هي كيان HTML لعلامة أقل من (لاحظ اختصار lt) و&gt; كيان HTML لعلامة أكبر من، لهذا استخدمنا الاختصار gt.

إضافة شيفرة برمجية إلى تدوينة ووردبريس – الطريقة السهلة

أسهل طريقة لإضافة شيفرات برمجيّة إلى تدويناتك هي أن تستخدم كيانات HTML وتحيط كل شيء بوسم <pre>. مثال سريع لتوضيح الأمر:

<pre>
  add_action('admin_notices', 'show_mot_text');
  function show_mot_text() {
    $text = get_motivation_text();
    echo "&lt;p id='wp-admin-motivation'&gt;$text&lt;/p&gt;";
  }
</pre>

لاحظ كيف قمتُ بإدراج الشيفرات البرمجيّة بعد وسم <pre> مباشرةً وأغلقتُ الوسم باستخدام <pre/> بعد آخر رمز في الشيفرة البرمجيّة. قد ترى أنّه من الأفضل لو تمّ وضع الوسوم في أسطر منفردة ولكن في هذه الحالة ستقوم خاصيّة إبراز بنية الجملة (Syntax Highlighter) في جافا سكربت بترجمة فواصل الأسطر تلك على أنّها فواصل أسطر فعليّة. ولذلك فعدم ترك فواصل أسطر تعتبر عادة حميدة هنا.

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

أقوم بكتابة شيفرات برمجيّة عاديّة ومن ثمّ تحويل كل كيانات HTML مرّة واحدة باستخدام محرّر النصوص. إذا احتجت إلى تعديل الشيفرات البرمجيّة فيمكنك لصق النسخة المحوّلة ثمّ فكّ ترميز الكيانات إلى الرموز الصحيحة. إذا كنت تستخدم Atom.io فيمكنك استخدام حزمة HTML Entities، أمّا إذا كنت تستخدم محرّر النصوص Sublime فيمكنك استخدام أمر HTML: Encode Special Characters.

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

طريقة أفضل لعرض الشيفرات البرمجية

طريقة أفضل لإضافة شيفرات برمجيّة إلى موقع هي استخدام إضافة لتنفيذ هذا الأمر بالتحديد. الكثير من الإضافات تستخدم مكوّن جافا سكربت يعمل على إبراز بنية الجملة وخيارات أخرى لشيفراتك البرمجيّة. مكوّن إبراز بنية الجملة المفضّل بالنسبة لي هو Prism ولحسن الحظّ هناك إضافة تقوم بدمجه في ووردبريس.

حمّل إضافة Prism WP، ثبّتها ثم ابدأ في كتابة شيفراتك البرمجيّة مع اتّباع التعليمات التالية.

• قم بإحاطة شيفراتك البرمجيّة باستخدام وسم <pre> ووسم <code>.
• قد تتم إضافة فئة معيّنة class إلى هذا الوسم والتي ستحدّد اللغة المستهدفة، وذلك لإبراز وتلوين الشيفرة بشكل مُناسب.
• إذا أردت إضافة ترقيم للأسطر فستحتاج إلى تفعيل هذا من إعدادات الإضافة ثم تضيف فئة line-numbers إلى وسم <pre>.

مثال الشيفرة البرمجيّة السابق يبدو كما يلي الآن في المحرّر:

<pre class="line-numbers">
  <code class='language-php'>
    add_action('admin_notices', 'show_mot_text');
    function show_mot_text() {
      $text = get_motivation_text();
      echo "<p id='wp-admin-motivation'>$text</p>";
    }
  </code>
</pre>

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

هناك عدد آخر من القوالب التي يمكنك استخدامها، ربّما تريد إلقاء نظرة على الصفحة الرئيسيّة لإضافة Prism. يمكن تغيير القوالب بالنّقر على الدّوائر الموجودة في الجانب الأيمن. تتيح لك الإضافة تغيير القالب من خلال الإعدادات الخاصّة بالإضافة.

خدمات خارجية

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

أقترح عليك الذهاب إلى صفحة البحث عن الإضافات في ووردبريس والبحث عن الإضافة المناسبة لك، ستجد العديد منها في ثوانٍ معدودة.

افعلها بنفسك DIY

أفضّل دائمًا الاعتماد على نفسي لإيجاد حلول للمشاكل عملاً بمبدأ افعلها بنفسك (DIY – Do It Yourself)، لذلك دعونا نحاول حل هذه المشكلة دون اللجوء لحلول جاهزة. لن نتطرّق لعمليّة الإبراز لأنّها صعبة للغاية، ولكن باستطاعتنا فعل الكثير لجعل إضافة الشيفرات البرمجية في ووردبريس أكثر سهولة.

أكبر مشكلة تواجهنا هي مشكلة كيانات HTML. ما نريد فعله هو القدرة على كتابة الشيفرات البرمجيّة كما هي في الواجهة الخلفيّة (Backend) وعرضها كما هي أيضًا في الواجهة الأماميّة (Frontend) بدون ترجمة الوسوم. يمكن تنفيذ ذلك عن طريق إضافة مرشّح (Filter) إلى the_content.

الفكرة عبارة عن أنّه قبل عرض المحتوى سنبحث خلال هذا المحتوى عن أي نصوص بين وسوم code واستبدال أي رموز مميّزة بها بكيانات HTML.

لقد قمتُ قبل بضعة أشهر بكتابة إضافة بسيطة تسمّى Smart Code Escape لفعل هذا الأمر. الإضافة مثال ممتاز على شيء مفيد يستخدم 15 سطر شيفرات برمجيّة فقط. لنلق نظرة الآن.

أول شيء تحتاج لفعله هو إنشاء إضافة. يمكن الاطلاع على سلسلة "مدخل إلى برمجة إضافات ووردبريس" إذا لم يكن لديك معرفة مسبقة حول كيفيّة برمجة الإضافات.

باختصار: قم بإنشاء مجلّد في مجلّد الإضافات الخاصّ بك وقم بتسميته smart-code-escape وبداخل المجلّد قم بإنشاء ملفّ باسم smart-code-escape.php. قم بإضافة المحتوى التالي إلى الملف.

<?php

/*
* Plugin Name: Smart Code Escape
* Plugin URI: https://github.com/danielpataki/Smart-Code-Escape
* Description: Converts less than, greater than and ampersand characters to their HTML
entities within pre tags before they are output on the page. You will always see the
non-escaped version in the editor, making code easy to modify. It Will not convert code
tags directly within pre tags to support Prism-style highlighting.
* Version: 1.1
* Author: Daniel Pataki
* Author URI: http://danielpataki.com
* License: GPL v2
* Licence URI: http://www.gnu.org/licenses/gpl-2.0.txt
*/

function smart_code_escape_pre($data) {
  preg_match('@(<code.*>)(.*)(<\/code>)@isU', $data[2], $matches);
  if(!empty( $matches)) {
    return $data[1] . $matches[1] . str_replace(array('&', '<', '>'), array('&amp;', '&lt;', '&gt;'), $matches[2]) . $matches[3] . $data[3];
  }
  else {
    return $data[1] . str_replace(array('&', '<', '>'), array('&amp;', '&lt;', '&gt;'), $data[2]) . $data[3];
  }
}

add_filter('the_content', 'smart_code_escape_content', 9);
function smart_code_escape_content($content) {
  $content = preg_replace_callback('@(<pre.*>)(.*)(<\/pre>)@isU', 'smart_code_escape_pre', $content);
  return $content;
}

تحتوي الإضافة الأصليّة على توثيق مضمّن للشيفرات البرمجيّة، إذا كنت مهتمًّا فيمكنك تحميلها من المستودع وإلقاء نظرة عليها. أوّل شيء يمكن ملاحظته هو أنّني قمتُ بإضافة مرشّح إلى the_content. يقوم هذا المرشّح باستدعاء دالّة Callback تعمل مع المحتوى الموجود بين وسوم <pre>.

تقوم دالة ()smart_code_escape_pre بتولي عمليّة التحويل. تعمل أوّلاً على التحقّق ممّا إذا كانت الشيفرات البرمجيّة محاطة بوسم <code>. فكّرتُ في عمل هذا التحقّق للتأكّد من أنّ الإضافة لن تتعارض مع إضافات الشيفرات البرمجيّة الأخرى مثل إضافة Prism السابق ذكرها. أتوقّع أنّه إذا قام أحدهم بإضافة شيفراتهم البرمجيّة عن طريقة إحاطتها بوسم <pre> وكذلك وسم <code> فمؤكّد أنّه يريد بالفعل عرض الشيفرات البرمجيّة كما هي في تدوينته وليس تنفيذ الشيفرات وإظهار تأثيرها على النص فقط.

إذا لم تكن محتويات الوسم <pre> موجودة داخل وسم <code> فستقوم الدّالة باستبدال كل الرموز المميّزة بكيانات HTML المعبّرة عنها.

خاتمة

كما تلاحظ فإنّ إضافة شيفرات برمجيّة إلى موقعك ليس بالأمر الصعب، كل ما عليك معرفته مجرّد أساسيّات لماذا يتم فك الترميز.

ترجمة -وبتصرّف- للمقال: How To Display Code On Your WordPress Website The Proper Way لصاحبه Daniel Pataki.