حل خطأ Entity name must immediately follow '&' في بلوجر

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

حدث خطأ أثناء تحليل xml في السطر x, العمود x: The entity name must immediately follow the '&' in the entity reference

في هذا الدليل الشامل والمُحدّث، سنشرح سبب حدوث هذا الخطأ بالضبط، ونقدّم لك حلّين عمليّين: الحل التقليدي (استبدال الرموز)، والحل الأسرع والأكثر أمانًا (استخدام CDATA) الذي يوفّر عليك الوقت في الأكواد الطويلة.

لماذا يحدث خطأ تحليل XML تحديداً؟

قوالب بلوجر مكتوبة بلغة XML (لغة ترميز قابلة للتوسيع)، وهي لغة صارمة جداً في قواعدها مقارنة بـ HTML العادي. أي رمز غير متوقع داخل المستند يجعل المحلل (Parser) يتوقف فوراً ويرفض حفظ القالب بالكامل.

عندما يرى محلل XML الرمز &، فإنه يفترض تلقائياً أن ما بعده هو بداية "كيان" (Entity) معرّف مسبقاً مثل amp أو lt، ينتهي بفاصلة منقوطة ;. فإذا كتبت في كود JavaScript شيئاً مثل && (عامل AND المنطقي) دون معالجة، يظن المحلل أنك بدأت كتابة كيان ولم تُكمله، فيظهر الخطأ ويرفض حفظ القالب.

الرموز الخاصة التي يجب الحذر منها في XML

الحل الأول: استبدال الرموز بكيانات XML يدوياً

هذا الحل مناسب عندما يكون الكود المُضاف قصيراً (سطر أو سطرين فقط). لنفترض أن هذا الكود يسبب المشكلة:

<script>
  if (x > 5 && y < 10) {
    // Error here
  }
</script>

بعد المعالجة يصبح الكود آمناً داخل القالب:

<script>
  if (x &gt; 5 &amp;&amp; y &lt; 10) { 
    // Success
  }
</script>

عيب هذا الأسلوب: إذا كان الكود طويلاً (أكثر من 20-30 سطراً) وبه عشرات الرموز الخاصة، فإن تعديل كل رمز يدوياً مُرهق وعرضة للأخطاء البشرية. هنا يأتي دور الحل الثاني.

الحل الثاني (الموصى به): تغليف الكود بـ CDATA

الطريقة الأذكى والمعتمدة من قِبل معظم مطوري قوالب بلوجر هي استخدام وسم <![CDATA[ ... ]]>. هذا الوسم يخبر محلل XML بأن كل ما بداخله يجب اعتباره نصاً خاماً وعدم تحليله كـ XML إطلاقاً، فلا داعي لاستبدال أي رمز مهما كان عدد الرموز الخاصة في الكود.

نفس المثال السابق، لكن بحل CDATA:

<script>
//<![CDATA[
  if (x > 5 && y < 10) {
    // يعمل بدون أي تعديل على الرموز
  }
//]]>
</script>

لاحظ أنك لم تحتَج لتغيير رمز واحد داخل الكود؛ فقط أضفنا //<![CDATA[ في بداية السكريبت و //]]> في نهايته (التعليق // مهم هنا لتوافق بعض المتصفحات القديمة مع JavaScript).

خطوات تطبيق الحل في بلوجر

1. اذهب إلى المظهر (Theme) ثم تعديل HTML.
2. استخدم Ctrl + F للبحث عن رقم السطر المذكور في رسالة الخطأ.
3. إذا كان الكود قصيراً: استبدل كل رمز & بـ &، وكل < بـ <، وكل > بـ >.
4. إذا كان الكود طويلاً: أحِط الجزء الذي يحتوي على الرموز الخاصة بـ //<![CDATA[ في البداية و //]]> في النهاية.
5. اضغط معاينة للتأكد من عدم وجود أخطاء أخرى قبل الحفظ.
6. احفظ القالب.

أخطاء تحليل XML مشابهة قد تواجهها

إذا استمرت المشكلة بعد التصحيح، تأكد من فحص هذه الأخطاء الشائعة الأخرى التي تظهر بنفس الطريقة:

• XML parsing error: not well-formed — غالباً بسبب وسم لم يُغلق بشكل صحيح.
• duplicate attribute — تكرار نفس الخاصية (Attribute) مرتين في نفس الوسم.
• mismatched tag — عدم تطابق وسم الفتح مع وسم الإغلاق.

أسئلة شائعة

هل يؤثر استخدام CDATA على أداء الموقع (SEO)؟
لا، استخدام CDATA لا يؤثر إطلاقاً على سرعة الموقع أو ترتيبه في محركات البحث، فهو مجرد تعليمة لمحلل XML أثناء حفظ القالب فقط.

لماذا يظهر الخطأ فجأة رغم أن الكود كان يعمل سابقاً؟
عادة يحدث هذا عند نسخ كود JavaScript من مصدر خارجي يحتوي رموز & أو < دون تنبّه لقواعد XML الخاصة بقالب بلوجر.

هل يمكن استخدام CDATA مع كل أنواع الأكواد؟
نعم، وهي الطريقة الموصى بها لأي كود JavaScript كبير يُضاف داخل قالب بلوجر لتفادي هذه الأخطاء نهائياً.

خلاصة

مشكلة The entity name must immediately follow the '&' تحدث بسبب تعارض بين قواعد JavaScript وقواعد XML الصارمة في قوالب بلوجر. للأكواد القصيرة، استبدال الرموز يدوياً كافٍ، أما للأكواد الطويلة فاستخدام CDATA هو الحل الأسرع والأكثر أماناً لتفادي الأخطاء البشرية.

اقرأ أيضاً: حل مشاكل الأرشفة - تسريع ارشفة المقالات