كيفية إضافة زر إلى محرر جوتنبرج باستخدام @ wordpress / scripts

منذ عام ونصف تقريبًا ، كتب أنطونيو منشور المدونة هذا موضحًا إحدى الصعوبات التي واجهناها عند تكييف مكوناتنا الإضافية مع محرر قوالب WordPress الجديد. بدت نتيجة البرنامج التعليمي شيئًا كالتالي:

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

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

قم بإنشاء مكون إضافي

أول شيء يجب علينا فعله هو إنشاء مكون إضافي لبرنامج WordPress. هذا واضح جدا. في الأساس ، كل ما يتعين علينا القيام به هو إنشاء مجلد في wp-content/plugins بالاسم الذي نريد أن نطلقه على المكون الإضافي (على سبيل المثال ، gutenberg-button ) وداخله ، إنشاء ملف يحمل نفس الاسم وملف .php ملحق .php . ثم اكتب الكود التالي في ملف البرنامج المساعد الخاص بك:

الآن ، دعنا نلقي نظرة فاحصة على ما يفعله المقتطف السابق:

• نفتح أولاً علامة <?php . لا مفاجآت هنا.
• بعد ذلك ، في هذا الملف الرئيسي ، نضيف تعليقًا متعدد الأسطر. يتضمن التعليق عدة أسطر مع أزواج "المفتاح / القيمة". على سبيل المثال ، نرى كيف نحدد اسم المكون الإضافي ( Plugin Name ) أو نسخته ( Version ) أو اسم المؤلف ( Author ). ستكون كل هذه المعلومات مرئية بعد ذلك في قسم الملحقات في WordPress.
• أخيرًا ، نضيف بعض التعليمات البرمجية المعيارية:
  • نحدد namespace (تحدثنا هنا عن مساحات الأسماء) ،
  • نتأكد من أنه في حالة تشغيل الملف ، يتم تشغيله كجزء من WordPress ، و
  • نحدد بعض الثوابت حول الملحق (والتي ستكون مفيدة لاحقًا).

بمجرد قيامنا بكل هذا ، إذا انتقلنا إلى شاشة المكونات الإضافية في WordPress الخاص بنا ، فسنرى أن زر Gutenberg موجود:

نقوم بتنشيطه و ... فويلا! بالتأكيد ، لن تفعل أي شيء ، لكنها موجودة بالفعل.

تطوير البرنامج المساعد جافا سكريبت

في الوقت الحاضر ، يجب أن يكون مطورو WordPress بارعين في استخدام JavaScript. أعتقد أن هذه إحدى عواقب كون جوتنبرج في جوهره. وهذا البرنامج التعليمي ليس استثناء.

تهيئة البيئة

إذا أردنا إضافة زر جديد إلى واجهة Gutenberg ، يجب علينا ترميز هذه الميزة في JavaScript. لذلك دعونا نجهز بيئة تطوير JavaScript في المكون الإضافي الخاص بنا. للقيام بذلك ، ما عليك سوى تشغيل الأمر التالي من سطر الأوامر (تأكد من أنك في wp-content/plugins/gutenberg-button عند القيام بذلك):

 npm init

واتبع التعليمات:

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

نتيجة هذه العملية ملف package.json . كما سترى في غضون لحظات قليلة ، سيكون هذا الملف مفيدًا للغاية في المستقبل.

كما أوضحت بالفعل في عنوان هذا المنشور ، سنستخدم @wordpress/scripts لإنشاء المكون الإضافي الخاص بنا. لذلك دعونا نضيفها كتبعية عن طريق تشغيل الأمر التالي:

 npm install --save-dev @wordpress/scripts

سيقوم هذا الأمر بتنزيل مجموعة من التبعيات داخل المكون الإضافي الخاص بنا (ضمن node_modules ) وسيقوم بتعديل package.json الخاص بنا بحيث يتضح أن @wordpress/scripts هو الآن تبعية تطوير.

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

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

لذلك دعونا نعدل ملف package.json الخاص بنا بحيث يحتوي قسم "scripts" على جميع الأوامر الموصى بها.

كيفية التحقق من أن كل شيء يعمل ...

لنقم بإنشاء مجلد src في جذر مشروعك وإضافة ملف index.js بداخله. سيكون هذا هو ملف JavaScript الرئيسي للمكون الإضافي الخاص بنا وسيحتوي على كل التعليمات البرمجية الخاصة بك (يمكنك بعد ذلك تنظيم الكود كما يحلو لك ، طالما أن الملف الرئيسي هو src/index.js ).

دعنا نجرب ما إذا كانت الأشياء تعمل كما هو متوقع عن طريق إضافة index.js البيان التالي:

 console.log( 'Hi!' );

وبناء المشروع باستخدام npm run build . سيؤدي هذا إلى تحويل التعليمات البرمجية الخاصة بك إلى شيء يمكن للمتصفح تشغيله (لم يكن ذلك ضروريًا بالفعل في الوقت الحالي ، ولكنه سيكون في غضون دقيقتين فقط) وإنشاء برنامج نصي جديد داخل مجلد build .

كل ما علينا فعله الآن هو إخبار WordPress بأن هذا البرنامج النصي موجود حتى يتمكن من تحميله. للقيام بذلك ، ما عليك سوى فتح الملف الرئيسي للمكوِّن الإضافي ( gutenberg-button.php ) وإضافة الأسطر التالية في النهاية:

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

إذا انتبهت ، فسترى أننا ببساطة نخبر WordPress بإدراج البرنامج النصي الجديد /build/index.js كمورد محرر كتلة. بهذه الطريقة ، عندما يصل المستخدم إلى محرر الكتلة ، سيكون البرنامج النصي الخاص بنا جزءًا من الأصول التي سيشملها المحرر.

لذلك دعونا نتحقق من هذا. انتقل إلى لوحة تحكم WordPress الخاصة بك ، وقم بتحرير منشور وانظر إلى وحدة تحكم JavaScript في متصفحك. إذا سارت الأمور كما هو متوقع ، يجب أن ترى "مرحبًا!" مكتوب على وحدة التحكم:

نسخ البرنامج التعليمي الخاص بنا لإضافة زر إلى Gutenberg

حسنًا ، بعد أن رأينا أنه يمكننا كتابة كود JavaScript npm run build ، وبنائه في شيء ستفهمه متصفحاتنا ، فقد حان الوقت لتكرار برنامج أنطونيو التعليمي. وهذا ، عزيزي القارئ ، بسيط للغاية.

افتح ملف src/index.js واستبدل عبارة console.log السابقة بما يلي:

كما ترى ، هذا هو نفس الرمز الذي كتبه أنطونيو منذ بضعة أشهر. يتمثل الاختلاف الرئيسي في حقيقة أننا لم نعد نستخدم المتغير العام wp للوصول إلى وظائف ومكونات Gutenberg ؛ بدلاً من ذلك ، نعتمد الآن على بيانات import . لكن بخلاف ذلك ، الأمر متشابه إلى حد كبير.

بمجرد كتابة الكود ، ما عليك سوى npm run build وهذا كل شيء! لديك الآن الزر في جوتنبرج:

دعنا نتأكد من أنه يعمل عن طريق تحديد بعض النصوص والنقر فوق الزر:

وها أنت ذا ، نرى النص يظهر في وحدة التحكم مرة أخرى!

ملاحظة أخيرة حول التبعيات ...

إذا ألقيت نظرة داخل مجلد build ، فسترى أن @wordpress/scripts لم يقم فقط بإنشاء ملف index.js ، ولكن يحتوي على ملف index.asset.php . يعرّف هذا الملف كائنًا صغيرًا بخاصيتين:

• قائمة التبعيات (أي نصوص WordPress) التي يتطلبها المكون الإضافي الخاص بنا
• نسخة بناء

يمكننا (ويجب علينا) استخدام هاتين الخاصيتين عند وضع نص في قائمة الانتظار في WordPress إذا أردنا التأكد من أن البرنامج النصي سيعمل بشكل صحيح. للقيام بذلك ، ما عليك سوى الرجوع إلى gutenberg-button.php وتغييره كما هو موضح أدناه:

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

ما عليك سوى تحميل الكائن في index.asset.php باستخدام عبارة include واستبدال قائمة التبعيات التي لدينا ( [] ) بالتبعية الفعلية واستخدام رقم البنية كإصدار البرنامج المساعد.

الاستنتاجات

يعد إنشاء إضافات WordPress مفيدة حقًا أمرًا صعبًا. يجب أن تفهم جيدًا كيفية عمل JavaScript وأن تكون على دراية بجميع موارد WordPress. ولكن بفضل حزمة @wordpress/scripts ، أصبح إعداد بيئة تطوير JavaScript وإنشاء مكون إضافي لـ JavaScript يمكن تشغيله داخل WordPress أسهل من أي وقت مضى.

آمل أن تكون قد أحببت منشور اليوم. وكالعادة ، إذا واجهتك مشكلة في أي وقت أو كانت لديك أسئلة ، فيرجى ترك تعليق وسنساعدك.

وبالمناسبة ، يوجد رابط للمشروع جاهز للتنزيل والاختبار إذا كنت ترغب في ذلك. فقط قم باستنساخ المشروع ، npm install جميع التبعيات ، npm run build المشروع وإعطائه فرصة!

صورة مميزة بواسطة Ashim D'Silva على Unsplash.