grav plugin tntsearch

TNTSearch Plugin

البرنامج المساعد TNTSearch مخصص لـ Grav CMS. محرك البحث الكامل المستند إلى الفهرسة القوي المدعوم من مكتبة TNTSearch التي توفر عمليات بحث سريعة عن محتوى GRAV المستندة إلى AJAX. يعد هذا البرنامج المساعد مرنًا للغاية ، مما يتيح فهارس بيانات المحتوى التعسفي بالإضافة إلى قوالب غصين مخصصة لتوفير الفرصة لفهرسة أنواع الصفحات الديناميكية الأخرى. يوفر TNTSearch CLI بالإضافة إلى الإدارة القائمة على المشرف وإعادة الفهرس ، بالإضافة إلى أداة بحث أمامية مدفوعة في AJAX.

ملاحظة: يتطلب TNTSearch الإصدار 3.0.0 الآن Grav 1.6.0 أو الأحدث للعمل لأنه يستخدم وظائف جديدة غير متوفرة في الإصدارات السابقة.

تثبيت

يمكن أن يتم تثبيت البرنامج المساعد TNT Search بواحدة من طريقتين. تتيح لك طريقة تثبيت GPM (MANGER Package Manager) لتثبيت المكون الإضافي بسرعة وسهولة بتثبيت المكون الإضافي باستخدام أمر طرفي بسيط ، في حين أن الطريقة اليدوية تتيح لك القيام بذلك عبر ملف مضغوط.

تثبيت GPM (المفضل)

إن أبسط طريقة لتثبيت هذا البرنامج المساعد هي عبر Manager Manager (GPM) من خلال محطة نظامك (تسمى أيضًا سطر الأوامر). من جذر تثبيت الجاذبية الخاص بك:

 bin/gpm install tntsearch

سيؤدي ذلك إلى تثبيت البرنامج المساعد TNT Search في دليل /user/plugins داخل GRAV. يمكن العثور على ملفاتها ضمن /your/site/grav/user/plugins/tntsearch .

متطلبات

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

• قاعدة بيانات SQLITE3
• تمديد PHP PDO
• PHP PDO_SQLITE DRIVER
• برنامج تشغيل PHP PDO_MYSQL (مطلوب فقط لأن المكتبة تشير إلى بعض ثوابت MySQL ، لا يتم استخدام MySQL DB)

| يأتي PHP افتراضيًا مع PDO والغالبية العظمى من الأنظمة المستندة إلى Linux تأتي بالفعل مع SQLite.

تركيب SQLite على أنظمة MAC

يأتي SQLite بالفعل مثبتًا مسبقًا على جهاز Mac الخاص بك ، ولكن يمكنك ترقيته إلى أحدث إصدار مع Homebrew:

تثبيت homebrew

$ /usr/bin/ruby -e " $( curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install ) "

تثبيت sqlite مع homebrew

$ brew install sqlite

تثبيت sqlite على أنظمة Windows

قم بتنزيل الإصدار المناسب من SQLite من صفحة تنزيل SQLite.

استخراج ملف zip الذي تم تنزيله وقم بتشغيل sqlite3.exe القابلة للتنفيذ.

إعدادات

قبل تكوين هذا البرنامج المساعد ، يجب عليك نسخ user/plugins/tntsearch/tntsearch.yaml إلى user/config/plugins/tntsearch.yaml وتحرير تلك النسخ فقط.

فيما يلي التكوين الافتراضي وشرح للخيارات المتاحة:

 enabled : true
search_route : ' /search '
query_route : ' /s '
built_in_css : true
built_in_js : true
built_in_search_page : true
enable_admin_page_events : true
search_type : auto
fuzzy : false
distance : 2
phrases : true
stemmer : ' no '
display_route : true
display_hits : true
display_time : true
live_uri_update : true
limit : 20
min : 3
snippet : 300
index_page_by_default : true
scheduled_index :
    enabled : false
    at : ' 0 */3 * * * '
    logs : ' logs/tntsearch-index.out '
filter :
  items :
    - [email protected]
powered_by : true
search_object_type : Grav      

خيارات التكوين هي كما يلي:

• enabled - تمكين أو تعطيل البرنامج المساعد على الفور
• search_route - المسار المستخدم في صفحة البحث المدمجة
• query_route - المسار الذي يستخدمه نموذج البحث للاستعلام عن محرك البحث
• built_in_css - تمكين أو تعطيل تصميم CSS المدمج
• built_in_js - تمكين أو تعطيل JavaScript المدمج
• built_in_search_page - تمكين أو تعطيل صفحة البحث المدمجة
• enable_admin_page_events - تمكين أو تعطيل أحداث الصفحة التي تحدث on-save لإضافة/تحديث/إزالة الصفحة في الفهرس
• search_type - يمكن أن يكون أحد هذه الأنواع:
  • basic - مطابقة السلسلة القياسية
  • boolean - دعم or minus . مثل foo -bar
  • auto - يكتشف تلقائيًا ما إذا كنت تريد استخدام basic أو boolean
• fuzzy - المباريات إذا كانت الكلمات "قريبة" ولكن ليس بالضرورة مطابقة دقيقة
• distance - Levenshtein المسافة من البحث الغامض. يمثل مقدار الأحرف التي تحتاج إلى تغيير أو إزالتها أو إضافتها في كلمة واحدة من أجل مطابقة الكلمة الرئيسية للبحث. زيادة المسافة تنتج المزيد من نتائج البحث ولكنها تقلل من دقة البحث.
• phrases - معالجة الدعم تلقائيًا للعبارات
• stemmer - يمكن أن يكون أحد هذه الأنواع:
  • no - لا ساق
  • arabic - اللغة العربية
  • croatian - اللغة الكرواتية
  • german - اللغة الألمانية
  • اللغة italian - الإيطالية
  • porter - Porter STEMMER للغة الإنجليزية
  • portuguese - اللغة البرتغالية
  • russian - اللغة الروسية
  • ukrainian - اللغة الأوكرانية
• display_route - عرض المسار في نتائج البحث
• display_hits - عرض عدد الزيارات في نتائج البحث
• display_time - عرض وقت التنفيذ في نتائج البحث
• live_uri_update - عند تمكين built_in_js ، يقوم Live بتحديث شريط URI في صفحة search_route
• limit - الحد الأقصى لمقدار النتائج التي سيتم عرضها
• min - Mininum كمية من الأحرف المكتوبة قبل إجراء البحث
• snippet - كمية الأحرف لمعاينة عنصر النتيجة
• index_page_by_default - إذا تم فهرسة جميع الصفحات افتراضيًا ما لم يتم تجاوز Frontmatter
• scheduled_index - مهمة فهرس مجدولة جديدة. تم تعطيله افتراضيًا ، عند تمكينه لتشغيله كل 3 ساعات ، ونتائج الإخراج إلى logs/tntsearch-index.out
• filter - مرشح مجموعات الصفحات يتيح لك اختيار صفحات محددة للفهرس عبر استعلام مجموعة
• powered_by - عرض نص TNTSEARCH الذي يعمل بالطاقة
• search_object_type - يسمح للفئات المخصصة بتجاوز دعم صفحة الجاذبية الافتراضية. يتيح ذلك إمكانيات البحث المخصصة تمامًا لأي نوع من البيانات.

الاستخدام

يعتمد TNTSearch على محتوىك الذي يتم فهرسته في قاعدة بيانات فهرس SQLite قبل إجراء أي استعلامات بحث. يشبه هذا إلى حد كبير محركات البحث الأخرى مثل Elasticsearch و Solr و Lucene ، وما إلى ذلك ، ولكنه يستخدم مكتبة TNTSearch محرك بحث PHP ببساطة لتحقيق ذلك مع القليل من الإعداد وبدون متاعب.

الفهرسة

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

فهرسة CLI

أولاً إذا كنت قادرًا على الوصول إلى CLI أو مجرد اختيار عدم استخدام المكون الإضافي للمسؤول ، يمكنك استخدام أمر CLI المدمج:

$ bin/plugin tntsearch index

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

Re-indexing Search

Added 1 /
Added 2 /blog/classic-modern-architecture
Added 3 /blog/daring-fireball-link
Added 4 /blog/focus-and-blur
Added 5 /blog/just-some-text-today
Added 6 /blog/london-industry
Added 7 /blog/random-thoughts
Added 8 /blog/sunshine-in-the-hills
Added 9 /blog/the-urban-jungle
Total rows 9
Done.

يشير هذا إلى فهرسة ناجحة للمحتوى الخاص بك.

فهرسة المكون الإضافي للمسؤول

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

بدلاً من ذلك ، يمكنك الانتقال إلى قسم تكوين TNTSearch والنقر فوق زر Index Content :

تخطي الفهرسة

ملاحظة: سيتم تخطي أي صفحة تستخدم سمة رأس صفحة redirect أثناء الفهرسة.

يمكنك تخطي صفحة صريحة في مرشح الفهرس عن طريق إضافة هذا yaml إلى رأس الصفحة:

 tntsearch:
    index: false

دعم متعدد اللغات

مع الإصدار 3.0 الجديد من TNTSearch ، تمت إضافة الدعم للغات المتعددة (Grav 1.6 مطلوب). داخليًا ، هذا يعني أنه بدلاً من ذلك تخزين الفهرس كمستخدم user:://data/tntsearch/grav.index ، يتم إنشاء فهارس متعددة لكل لغة تم تكوينها في GRAV. على سبيل المثال ، إذا قمت بتعيين اللغات المدعومة على ['en', 'fr', 'de'] ، ثم عند إجراء فهرس ، ستحصل على ثلاثة ملفات: en.index ، fr.index ، و de.index . عند الاستعلام عن اللغة النشطة المناسبة ، يحدد الفهرس الذي يتم الاستعلام عنه. على سبيل المثال ، سيؤدي إجراء البحث على صفحة تسمى /fr/search إلى قاعدة بيانات fr.index لاستخدامها ، ونتائج الفرنسية المراد إرجاعها.

ستستغرق الفهرسة ملاحظة وقتًا أطول اعتمادًا على عدد اللغات التي تدعمها حيث يتعين على TNTSearch فهرسة كل صفحة في كل لغة.

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

دعم الجدولة

واحدة من الميزات الجديدة الرائعة لـ GRAV 1.6 هي الجدولة المدمجة التي تسمح بتشغيل وظائف مكونة من البرنامج المساعد بشكل دوري. TNTSearch هي حالة استخدام رائعة لهذه الإمكانية لأنها تتيح تشغيل وظيفة الفهرسة لتشغيلها كل بضع ساعات دون الحاجة إلى الحفاظ على الأمور متزامنة يدويًا. هناك بعض الخيارات التي تسمح لك بتكوين هذه الإمكانية.

لاحظ أولاً ، أن وظيفة المجدول هذه يتم تعطيلها افتراضيًا ، لذلك يجب عليك أولاً تمكين وظائف الجدولة في إعدادات البرنامج المساعد TNTSearch. بعد ذلك يمكنك تكوين عدد المرات التي يجب أن تعمل فيها مهمة الفهرسة. الافتراضي هو كل 3 ساعات. أخيرًا ، يمكنك تكوين مكان تسجيل أي إخراج فهرسة إليه.

أحداث صفحات المسؤول

بمجرد حصولك على فهرس ، يستفيد TNTSearch من أحداث المسؤول إلى إدخالات reate و u pdate و d elete عند تحرير الصفحات. إذا كان الفهرس الخاص بك يبدو أنه خارج المزامنة ، فيمكنك ببساطة إعادة إثارة موقعك بأكمله.

تخصيص فهرس البحث

إضافة الحقول المخصصة

افتراضيًا ، سيقوم البرنامج المساعد TNTSearch بفهرسة title صفحتك content صفحتك. هذا عادة ما يكفي بالنسبة لمعظم الحالات ، ولكن هناك حالات قد ترغب في فهرسة المزيد من الحقول. يقدم البرنامج المساعد مثالاً على ذلك من خلال الاستماع إلى حدث onTNTSearchIndex :

 public static function getSubscribedEvents ()
{
    return [
        ' onTNTSearchIndex ' => [ ' onTNTSearchIndex ' , 0 ]
    ];
}

public function onTNTSearchIndex ( Event $ e )
{
    $ fields = $ e [ ' fields ' ];
    $ page = $ e [ ' page ' ];

    if ( isset ( $ page -> header ()-> author )) {
        $ fields -> author = $ page -> header ()-> author ;
    }
}

يتيح لك ذلك إضافة مؤلف إلى الحقول المفهرسة إذا تم تعيينه في Page Frontmatter. يمكنك إضافة الحقول المخصصة الخاصة بك مع مكون إضافي بسيط للغاية يستمع إلى هذا الحدث.

توفير قوالب عرض مخصصة

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

على سبيل المثال ، لنفترض أن لدينا صفحة رئيسية مبنية من بضع صفحات فرعية معيارية مع محتوى صغير تحتها ، فهي تسمى home.md ، لذلك يستخدم ملف home.html.twig في templates/ المجلد الخاص بالموضوع. يمكنك إنشاء إصدار مبسط من هذا القالب وحفظه templates/tntsearch/home.html.twig . لهذا المثال ، يبدو هذا القالب هكذا:

{% for module in page. collection () %}
< p >
    {{ module . content | raw }}
</ p >
{% endfor %}

{{ page . content | raw }}

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

لتوجيه TNTSearch إلى الفهرس باستخدام هذا القالب بدلاً من مجرد استخدام محتوى الصفحة في حد ذاته ، تحتاج فقط إلى إضافة إدخال في home.md .

 tntsearch :
    template : ' tntsearch/home '

البحث

يأتي TNTSearch Plugin for Grav مع صفحة استعلام مدمجة يمكن الوصول إليها عبر مسار /search افتراضيًا. صفحة البحث هذه عبارة عن حقل إدخال بسيط سيؤدي استعلام Ajax as-you . نظرًا لأن TNTSearch سريع جدًا ، فستحصل على استجابة بحث في الوقت الفعلي بطريقة مماثلة لبحث Google. كما يتم إرجاع النتائج التي تم تسليط الضوء عليها بالفعل لمطابقة المصطلحات.

يمكنك أيضًا اختبار البحث مع CLI:

 $ bin/plugin tntsearch query ipsum

{
    "number_of_hits" : 3 ,
    "execution_time" : " 2.101 ms " ,
    "hits" : [
        {
            "link" : " / blog / classic-modern-architecture " ,
            "title" : " Classic Modern Architecture " ,
            "content" : " ...sed a odio. Curabitur ut lectus tortor. Sed <em>ipsum< / em> eros, egestas ut eleifend non, elementum vitae eros. Mauris felis diam, pellentesque vel lacinia ac, dictum a nunc. n Lorem <em>ipsum< / em> dolor sit amet, consectetur adipiscing elit. Donec ultricies tristique nulla et mattis. Phasellus id massa eget... "
        },
        {
            "link" : " / blog / focus-and-blur " ,
            "title" : " Focus and Blur " ,
            "content" : " ...sed a odio. Curabitur ut lectus tortor. Sed <em>ipsum< / em> eros, egestas ut eleifend non, elementum vitae eros. Mauris felis diam, pellentesque vel lacinia ac, dictum a nunc. n Lorem <em>ipsum< / em> dolor sit amet, consectetur adipiscing elit. Donec ultricies tristique nulla et mattis. Phasellus id massa eget... "
        },
        {
            "link" : " / blog / london-industry " ,
            "title" : " London Industry at Night " ,
            "content" : " ...sed a odio. Curabitur ut lectus tortor. Sed <em>ipsum< / em> eros, egestas ut eleifend non, elementum vitae eros. Mauris felis diam, pellentesque vel lacinia ac, dictum a nunc. n Lorem <em>ipsum< / em> dolor sit amet, consectetur adipiscing elit. Donec ultricies tristique nulla et mattis. Phasellus id massa eget... "
        }
    ]
}

تخصيص صفحة البحث

إذا تم العثور على صفحة الجاذبية المادية لمسار /search ، فسيستخدم TNTSearch ذلك بدلاً من الصفحة التي يوفرها المكون الإضافي. يتيح لك ذلك إضافة محتوى بسهولة إلى صفحة البحث الخاصة بك حسب الحاجة. إذا كنت ترغب في تخصيص إخراج HTML الفعلي ، فما عليك سوى نسخ templates/search.html.twig من المكون الإضافي إلى السمة وتخصيصه.

يمكن أيضًا تعديل حقل الإدخال الفعلي حسب الحاجة من خلال النسخ وتحرير الملفات templates/partials/tntsearch.html.twig إلى موضوعك وتعديله.

تخصيص بيانات الاستعلام

افتراضيًا ، يتم إرسال المكون الإضافي TNTSearch لـ GRAV ، ويتم إرسال استجابة JSON مع الهيكل التالي:

{
    "number_of_hits" : 3 ,
    "execution_time" : " 1.000 ms " ,
    "hits" : [
        {
            "link" : " /page-a " ,
            "title" : " Title A " ,
            "content" : " highlighted-summary "
        },
        {
            "link" : " /page-b " ,
            "title" : " Title B " ,
            "content" : " highlighted-summary "
        },
        {
            "link" : " /page-c " ,
            "title" : " Title C " ,
            "content" : " highlighted-summary "
        }
    ]
}

هناك حالات يكون فيها هذا الإخراج غير مرغوب فيه أو يجب تغييره. يوفر TNTSearch فعليًا حدثًا إضافيًا للسماح لك بمعالجة هذا التنسيق. مثال على ذلك يمكن رؤيته أدناه:

 public static function getSubscribedEvents () {
    return [
        ' onTNTSearchQuery ' => [ ' onTNTSearchQuery ' , 1000 ],
    ];
}

public function onTNTSearchQuery ( Event $ e )
{
    $ query = $ this -> grav [ ' uri ' ]-> param ( ' q ' );

    if ( $ query ) {
        $ page = $ e [ ' page ' ];
        $ query = $ e [ ' query ' ];
        $ options = $ e [ ' options ' ];
        $ fields = $ e [ ' fields ' ];
        
        $ fields -> results [] = $ page -> route ();
        $ e -> stopPropagation ();
    }
}

الأشياء المهمة التي يجب ملاحظتها هي قيمة الطلب 1000 لضمان تشغيل هذا الحدث قبل الحدث الافتراضي في ملف البرنامج المساعد tntsearch.php . تضع طريقة الحدث الفعلية ببساطة صفيف نتائج على الحقول إلى طريق ما ، مما يؤدي إلى:

{
    "number_of_hits" : 3 ,
    "execution_time" : " 1.000 ms " ,
    "results" : [ '/page-a', '/page-b', '/page-c' ]
}

حقل البحث المنسدلة

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

{% embed ' partials/tntsearch.html.twig ' with { limit : 10 , snippet : 150 , min : 3 , search_type : ' auto ' , dropdown : true } %}{% endembed %}

هنا قمنا بتضمين الجزئي الافتراضي ، لكننا تجاوزنا options عن طريق تمريرها في with . من المهم أن نلاحظ أن القائمة dropdown: true يجب تعيينه من أجل تفسيره على أنه المنسدلة.

الاعتمادات

لن يكون هذا البرنامج المساعد ممكنًا بدون مكتبة TNTSearch المذهلة لـ PHP. تأكد من قيامك بدور هذا المشروع على جيثب.