ajaxcom bundle

Everlution AjaxcomBundle

تثبيت

الخطوة 1: قم بتنزيل الحزمة

$ composer require everlutionsk/ajaxcom-bundle

الخطوة 2: تمكين الحزمة

 <?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles ()
    {
        $ bundles = array (
            // ...

            new Everlution  AjaxcomBundle  EverlutionAjaxcomBundle (),
        );

        // ...
    }

    // ...
}

الخطوة 3: قم بتضمين مكتبة Ajaxcom JavasSript ضمن تخطيط TWIG الخاص بك

قم بتثبيت @everlutionsk/ajaxcom-js عبر npm وقم بتضمين ajaxcom.js في تخطيط TWIG الخاص بك:

< script type = " text/javascript " src = " {{ asset( ' build/ajaxcom.js ' ) }} " ></ script >

آخر شيء عليك القيام به هو توفير بعض معالجات JavaScript ضمن تخطيط TWIG الخاص بك - يرجى اتباع وثائق @everlutionsk/ajaxcom-js .

إعدادات

لا تحتاج إلى تكوين أي شيء إذا كنت ترغب في استخدام قوالب رسائل الفلاش التي توفرها الحزمة.

 # all configuration is optional - following values are default
everlution_ajaxcom :
    flash_template : @EverlutionAjaxcom/flash_message.html.twig
    flash_block_id : flash_message
    persistent_class : ajaxcom-persistent
    blocks_to_render : # default value is empty array - when you provide this value, AjaxcomBundle will automatically render these blocks within each AJAX request
          - id : ' content '
          - id : ' navigation '
          - id : ' flash_message '
            refresh : true

افتراضيًا، يتجاهل AjaxcomBundle الكتل الفارغة وإذا طلب المطور عرض كتلة فارغة، فإننا نقوم بتصفية هذه الحالات. في حالة رغبتك في إعادة عرض الكتلة بمحتوى فارغ، يجب عليك تعيين علامة refresh على "صحيح" كما ترون في المثال أعلاه.

عندما تريد تعيين علامة التحديث من وحدة التحكم، فإنك تحتاج أولاً إلى إضافة الكتلة ثم تحديثها:

 <?php

public function exampleAction ()
{
    $ this -> addAjaxBlock ( ' example ' );
    $ this -> refreshAjaxBlock ( ' example ' );
    
    return $ this -> render ( ' some/template ' );
}

تعمل الحزمة بشكل أفضل مع إطار عمل Bootstrap 3+ CSS.

الاستخدام

قم بتوسيع وحدة التحكم الخاصة بك من EverlutionAjaxcomBundleControllerController أو استخدم سمة EverlutionAjaxcomBundleControllerAjaxcomTrait مع وحدة التحكم الخاصة بك للحصول على وظائف Ajaxcom.

افتراضيًا، ستتعامل مكتبة ajaxcom-js مع جميع نقرات الارتباط باستثناء النقرة ذات target="_blank" وجميع عمليات إرسال النماذج. إذا كنت بحاجة إلى تغيير المحدد أو كنت تريد الحصول على بعض التحكم في الروابط التي يتم التعامل معها بواسطة ajaxcom-js وأيها لا يمكنك تجاوز المحددات الافتراضية في تهيئة ajaxcom-js . يرجى الاطلاع على وثائق @everlutionsk/ajaxcom-js .

مثال:

< a href = " https://www.google.com " >External link</ a > <!-- won't be handled by Ajaxcom -->
< a href = " {{ path( ' remove_user ' ) }} " >Remove user</ a > <!-- will be handled by Ajaxcom -->

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

public function render($view, array $parameters = array(), Response $response = null)

تعمل حزمة Ajaxcom الخاصة بـ Everlution على توسيع طريقة render() القياسية الخاصة بـ Symfony حتى تتمكن من دمج Ajaxcom مع مشروعك دون أي تغييرات أخرى في قاعدة التعليمات البرمجية الخاصة بك.

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

ستتعامل حزمة Ajaxcom مع إجراء وحدة تحكم Symfony الخاصة بك مع طلب Ajax وطلب غير Ajax تلقائيًا، لذلك لا تحتاج إلى كتابة التعليمات البرمجية الخاصة بك مرتين - ستستدعي الحزمة نفس الإجراء دائمًا.

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

renderAjaxBlock(string $id)

من أجل عرض كتلة واحدة فقط على الصفحة ديناميكيًا، يجب عليك استيفاء الشرطين التاليين:

1. الكتلة التي تريد عرضها محاطة داخل block غصين
2. يتم وضع block الغصين داخل عنصر DOM ID له نفس اسم الكتلة

افتراضيًا، لا يدعم TWIG الواصلات في أسماء الكتل، لذا إذا كنت بحاجة إلى استخدام الواصلات داخل معرفك، فسنقوم تلقائيًا بتحويل الواصلات إلى شرطات سفلية نيابةً عنك. ومن ثم يمكنك استخدام الواصلات داخل معرفك مع مجموعة من نفس الاسم لكتلة TWIG - تحتاج فقط إلى استبدال الواصلات بشرطات سفلية. مثال: ستتم مطابقة id='custom-block' و {% block custom_block %} تلقائيًا بواسطة AjaxcomBundle.

مثال:

غصين:

< div id = " list " >
    {% block list %}
        // this is the HTML which will be replaced/removed ...
    {% endblock %}
</ div >

PHP:

 $ this -> renderAjaxBlock ( " list " );

أثناء تنفيذ وحدة التحكم الخاصة بك، ما عليك سوى الاتصال renderAjaxBlock حيث تحتاج إلى تقديم معرف الكتلة (على سبيل المثال، اسم كتلة TWIG).

عندما يتم استدعاء الإجراء الخاص بك عبر طلب Ajax، ستحتوي استجابة JSON لمكتبة Ajaxcom على معلومات حول الكتلة التي يجب إعادة عرضها باستخدام HTML.

removeAjaxBlock(string $selector)

إذا كنت تريد إزالة بعض عناصر DOM ديناميكيًا، على سبيل المثال بعد حذف بعض الصفوف من الجدول، فيمكنك استخدام طريقة removeAjaxBlock() حيث ستوفر ببساطة محدد CSS للعنصر الذي تريد إزالته.

مثال:

غصين:

< table >
    < tbody >
        < tr id = " row-1 " >< td >1.</ td ></ tr >
        < tr id = " row-2 " >< td >2.</ td ></ tr >
        < tr id = " row-3 " >< td >3.</ td ></ tr >
    </ tbody >
</ table >

PHP:

 $ this -> removeBlock ( " #row-2 " );

// OR you can use any CSS selector

$ this -> removeBlock ( " tr:nth-child(2) " );

سيقوم الكود أعلاه (كلا المثالين) بإزالة الصف الأوسط من الجدول بعد استدعاء الإجراء.

نتيجة:

< table >
    < tbody >
        < tr id = " row-1 " >< td >1.</ td ></ tr >
        <!-- the #row-2 has been removed -->
        < tr id = " row-3 " >< td >3.</ td ></ tr >
    </ tbody >
</ table >

addCallback(string $function, array $parameters = [])

يمكنك إضافة أي عدد تريده من عمليات رد اتصال JavaScript. الوسيطة الأولى لـ addCallback() هي اسم الوظيفة التي يجب استدعاؤها بعد تقديم HTML، والثانية هي مجموعة من المعلمات التي سيتم تمريرها إلى الوظيفة ككائن.

مثال:

PHP:

 $ this -> addCallback ( ' Table.init ' , [ ' some ' => ' data ' , ' other ' => [ ' data ' , ' etc ' ]]);

 var Table = function ( ) {
    return {
        init : function ( data ) {
            var some = data . some ;
            var otherArray = data . other ;
            
            // initialize table with provided data
        } ;
    }
} ; 

لا تحتاج بالضرورة إلى استخدام هذه الوظيفة

لا تحتاج فعليًا إلى استخدام هذه الوظيفة إذا كنت تريد كتابة JavaScript بالطريقة التالية:

 // additional.js
var App = {
    additional : function ( ) {
        // some additional functionality
        console . log ( 'executing App.additional' ) ;
    } ,
    // more functions within App namespace
}

App . additional ( ) ;

سيتم تنفيذ App.additional() في كل مرة يقوم فيها المتصفح بتنزيل ملف additional.js - بغض النظر عما إذا كان الطلب يتم التعامل معه مع Ajaxcom أو بدونه. كل ما عليك فعله هو التأكد من إضافة <script src="additional.js"></script> إلى DOM الخاص بك عبر Ajaxcom حيثما تكون هناك حاجة إليه.

ستضيف AjaxcomBundle جميع البرامج النصية الموجودة في كتلة javascripts إلى صفحتك تلقائيًا (سيتم إدراجها بعد آخر <script> داخل الكود الخاص بك).

replaceClass()

يمكنك بسهولة استبدال الفئة في أي كائن DOM تريده عن طريق استدعاء replaceClass() باستخدام وسيطتين - الأول هو محدد CSS الذي تختاره والثاني هو الفئة التي تريد استبدال الفئة الحالية بها.

doNotChangeUrl()

يمكنك بسهولة تجنب استبدال عنوان url للصفحة المستهدفة عن طريق استدعاء doNotChangeUrl() .

رسائل فلاش

تتم معالجة رسائل الفلاش تلقائيًا بواسطة حزمة Ajaxcom. عندما يتم استدعاء الطلب عبر Ajax، يتم عرض الومضات الموجودة في حقيبة الجلسة تلقائيًا.

ما عليك سوى تضمين قالب الغصين المقدم في مكان ما داخل تخطيط الغصين الخاص بك:

{% include " @EverlutionAjaxcom/flash_message.html.twig " %}

عند استدعاء addFlash() من وحدة التحكم الخاصة بك، يرجى استخدام EverlutionAjaxcomBundleFlash لتوفير نوع رسالة الفلاش:

 $ this -> addFlash ( Everlution  AjaxcomBundle Flash:: SUCCESS , ' Your request has been successfully handled by Ajaxcom bundle ' );

// you can use following constants:
// EverlutionAjaxcomBundleFlash::SUCCESS
// EverlutionAjaxcomBundleFlash::ERROR
// EverlutionAjaxcomBundleFlash::WARNING
// EverlutionAjaxcomBundleFlash::INFO

إرسال النماذج من خلال Ajaxcom

تتم معالجة كافة النماذج بشكل افتراضي بواسطة ajaxcom-js . يمكنك تغيير هذا السلوك عن طريق تجاوز محدد النماذج الافتراضي أثناء تهيئة ajaxcom-js . يرجى اتباع وثائق @everlutionsk/ajaxcom-js .

إعادة استخدام مصادر البيانات

من أجل إعادة استخدام مصدر البيانات بين علامات التبويب المتعددة، يمكنك بسهولة إنشاء وظائف Twig عن طريق توسيع BaseDataSource الخاص بنا.

ما عليك سوى إضافة البيان التالي إلى Services.yml الخاص بك:

    AppBundleDataProvider :
        resource : ' ../../src/AppBundle/DataProvider '
        tags : ['twig.extension']

يمكنك تحديد أي مجلد تريده داخل مشروعك. في هذا المثال، اخترنا مساحة الاسم AppBundleDataProvider .

يتم فحص كل فئة ضمن مساحة الاسم هذه والتي تمتد EverlutionAjaxcomBundleDataSourceBaseDataSource بحثًا عن الأساليب العامة ذات اللاحقة Provider عبر الانعكاس ونقوم بإنشاء وظائف Twig البسيطة من هذه الطرق. دعونا نرى المثال:

 // AppBundleDataProviderExample.php

// simple function which returns static array
public function navigationProvider () {
    return [ 
        // some data... 
    ];
}

// you can use parametrical functions and injected services as well
public function userProfileProvider ( int $ id ) {
    return $ this -> someService -> getData ( $ id );
}

بعد إنشاء مثل هذه الفئة، يمكنك ببساطة استدعاء الوظيفة داخل الغصين:

{{ dump (navigation()); }} {# will dump static array #}

{% for item in userProfile( 2 ) %}
   {{ dump ( item ) }}
{% endfor %}

أفضل الممارسات

إذا كنت تريد استخدام AjaxcomBundle بسلاسة، فيجب عليك نسخ @EverlutionAjaxcomlayout_bootstrap_4.html.twig إلى مشروعك (على سبيل المثال AppBundle) وتعديله ليناسب احتياجاتك.

بهذه الطريقة ستتعامل AjaxcomBundle مع مهام مثل استبدال JavaScripts وStyleSheets وMetaTags نيابةً عنك.

استخدم الاستبدال الآلي لـ JS وCSS وMeta وTitle

عند استخدام الكتل من @EverlutionAjaxcomlayout_bootstrap_4.html.twig يجب أن تكون جاهزًا تمامًا.

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

استبدال جافا سكريبت

1. يجب أن تحتوي جميع ملفات JavaScript التي يجب تضمينها في كل صفحة على class='ajaxcom-persistent' (أو أي شيء قمت بتعيينه ضمن تكوين الحزمة)
2. يجب أن يحتوي تخطيطك الرئيسي الذي تقوم بتوسيعه على {% block javascripts %}{% endblock %}
3. عندما تقوم بتوسيع تخطيطك الرئيسي وتقوم بإعادة كتابة كتلة javascripts ، سيقوم AjaxcomBundle بتحميل البرامج النصية من هذه الكتلة تلقائيًا لك

استبدال أوراق الأنماط

1. مثل JavaScript، يجب أن تحتوي جميع أوراق الأنماط التي يجب تضمينها في كل صفحة class='ajaxcom-persistent' (أو أي شيء قمت بتعيينه ضمن تكوين الحزمة)
2. يجب أن يحتوي تخطيطك الرئيسي الذي تقوم بتوسيعه على {% block stylesheets %}{% endblock %}
3. عندما تقوم بتوسيع تخطيطك الرئيسي وتقوم بإعادة كتابة كتلة stylesheets سيقوم AjaxcomBundle بتحميل الأنماط من هذه الكتلة تلقائيًا نيابة عنك

استبدال العلامات الوصفية والعنوان

1. يجب أن تحتوي جميع العلامات الوصفية التي يجب أن تكون موجودة في كل صفحة class='ajaxcom-persistent' (أو أي شيء قمت بتعيينه ضمن تكوين الحزمة)
2. يجب أن يحتوي تخطيطك الرئيسي الذي تقوم بتوسيعه على {% block metatags %}{% endblock %}
3. عندما تقوم بتوسيع التصميم الرئيسي الخاص بك وتقوم بإعادة كتابة كتلة metatags سيقوم AjaxcomBundle بتحميل العلامات الوصفية من هذه الكتلة تلقائيًا نيابة عنك
4. إذا كنت تريد تغيير title الصفحة، فيجب أن يحتوي تخطيطك على <title>{% block title %}{% endblock %}</title> وتحتاج إلى إعادة كتابة مقطع title داخل القالب حيث تقوم بتوسيع القالب الرئيسي الخاص بك

المهام

• إضافة مثال الاستخدام المعقد