حقل مرن سهل وكامل لـ Laravel Nova، مثالي للمجموعات الحقلية المتكررة والمرنة.

بداية سريعة

إليك دليل موجز جداً للبدء فوراً. راجع الوثائق الكاملة على https://whitecube.github.io/nova-flexible-content

التثبيت

composer require whitecube/nova-flexible-content

الاستخدام

يسمح الحقل المرن بإدارة سهلة لمجموعات الحقول القابلة للتكرار والترتيب. على عكس بعض الحلول الموجودة لـ Laravel Nova، هذا الحقل لا يفرض قيوداً على أنواع الحقول المسموح باستخدامها داخل هذه المجموعات.这意味着 أنه يمكنك استخدام جميع أنواع الحقول الخاصة بـ Laravel Nova، بالإضافة إلى أي حقول من المجتمع.

إضافة تخطيطات

يمثل التخطيط مجموعة من الحقول التي يمكن تكرارها داخل الحقل المرن. يمكنك إضافة عدد تريده من التخطيطات. إذا تم تعريف تخطيط واحد فقط، فسيتصرف الحقل كمكرر بسيط، وبإضافة المزيد من التخطيطات ستحصل على محتوى مرن. كلا المفهومين مشابهان لنظيريهما في إضافة ACF الخاصة بـ Wordpress.

يمكن إضافة التخطيطات باستخدام الطريقة التالية على حقولك المرنة:

 addLayout(string $title, string $name, array $fields)

يتم استخدام المعامل $name لتخزين التخطيط المختار في قيمة الحقل. اختره بحكمة، فمن المحتمل أن تستخدمه لتعريف التخطيطات في تطبيقك.

use Whitecube\NovaFlexibleContent\Flexible;

/**
 * احصل على الحقول المعروضة بواسطة المورد.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        // ...

        Flexible::make('Content')
            ->addLayout('قسم محتوى بسيط', 'wysiwyg', [
                Text::make('العنوان'),
                Markdown::make('المحتوى')
            ])
            ->addLayout('قسم فيديو', 'video', [
                Text::make('العنوان'),
                Image::make('صورة مصغرة للفيديو', 'thumbnail'),
                Text::make('معرف الفيديو (YouTube)', 'video'),
                Text::make('تعليق الفيديو', 'caption')
            ])
    ];
}

تخصيص نص الزر

يمكنك تغيير النص الافتراضي لزر "إضافة تخطيط" كما يلي:

Flexible::make('Content')
    ->button('أضف شيئاً رائعاً!');

استخدام القيم المرنة في العروض

إذا كنت تستخدم Laravel 6 أو أقل، أو لا ترغب في استخدام التحويلات، فالرجاء استخدام accessor على نموذجك مع trait HasFlexible.

يقدم Laravel 7 تحويلات مخصصة، وتعتبر الحقول المرنة حالة استخدام مثالية لها. يخزن الحقل قيمه كسلسلة JSON واحدة، مما يعني أنه يجب تحليل هذه السلسلة قبل استخدامها في تطبيقك. يمكن القيام بذلك ببساطة باستخدام كلاس FlexibleCast من هذه الحزمة:

namespace App;

use Illuminate\Database\Eloquent\Model;
use Whitecube\NovaFlexibleContent\Value\FlexibleCast;

class MyModel extends Model
{
    protected $casts = [
        'flexible-content' => FlexibleCast::class
    ];
}

بشكل افتراضي، سيجمع كلاس FlexibleCast مثيلات Layout الأساسية. إذا كنت ترغب في تعيين التخطيطات إلى مثيلات تخطيط مخصصة، فهذا ممكن أيضاً. أولاً، قم بإنشاء تحويل مرن مخصص عن طريق تشغيل php artisan flexible:cast MyFlexibleCast. سيؤدي هذا إلى إنشاء الملف في دليل App\Casts.

ثم قم بسهولة بتعيين كلاسات التخطيط المخصصة لك إلى المفاتيح المناسبة:

namespace App\Casts;

class MyFlexibleCast extends FlexibleCast
{
    protected $layouts = [
        'wysiwyg' => \App\Nova\Flexible\Layouts\WysiwygLayout::class,
        'video' => \App\Nova\Flexible\Layouts\VideoLayout::class,
    ]
}

إذا كنت بحاجة إلى مزيد من التحكم، فيمكنك تجاوز طريقة getLayoutMappings بدلاً من ذلك.

مجموعة التخطيطات

المجموعات التي يتم إرجاعها بواسطة تحويل FlexibleCast و trait HasFlexible توسع Illuminate\Support\Collection الأصلية. تعرض هذه المجموعات المخصصة طريقة find(string $name) التي تعيد أول تخطيط له اسم التخطيط $name المحدد.

مثيل التخطيط

التخطيطات هي نوع من النماذج الوهمية. تستخدم trait HasAttributes من Laravel، مما يعني أنه يمكنك تعريف accessors & mutators لسمات التخطيط. علاوة على ذلك، يمكن أيضاً الوصول إلى خصائص التخطيط باستخدام الطرق التالية:

name()

يعيد اسم التخطيط.

title()

يعيد عنوان التخطيط (كما يظهر في Nova).

key()

يعيد المفتاح الفريد للتخطيط (المعرف الفريد للتخطيط).

المزيد من التفاصيل

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

كلاسات تخطيط مخصصة

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

كلاسات إعدادات مسبقة محددة مسبقاً

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

كلاسات محلل مخصصة

بشكل افتراضي، يستفيد الحقل من عمود JSON على جدول النموذج الخاص بك. في بعض الحالات، قد ترغب حقاً في استخدام هذا الحقل، ولكن لسبب ما، سمة JSON ليست الطريقة المثلى. على سبيل المثال، قد ترغب في تخزين القيم في جدول آخر (مما يعني أنك ستستخدم حقل المحتوى المرن بدلاً من حقل BelongsToMany أو HasMany التقليدي). لا تقلق، نحن نغطيك!

أخبر الحقل بكيفية تخزين واسترجاع محتواه عن طريق إنشاء كلاس محلل خاص بك، والذي يحتوي بشكل أساسي على طريقتين بسيطتين: get و set. راجع الوثائق لمزيد من المعلومات حول هذا.

الاستخدام مع nova-page

ربما سمعت عن حزمة أخرى من حزمنا، nova-page، وهي أداة Nova تسمح بتحرير الصفحات الثابتة مثل صفحة "حول" (أو ما شابه) دون الحاجة إلى تعريف نموذج لها بشكل فردي. في كثير من الأحيان، يأتي حقل المحتوى المرن في متناول اليد. لا تقلق، كلتا الحزمتين تعملان معاً بشكل جيد! أولاً، قم بإنشاء قالب صفحة nova وأضف محتوى مرناً إلى حقول القالب.

كما هو موضح في الوثائق، يمكنك الوصول إلى المحتوى الثابت لـ nova-page في عروض blade الخاصة بك باستخدام {{ Page::get('attribute') }}. عند طلب المحتوى المرن بهذه الطريقة، فإنه يعيد سلسلة JSON خام تصف المحتوى المرن، وهو بالطبع ليس مفيداً جداً. بدلاً من ذلك، يمكنك ببساطة تطبيق trait Whitecube\NovaFlexibleContent\Concerns\HasFlexible على قوالب الصفحة الخاصة بك، والذي سيعرض طريقة الواجهة Page::flexible('attribute') وسيتولى تحويل المحتوى المرن.

namespace App\Nova\Templates;

// ...
use Whitecube\NovaFlexibleContent\Concerns\HasFlexible;

class Home extends Template
{
    use HasFlexible;

    // ...
}

💖 الرعاة

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

المساهمة

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

شكراً!

اختبارات الوحدة

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

قم بتشغيل PHPUnit عن طريق استدعاء composer test.

صنع بـ ❤️ من أجل المصادر المفتوحة

في Whitecube نستخدم الكثير من البرمجيات مفتوحة المصدر كجزء من عملنا اليومي. لذا عندما تتاح لنا فرصة لرد الجميل، نكون متحمسين للغاية!

نأمل أن تستمتع بهذه المساهمة الصغيرة منا ونود أن نسمع منك إذا وجدتها مفيدة في مشاريعك. تابعنا على Twitter لمزيد من التحديثات!