إنشاء مكون إضافي مخصص لـ October CMS

نواصل مراجعة أكتوبر CMS وميزاته. لقد عملنا في LOVATA مع هذا النظام لمدة 6 سنوات وخلال هذا الوقت تأكدنا من أن شعبيته المتزايدة تستحق تمامًا.



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



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



في العام الماضي ، أجريت بحثًا بسيطًا على أنظمة إدارة محتوى جديدة تستند إلى PHP بحثًا عن بديل WordPress جيد . من الناحية المثالية ، كان ينبغي أن يكون حلاً مفتوح المصدر مع قاعدة بيانات حديثة.



ثم كنت مهتمًا بـ October CMS . لقد جربته وأعجبني على الفور تقريبًا . أكتوبر له بنية كود جيدة ويسهل كتابة الإضافات الخاصة بك له.



الغرض من هذه المقالة هو مساعدتك على فهم ماهية النظام الأساسي وما الذي تتوقعه منه قبل أن تقرر استخدامه.

لماذا تختار أكتوبر كمنصة CMS الخاصة بك؟

هناك العديد من الأسباب الرئيسية التي دفعتني إلى استخدام أكتوبر لمشاريعي.

مكتوب في إطار عمل Laravel

تم بناء October CMS على Laravel ، أقوى إطار عمل PHP لبناء تطبيقات الويب الحديثة. أستطيع أن أقول على وجه اليقين إنه الأفضل. إطار العمل سهل الاستخدام للغاية وسهل الفهم للغاية. بالإضافة إلى ذلك ، يحتوي على جميع الميزات التي يتطلبها إطار عمل حديث: التوجيه (التوجيه) ، ورسم الخرائط العلائقية للكائنات (ORM) ، والتفويض ، والتخزين المؤقت والعديد من الميزات الأخرى ، مما يوفر بنية لطيفة ومفهومة وفقًا لمفهوم Model-View-Controller. منذ أن تمت كتابة أكتوبر CMS في إطار عمل Laravel ، ورثت كل هذه الميزات من "الأخ الأكبر".

تنظيف الكود والتوثيق

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



بدلاً من لغة PHP القديمة الجيدة ، يستخدم October Twig كلغة نموذجية ، مما يجعل مهمة المطور أسهل. الوثائق الفنية مكتوبة بشكل جيد وتقدم إجابات سريعة على معظم الأسئلة.

مجتمع كبير

على الرغم من أن مجتمع أكتوبر لا يزال صغيرًا ، إلا أن أفراده متعاونون ومتعاونون. هناك قناة Slack يمكنك الانضمام إليها ، وسيسعد المطورون بمساعدتك في حل مشكلتك مع انتقال المجتمع إلى Discord .

سوق كبير

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

الإضافات والمكونات

المكونات الإضافية هي الأساس لإضافة ميزات جديدة إلى October CMS. يمكن أن يتكون المكون الإضافي من عدة ملفات وأدلة مسؤولة عن تسجيل المكونات أو النماذج المخصصة أو تحديث بنية قاعدة البيانات أو إضافة الترجمات. عادةً ما يتم إنشاء مكون إضافي في مشروع في الملحقات / الدليل. نظرًا لأنه يتم إضافة العديد من المكونات الإضافية إلى السوق ليستخدمها أشخاص آخرون ، يجب أن يكون لكل مكون إضافي مساحة اسم خاصة به ، والتي تبدأ عادةً باسم الشركة أو المطور الذي أنشأ المكون الإضافي. لذلك ، على سبيل المثال ، إذا كان اسمك هو Acme وقمت بإنشاء مكون إضافي رائع يسمى Blog ، فسيتم تسمية المكون الإضافي الخاص بك باسم Acme \ Blog.



دعني أوضح لك الشكل الذي قد يبدو عليه هيكل دليل البرنامج المساعد:







كما ترى ، يوجد ملف يسمى plugin.php مسؤول عن تسجيل المكون الإضافي وجميع مكوناته في أكتوبر CMS.



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







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



يحتوي October CMS على سوق كبير حيث يمكنك العثور على كل ما تحتاجه.







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



يتم إنشاء المكونات كجزء من المكون الإضافي وتقع في المكونات / الدليل الفرعي :







يحتوي كل مكون على ملف PHP ، على سبيل المثال componentName.php ، الذي يحدد المكون ، بالإضافة إلى دليل فرعي اختياريللجزئي. يجب أن يكون لمجلد الأجزاء للمكون نفس اسم الأحرف الصغيرة مثل المكون نفسه.



لفهم كيفية عمل المكون ، دعنا نفترض أن المكون الخاص بنا مسؤول عن عرض منشورات المدونة.

namespace Acme\Blog\Components;
 
class BlogPosts extends \Cms\Classes\ComponentBase
{
    public function componentDetails()
    {
        return [
            'name' => 'Blog Posts',
            'description' => 'Displays a collection of blog posts.'
        ];
    }
 
    // This array becomes available on the page as {{ component.posts }}
    public function posts()
    {
        return ['First Post', 'Second Post', 'Third Post'];
    }
} 

كما ترى ، المكون له وظيفتان رئيسيتان. الأول ، componentDetails () ، يوفر معلومات حول المكون للمسؤول الذي سيضيف ويستخدم المكونات في صفحات الويب الخاصة به. تقوم الوظيفة الثانية ، posts () ، بإرجاع المنشورات الفارغة ، والتي يمكن استخدامها بعد ذلك داخل جزء المكون (blogposts / default.htm file) ، مثل هذا:

url = "/blog"
 
[blogPosts]
==
{% for post in blogPosts.posts %}
    {{ post }}
{% endfor %}

لجعل October CMS يعرف أن المكون الخاص بنا موجود ، يجب علينا تسجيله باستخدام ملف البرنامج المساعد الرئيسي داخل وظيفة registerComponents ():

public function registerComponents()
{
    return [
        'October\Demo\Components\Todo' => 'demoTodo'
    ];
}<

كيفية إنشاء مكون إضافي لنموذج الاتصال

سنكتب ملحقًا لإنشاء نموذج ملاحظات. هذه هي الطريقة التي يجب أن تعمل بها:

• سيحتوي النموذج على الحقول التالية: الاسم الأول واسم العائلة وعنوان البريد الإلكتروني والرسالة.
• سيتم إرسال البيانات إلى الخادم باستخدام Ajax.
• بعد إرسال البيانات ، سيتلقى المسؤول رسالة بريد إلكتروني بالرسالة التي أرسلها المستخدم. في هذه المقالة ، سنستخدم تثبيتًا نظيفًا لـ October CMS:

لنبدأ في بناء المكون الإضافي الخاص بنا عن طريق تشغيل أمر في Terminal الذي يولد بنية المكون الإضافي:

php artisan create:plugin progmatiq.contactform 

تحتوي وسيطة progmatiq.contactform على اسم المؤلف (progmatiq) واسم الملحق (contactform).







نحتاج الآن إلى فتح ملف plugin.php الخاص بنا وتغيير معلومات البرنامج المساعد بالطريقة التالية:

public function pluginDetails()
   {
        return [
            'name'        => 'Contact Form',
            'description' => 'A simple contact form plug-in',
            'author'      => 'progmatiq',
            'icon'        => 'icon-leaf'
        ];
    }

فيما يلي بعض الطرق الأخرى التي تستحق إلقاء نظرة عليها:

• registerComponents ()
  
  هنا يمكنك تحديد مجموعة من المكونات التي يوفرها المكون الإضافي الخاص بك.
• registerPermissions ()
  
  يمكنك تسجيل أذونات مخصصة ، والتي يمكنك استخدامها بعد ذلك في مناطق أخرى من التطبيق.
• RegisterNavigation ()
  
  يمكنك إضافة عنصر قائمة URL مخصص إلى قائمة admin.

لنقم بإنشاء مكون ContactForm:

• قم بإنشاء مكونات / مجلد جديد في الدليل الجذر للمكون الإضافي الخاص بك.
• قم بإنشاء ملف contactForm.php في المكونات / الدليل.

• الصق الكود التالي لإخبار أكتوبر بما يفعله المكون الخاص بنا. يمكننا القيام بذلك عن طريق إنشاء طريقة componentDetails () داخل المكون الخاص بنا.

<?php

namespace Progmatiq\Contactform\Components;

use Cms\Classes\ComponentBase;

class ContactForm extends ComponentBase
{
    public function componentDetails()
    {
        return [
            'name' => 'Contact Form',
            'description' => 'A simple contact form'
        ];
    }
}

الآن نحتاج إلى تسجيل المكون داخل المكون الإضافي. للقيام بذلك ، نقوم بتعديل طريقة registerComponents ():

public function registerComponents()
    {
        return [
            'Progmatiq\Contactform\Components\ContactForm' => 'contactForm',
        ];
    }

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



بعد تسجيل المكون ، يمكننا إنشاء صفحة اتصال جديدة وإضافة المكون الخاص بنا (رقم الخطوة هو نفسه الرسم التوضيحي في لقطة الشاشة):

1. في لوحة الإدارة ، انتقل إلى CMS (1)> Pages (2) وانقر فوق + إضافة (3).
2. امنح صفحتك اسمًا وعنوان URL (4).
3. قم بتسمية ملفك (5) واختر التنسيق الافتراضي (6).

دعنا نضيف مكوننا الجديد إلى الصفحة:

1. انقر فوق المكونات في القائمة اليسرى (1) ثم حدد مكون نموذج الاتصال الخاص بنا. بمجرد النقر فوقه (2) ، يجب إضافته إلى الصفحة.
2. نحتاج إلى وضع جزء من التعليمات البرمجية التي ستضيف عنوانًا إلى صفحتنا ، وكذلك عرض المكون باستخدام توجيه Twig {٪ component 'contactForm'٪}:

<div class="container">
    <h1> Contact </h1>
    {% component 'contactForm' %}
</dіv>

إذا فتحت صفحة جهات الاتصال الآن ، فلن ترى أي شيء باستثناء عنوان يقول "جهات الاتصال".







الشيء هو أن نموذجنا لا يحتوي على HTML لعرضه.



نحتاج إلى إنشاء ملف contactform / default.htm في المكونات / المجلد.







تحتاج أيضًا إلى إضافة HTML التالي إلى الملف:

<form method="POST" 
    data-request="onSend"
    data-request-validate
    data-request-success="this.reset(); alert('Thank you for submitting your inquiry')"
>
    <div>
        
        <label for="first_name">First Name</label>
        <input type="text" name="first_name" class="form-control">
        <p data-validate-for="first_name" class="text-danger"></p> 
    </div>
 
    <div>
        <label for="last_name">Last Name</label>
        <input type="text" name="last_name" class="form-control">
 
        <p data-validate-for="last_name" class="text-danger"></p> 
    </div>
 
    <div>
        <label for="email">Email</label>
        <input type="text" name="email" class="form-control">
        <p data-validate-for="email" class="text-danger"></p> 
    </div>
 
    <div>
        <label for="content">Content</label>
        <textarea rows="6" cols="20" name="content" class="form-control"></textarea>
        <p data-validate-for="content"  class="text-danger"></p> 
    </div>
 
    <div>
        <button type="submit" class="btn btn-primary" data-attach-loading>Send</button>
    </div>
</form>

معظم الكود بسيط جدًا. ومع ذلك ، فإن لها سمات بيانات خاصة- * يمكن استخدامها في أكتوبر:



للعلامة ثلاث سمات خاصة:

data-request="onSend"

تخبر هذه السمة شهر أكتوبر أنه يجب استدعاء وظيفة onSend من المكون الخاص بنا (والتي سننشئها بعد ذلك) عند تقديم النموذج باستخدام Ajax.

data-request-validate

سيمكن التحقق من صحة النموذج عبر Ajax باستخدام الأخطاء التي سيتم إرسالها من الخادم إذا كان النموذج غير صالح.

data-request-success="this.reset(); alert('Thank you for submitting your inquiry')"

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



يحتوي كل إدخال على الكتلة التالية ، المسؤولة عن عرض أخطاء التحقق من الصحة التي يُرجعها الخادم لإدخال معين:

<p data-validate-for="content"  class="text-danger"></p>

يحتوي زر الإرسال على سمة تحميل إرفاق البيانات التي تضيف زرًا زائدًا وتعطيل الزر عندما يعالج الخادم الطلب. هذا لمنع المستخدم من إرسال النموذج مرة أخرى حتى تتم معالجة الطلب السابق.



وإليك كيف تبدو صفحتنا الآن:







دعنا نعود إلى مكون contactForm.php الخاص بنا وأنشئ التوابع المساعدة onSend () والتحقق من صحة () التي ستكون مسؤولة عن إرسال النموذج:

public function onSend()
    {
        // Get request data
        $data = \Input::only([
            'first_name',
            'last_name',
            'email',
            'content'
        ]);
 
        // Validate request
        $this->validate($data);
 
        // Send email
        $receiver = 'admin@gmail.com';
 
        \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) {
            $message->to($receiver);
        });
    }
 
    protected function validate(array $data) 
    {
        // Validate request
        $rules = [
            'first_name' => 'required|min:3|max:255',
            'last_name' => 'required|min:3|max:255',
            'email' => 'required|email',
            'content' => 'required',
        ];
 
        $validator = \Validator::make($data, $rules);
 
        if ($validator->fails()) {
            throw new ValidationException($validator);
        }
    }

أول شيء نقوم به هو الحصول على البيانات من الطلب والتحقق من صحتها باستخدام التابع validate () المساعد. يمكن العثور على جميع قواعد التحقق المتاحة التي يمكنك استخدامها في الوثائق . إذا فشل التحقق من الصحة ، فإن أسلوب التحقق () يطرح ValidationException - سيتوقف تنفيذ التعليمات البرمجية ، وسيصدر الخادم رمز الحالة 406 ورسالة فشل التحقق من الصحة.



إذا تم التحقق من الصحة بنجاح ، فسنرسل بريدًا إلكترونيًا إلى المسؤول لدينا.



ملاحظة: من أجل التبسيط ، افترضت أن البريد الذي نريد إرسال الطلب إليه هو admin@gmail.com. تأكد من استخدام عنوان البريد الإلكتروني الخاص بك!



هذا هو الكود الكامل للمكون الإضافي contactForm.php الخاص بك:

<?php
 
namespace Progmatiq\Contactform\Components;
 
use Cms\Classes\ComponentBase;
use October\Rain\Exception\ValidationException;
 
class ContactForm extends ComponentBase
{
    public function componentDetails()
    {
        return [
            'name' => 'Contact Form',
            'description' => 'A simple contact form'
        ];
    }
 
    public function onSend()
    {
        // Get request data
        $data = \Input::only([
            'first_name',
            'last_name',
            'email',
            'content'
        ]);
 
        // Validate request
        $this->validate($data);
 
        // Send email
        $receiver = 'admin@gmail.com';
 
        \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) {
            $message->to($receiver);
        });
    }
 
    protected function validate(array $data) 
    {
        // Validate request
        $rules = [
            'first_name' => 'required|min:3|max:255',
            'last_name' => 'required|min:3|max:255',
            'email' => 'required|email',
            'content' => 'required',
        ];
 
        $validator = \Validator::make($data, $rules);
 
        if ($validator->fails()) {
            throw new ValidationException($validator);
        }
    }
}

كما ترى ، فإن الوسيطة الأولى التي تأخذها وظيفة Mail :: send () هي اسم قالب البريد الإلكتروني الذي سيظهر في نص الرسالة. نحن بحاجة إلى إنشائه في لوحة الإدارة. اذهب إلى الإعدادات> قوالب البريد الإلكتروني وانقر على زر قالب جديد. ثم املأ النموذج كما هو موضح على الشاشة أدناه: هذا







هو نص البريد الإلكتروني الذي سنستخدمه:

لقد تلقيت استفسار جهة اتصال جديدة



** الاسم الأول **:

{{first_name}}

***

** اسم العائلة **:

{{last_name}}

***

** البريد الإلكتروني **:

{{email}}

** *

** الرسالة **:

{{content}}

***

الآن احفظ قالب البريد الإلكتروني الخاص بك. الشيء التالي الذي يتعين علينا القيام به هو إعداد خادم SMTP لإرسال رسائل البريد الإلكتروني.



اذهب إلى الإعدادات> تكوين البريد واملأ جميع الإعدادات.







بالطبع لن أشارك ملفات التكوين الخاصة بي. استخدم الإعدادات الخاصة بك.



في هذه المرحلة ، نحن جاهزون لبدء اختبار مكون نموذج الملاحظات.



أولاً ، دعنا نتحقق مما إذا كانت عملية التحقق تعمل عندما نترك حقل المحتوى فارغًا وإدخال عنوان بريد إلكتروني غير صالح:







التحقق يعمل كما هو متوقع. الآن دعنا ندخل التفاصيل الصحيحة ونرى ما إذا تم إرسال البريد الإلكتروني بنجاح إلى مسؤولنا.



هذا هو البريد الإلكتروني الذي سيتلقاه admin@gmail.com:







بعد إرسال النموذج بنجاح ، سيرى المستخدم الرسالة المقابلة:

انتاج |

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



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



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