تطوير جوتنبرج بأمثلة: خرائط جوجل (الجزء الثاني)

أهلا! عدنا ببرنامجنا التعليمي للتطوير في جوتنبرج. بدأنا الأسبوع الماضي مشروعًا أضاف كتلة خريطة في WordPress. في هذا المنشور الأول ، حددنا المتطلبات التي يجب أن يفي بها المكون الإضافي الخاص بنا وأعددنا الهيكل العظمي لما سينتهي به الأمر ليكون المنتج النهائي ، بدءًا من البرنامج المساعد الرائع الذي أنشأناه في Nelio.

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

نظرة سريعة على الوضع الحالي للمشروع ...

في الحالة الحالية للمشروع ، لدينا كتلة تجريبية بسيطة محددة في packages/blocks/demo/ . هذه الكتلة الصغيرة هي التي تأتي كمثال في Boilerplate للمكوِّن الإضافي لـ Nelio وتبدو كما يلي:

من الواضح أن هذا ليس ما نريده. لسنا مهتمين برمز قلب متبوعًا بنص ، ولكن بشيء مثل هذا:

أي أننا نريد كتلة خرائط Google مع علامة اختيارية بداخلها. كيف يمكننا الانتقال من نموذج النموذج الأصلي الذي كان يحتوي عليه النموذج المعياري إلى هذه الكتلة الأخرى الأكثر قوة؟ حسنًا ، هذا ما سنجيب عليه اليوم!

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

فهم الكتلة التجريبية ...

كما قلت سابقًا ، يتم تحديد الكتلة التجريبية في packages/blocks/demo/ . ستجد في هذا المجلد أنماط الكتلة ورمزها والعديد من الملفات التي تحتوي على الكود الذي ينفذ عملها. دعنا نرى أهم الملفات.

من ناحية ، يوجد الملف الرئيسي: index.js . يصدر هذا الملف ثلاثة متغيرات: اسم الكتلة ( name ) ، وتعريف الكتلة ( settings ) ، والأنماط التي تدعمها الكتلة ( styles ). هذه المتغيرات الثلاثة هي تلك المستخدمة في packages/blocks/index.js لتسجيل الكتلة في Gutenberg (مع registerBlockType ) وبالتالي إتاحتها للمستخدمين النهائيين.

هذا الملف الرئيسي ، إذن ، يعمل كنقطة دخول لفهم الكتلة التي نقوم بإنشائها. في إعدادات الكائن ( settings ) ، نرى ثلاث خصائص مهمة: attributes ، edit ، save . كل خاصية من هذه الخصائص لها ملف JavaScript خاص بها (من أجل البساطة وسهولة الفهم) ، كل واحدة منها تمت تسميتها على اسم الخاصية المقابلة لها. دعنا نلقي نظرة سريعة على كل منهم:

• يعرّف ملف attributes.js كل خصائص الكتلة الخاصة بنا والتي تكون ديناميكية ، وبالتالي ، يجب أن تكون قابلة للتعديل من قبل مستخدمينا. في حالة كتلة العرض التوضيحي الخاصة بنا ، السمة الوحيدة الموجودة هي النص الذي كتبه المستخدم ، ولكن سيكون لكتلة الخريطة العديد من الخيارات: إحداثيات مركز الخريطة ، ومستوى التكبير الافتراضي الذي يجب أن تستخدمه الخريطة ، وما يجب أن تكون الأزرار (إن وجدت) مرئية للتفاعل مع الخريطة ، وما إلى ذلك.
• يعد الملف edit.js هو الملف الذي يحدد كيفية عرض الكتلة في محرر WordPress والإعدادات التي يتم تقديمها للمستخدم (سواء في شريط الأدوات أو في الشريط الجانبي لإعدادات الكتلة). في العرض التوضيحي ، يتضمن edit ببساطة مكون RichText في WordPress لكتابة المحتوى. كما سنرى ، ستكون كتلة الخريطة أكثر تعقيدًا وستتضمن أيضًا إعدادات إضافية.
• أخيرًا ، يحدد save.js الطريقة التي ستحول الكتلة التي كنا نحررها في Gutenberg إلى HTML والتي يجب عرضها في الواجهة الأمامية. مرة أخرى ، في العرض التوضيحي ، نرى أن هذه الوظيفة تقوم ببساطة بحفظ محتويات RichText باستخدام RichText.Content ، ولكن يمكن أن تكون أي شيء آخر (كما سنرى الأسبوع المقبل في الجزء الثالث والأخير من هذا البرنامج التعليمي).

إنشاء كتلة الخريطة بناءً على كتلة العرض التوضيحي المضمنة في البرنامج المساعد Boilerplate

بمجرد أن نفهم بالضبط كيف تعمل الكتلة التجريبية ، فقد حان الوقت لنسأل أنفسنا: كيف نصنع الكتلة التجريبية الخاصة بنا؟ حسنًا ، سهل جدًا: كما أخبرنا Toni قبل بضعة أيام ، علينا ببساطة تكرار packages/blocks/demo/ في packages/blocks/nelio-maps/ والبدء في تعديل كل ما هو ضروري. أعلم أن القول أسهل من الفعل.

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

النقطة التالية التي يجب تعديلها هي كل ما يتعلق بإصدار الكتلة في Gutenberg. للقيام بذلك ، يجب علينا الغوص في edit.js إذا نظرت عن كثب ، سترى أنه ليس أكثر تعقيدًا مما كان لدينا في الكتلة التجريبية الأصلية.

الشيء الأكثر أهمية هو طريقة render الكتلة (السطر 33) ، حيث نسترجع السمات التي حددناها للتو من كائن يسمى this.props . سنستخدم هذه الخصائص لتقديم الكتلة وإعداداتها بالطبع. هذا ما نملكه:

1. عنصر تحكم شريط أدوات شريط الأدوات (السطر 66) ، والذي ToolbarControls في ملف خارجي باسم toolbar.js (لا تقلق ، سنرى محتواه في غضون دقيقة).
2. إعدادات الحظر التي تظهر في الشريط الجانبي للمحرر (السطر 68) ، والتي نجدها في مكون يسمى Inspector الذي حددناه في inspector.js .
3. محتوى الكتلة نفسها ، والتي تتكون من حالتين:
   • إذا لم يكن لدي مفتاح API لخرائط Google متاحًا ، فإننا نعرض إشعار المستخدم (السطر 122).
   • إذا كان لدينا هذا المفتاح ، فإننا نعرض الخريطة باستخدام MapBlock (السطر 83). قد تتضمن الخريطة Marker (خط 97) ، والتي تكون مرئية فقط عند تنشيط الخيار ، وقد تكون مصحوبة أيضًا بـ div (السطر 104) بمعلومات إضافية عنه.

خرائط جوجل كمكون رد فعل

إذا أردنا وضع خريطة Google في محررنا ، فيجب علينا استخدام مكون يسمح لنا باستخدام API للخرائط في خرائط Google. بالنظر إلى أن Gutenberg مبني على React ، فإن الشيء المنطقي الذي يجب فعله هو معرفة ما إذا كان هناك مكون React في خرائط Google. والشيء المؤكد ، هناك واحد!

كما يمكنك أن تقرأ في وثائق المشروع ، علينا أولاً إضافة المكون إلى مشروعنا. فقط قم بتثبيت وإضافة التبعية بتشغيل الأمر التالي:

 npm install react-google-maps --save-dev

الذي يضيف إدخالًا جديدًا في package.json لدينا ويقوم بتنزيل الحزمة في node_modules .

كيفية إنشاء مكون WordPress يغلف مكون React

إذا واصلنا النظر في وثائق مشروع React هذا لخرائط Google ، فسنرى أنهم يوصوننا بلف مكون GoogleMap الخاص بهم مع المكون الخاص بنا. بمجرد تغليفه ، سيتعين علينا استخدام المكون الخاص بنا في المكون الإضافي الخاص بنا.

حسنًا ، دعنا نتبع تقدمهم وننشئ مكونًا يسمى MapBlock في ملف map-block.js . وهذا كل شيء! لدينا الآن مكون خريطة جاهز يمكننا استخدامه في كتلة Gutenberg الخاصة بنا.

كيفية إضافة إعدادات الحظر في مفتش محرر WordPress

الخطوة التالية هي تكوين الشكل الذي يجب أن تظهر به هذه الخريطة في المحرر وإضافة بعض الإعدادات لتعديل مظهرها. للقيام بذلك ، يجب أن نضيف العديد من أقسام الإعدادات في شريط Gutenberg الجانبي. نظرًا لأنني تقدمت بالفعل ، فقد حققنا ذلك من خلال مكون أطلقنا عليه اسم Inspector والذي حددناه في ملف inspector.js .js.

إذا ألقيت نظرة على هذا الملف ، فسترى أنه يتبع نفس النمط كما هو الحال دائمًا: نحن نحدد Component بطريقة render . تقوم هذه الطريقة بسحب السمات ذات الصلة في this.props وإرجاع JSX مع جميع عناصر التحكم. في هذه الحالة بالذات ، تقوم بإرجاع مثيل لـ InspectorControls (هذا يخبر WordPress أن هذا المحتوى ينتقل إلى الشريط الجانبي) مع عدة أقسام PanelBody . دعونا نرى كل قسم بالتفصيل.

إعدادات الخريطة الأساسية

أول PanelBody (السطر 47) ليس لها title وبالتالي تظهر دائمًا كقسم لا يمكن إغلاقه:

يحدد هذا القسم زوجًا من RangeControl ، والتي يمكنك رؤية نتيجتها في لقطة الشاشة السابقة. تسمح لنا عناصر التحكم هذه بتعديل ارتفاع الخريطة ومستوى التكبير / التصغير.

قسم آخر مثير للاهتمام وبسيط هو القسم الموجود في السطر 121. هنا نضيف بعض الخيارات لتنشيط أو إلغاء تنشيط الأزرار التي يجب أن تظهر على الخريطة عند عرضها في الواجهة الأمامية :

للقيام بذلك ، علينا ببساطة استخدام مكون WordPress الافتراضي CheckboxControl .

كيفية إضافة قسم نمط مخصص لكتلة الخريطة الخاصة بنا

قسم آخر مثير للاهتمام من الكتلة لدينا هو قسم النمط (السطر 68). يمكنك رؤية النتيجة النهائية في لقطة الشاشة التالية:

إنه قسم خاص لأن المكون الذي نستخدمه ( MapStyles ) ليس شيئًا موجودًا في WordPress افتراضيًا ، ولكنه شيء أنشأناه لهذه الكتلة على وجه الخصوص. كما ترى في الرابط السابق ، فهو مكون يقوم بتحميل مجموعة من الأنماط المحددة مسبقًا في مكون من نوع ImagePicker (والذي ، بالمناسبة ، غير موجود افتراضيًا في WordPress أيضًا - يمكنك العثور عليه في packages/components/image-picker/ ).

عندما يحدد المستخدم أيًا من الأنماط المضمنة في ImagePicker ، فإن مكون MapStyles يستدعي وظيفة onChange التي أعطيت لها (انظر السطر 76 من inspector.js ) ويمرر قيمتين: اسم النمط المحدد و JSON المرتبط.

أخيرًا ، لاحظ أن أحد الخيارات التي MapStyles هو نمط مخصص :

عند تحديده ، يعرض المكون مربع نص إضافي (السطر 45) بحيث يمكن للمستخدم إدخال نمطه الخاص في تنسيق JSON. في حالة عدم معرفتك ، يمكن تخصيص خرائط خرائط Google كثيرًا!

كيفية إضافة علامة إلى خريطتنا

القسم التالي الذي لدينا هو الذي يتحكم في العلامة الخاصة بنا (السطر 81). يتيح لنا هذا القسم إظهار أو إخفاء العلامة (السطر 86) ، وعندما يكون نشطًا ، يعطينا بعض الإعدادات الإضافية:

كما ترى ، يظهر مربع بحث للبحث عن المواقع في خرائط Google (التي قمنا بتنفيذها ، مرة أخرى ، مع مكون مخصص يسمى AddressSearch ) والقدرة على إظهار أو إخفاء كتلة النص لوضع معلومات إضافية حول العلامة.

بالمناسبة ، لاحظ أن مكون AddressSearch يعتمد على مكون يسمى StandaloneSearchBox ، وهو أيضًا جزء من مشروع React. يا لها من متعة إعادة استخدام عمل الآخرين!

كيفية تكوين شريط الأدوات للكتلة

آخر شيء علينا مناقشته هو شريط الأدوات. إذا كنت قد فهمت كيفية عمل الشريط الجانبي ، فإن شريط الأدوات عبارة عن قطعة من الكعكة.

يتم تمثيل شريط أدوات المكون الإضافي الخاص بنا بواسطة مكون ToolbarControls المحدد في toolbar.js . نحن هنا ببساطة نضيف مكونًا لتحديد محاذاة الكتلة ( BlockAlignmentToolbar ، في السطر 42) ، وزوج من القوائم المنسدلة لتوسيط الخريطة (السطر 50) ولتعديل موقع العلامة (السطر 79) ، وزوجين من أزرار إضافية لتغيير موقع مربع النص حيث يمكننا وضع معلومات إضافية حول العلامة (الأسطر 107 و 120).

باختصار

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

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

صورة مميزة بواسطة Rawpixel على Unsplash .