يوفّر تطبيق البحث المصغّر واجهة بحث قابلة للتخصيص لتطبيقات الويب. لا تتطلّب الأداة سوى جزء صغير من رمز HTML وJavaScript لتنفيذها وتفعيل ميزات البحث الشائعة، مثل السمات وتقسيم الصفحات. يمكنك أيضًا تخصيص أجزاء من الواجهة باستخدام CSS وJavaScript.
إذا كنت بحاجة إلى مرونة أكبر مما تقدّمه الأداة المصغّرة، ننصحك باستخدام واجهة برمجة التطبيقات Query API. للحصول على معلومات عن إنشاء واجهة بحث باستخدام Query API، راجِع مقالة إنشاء واجهة بحث باستخدام Query API.
إنشاء واجهة بحث
يتطلّب إنشاء واجهة البحث عدة خطوات:
- ضبط تطبيق بحث
- إنشاء معرّف عميل للتطبيق
- إضافة ترميز HTML لمربّع البحث والنتائج
- تحميل التطبيق المصغّر على الصفحة
- إعداد التطبيق المصغّر
ضبط تطبيق بحث
يجب أن تحتوي كل واجهة بحث على تطبيق بحث محدّد في وحدة تحكّم المشرف. يقدّم تطبيق البحث معلومات إضافية لطلب البحث، مثل مصادر البيانات والعناصر المميّزة وإعدادات جودة البحث.
لإنشاء تطبيق بحث، يُرجى الرجوع إلى مقالة إنشاء تجربة بحث مخصّصة.
إنشاء معرّف عميل للتطبيق
بالإضافة إلى الخطوات الواردة في مقالة ضبط أذونات الوصول إلى Google Cloud Search API، يجب أيضًا إنشاء معرّف عميل لتطبيق الويب.
عند ضبط المشروع:
- اختيار نوع العميل متصفّح الويب
- قدِّم معرّف الموارد المنتظم (URI) لمصدر تطبيقك.
- ملاحظة عن معرّف العميل الذي تم إنشاؤه ستحتاج إلى رقم تعريف العميل لإكمال الخطوات التالية. لا يلزم إدخال مفتاح سر العميل لتطبيق الشريط الجانبي.
للحصول على معلومات إضافية، يُرجى الاطّلاع على مقالة بروتوكول OAuth 2.0 لتطبيقات الويب من جهة العميل.
إضافة ترميز HTML
يتطلب التطبيق المصغّر قدرًا صغيرًا من رموز HTML لكي يعمل. عليك تقديم ما يلي:
- عنصر
input
لمربّع البحث - عنصر لتثبيت النافذة المنبثقة للاقتراح عليه
- عنصر يحتوي على نتائج البحث
- (اختياري) قدِّم عنصرًا يحتوي على عناصر التحكّم في السمات.
يعرض مقتطف HTML التالي رمز HTML لأداة بحث مصغّرة، حيث يتم تحديد
العناصر التي سيتم ربطها باستخدام سمة id
:
تحميل التطبيق المصغّر
يتم تحميل التطبيق المصغّر ديناميكيًا من خلال نص برمجي لتحميل التطبيقات. لتضمين
أداة التحميل، استخدِم العلامة <script>
كما هو موضّح:
يجب تقديم دالة استدعاء onload
في علامة النص البرمجي. يتم استدعاء الدالة
عندما يكون أداة التحميل جاهزة. عندما يصبح أداة التحميل جاهزة، واصِل تحميل التطبيق المصغّر
من خلال استدعاء gapi.load()
لتحميل وحدة "Google Sign-in" و"Cloud Search" و"Google API Client Library".
يتم استدعاء الدالة initializeApp()
بعد loadingتحميل كل الوحدات.
إعداد التطبيق المصغّر
أولاً، عليك إعداد مكتبة العملاء من خلال استدعاء gapi.client.init()
أو gapi.auth2.init()
باستخدام معرّف العميل الذي تم إنشاؤه
ونطاق https://www.googleapis.com/auth/cloud_search.query
. بعد ذلك، استخدِم فئتي
gapi.cloudsearch.widget.resultscontainer.Builder
و
gapi.cloudsearch.widget.searchbox.Builder
لضبط التطبيق المصغّر
وربطه بعناصر HTML.
يوضّح المثال التالي كيفية إعداد التطبيق المصغّر:
يشير المثال أعلاه إلى متغيّرَين للإعدادات تم تعريفهما على النحو التالي:
تخصيص تجربة تسجيل الدخول
يطلب التطبيق المصغّر تلقائيًا من المستخدمين تسجيل الدخول وتفويض التطبيق في الوقت الذي يبدأون فيه كتابة طلب بحث. يمكنك استخدام ميزة "تسجيل الدخول باستخدام حساب Google" للمواقع الإلكترونية لتوفير تجربة تسجيل دخول مخصّصة أكثر للمستخدمين.
تفويض المستخدمين مباشرةً
استخدِم ميزة تسجيل الدخول باستخدام حساب Google لتتبُّع حالة تسجيل دخول
المستخدم وتسجيل دخول المستخدمين أو تسجيل خروجهم حسب الحاجة. على سبيل المثال، يرصد المثال التالي حالة isSignedIn
لرصد التغييرات في تسجيل الدخول ويستخدم GoogleAuth.signIn()
الطريقة لبدء تسجيل الدخول من خلال نقرة على زر:
لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة تسجيل الدخول باستخدام حساب Google.
تسجيل دخول المستخدمين تلقائيًا
يمكنك تبسيط تجربة تسجيل الدخول بشكل أكبر من خلال تفويض التطبيق مسبقًا نيابةً عن المستخدمين في مؤسستك. تكون هذه التقنية مفيدة أيضًا عند استخدام Cloud Identity Aware Proxy لحماية التطبيق.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة استخدام ميزة "تسجيل الدخول باستخدام حساب Google" مع تطبيقات تكنولوجيا المعلومات.
تخصيص الواجهة
يمكنك تغيير مظهر واجهة البحث من خلال مجموعة من التقنيات:
- إلغاء الأنماط باستخدام CSS
- تزيين العناصر باستخدام محوِّل
- إنشاء عناصر مخصّصة باستخدام محوِّل
إلغاء الأنماط باستخدام CSS
تأتي الأداة المصغّرة للبحث مع ملف CSS الخاص بها لتنسيق عناصر الاقتراحات والنتائج، بالإضافة إلى عناصر التحكّم في تقسيم الصفحات. ويمكنك إعادة تصميم هذه العناصر حسب الحاجة.
أثناء التحميل، تحمّل أداة البحث ملفّ أسلوبها التلقائي بشكل ديناميكي. ويحدث ذلك بعد تحميل أوراق أسلوب التطبيق، ما يؤدي إلى رفع أولوية القواعد. لضمان أنّ أنماطك لها الأولوية على الأنماط التلقائية، استخدِم أدوات اختيار السلف لزيادة دقة القواعد التلقائية.
على سبيل المثال، لن يكون للقاعدة التالية أي تأثير في حال تحميلها في علامة static
link
أو style
في المستند.
.cloudsearch_suggestion_container {
font-size: 14px;
}
بدلاً من ذلك، يمكنك تحديد القاعدة باستخدام رقم تعريف أو فئة الحاوية الأصل المُعلَن عنها في الصفحة.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
للحصول على قائمة بفئات الدعم وأمثلة على علامات HTML التي تُنشئها الأداة المصغّرة، اطّلِع على مرجع فئات CSS المتوافقة.
تزيين العناصر باستخدام محوِّل
لتزيين عنصر قبل عرضه، أنشئ ومقدِّم ومقدِّمًا
محوِّلًا ينفِّذ إحدى طرق الزخرفة، مثل
decorateSuggestionElement
أو decorateSearchResultElement.
على سبيل المثال، تُضيف المحوِّلات التالية فئة مخصّصة إلى عناصر الاقتراح والنتيجة.
لتسجيل المحوِّل عند إعداد التطبيق المصغّر، استخدِم setAdapter()
طريقة فئة Builder
المعنية:
يمكن للعناصر الزخرفية تعديل سمات عنصر الحاوية بالإضافة إلى أي عناصر فرعية. يمكن إضافة عناصر فرعية أو إزالتها أثناء الزخرفة. ومع ذلك، في حال إجراء تغييرات هيكلية على العناصر، ننصحك بإنشاء العناصر مباشرةً بدلاً من تزيينها.
إنشاء عناصر مخصّصة باستخدام محوِّل
لإنشاء عنصر مخصّص لاقتراح أو حاوية سمة أو نتيجة بحث،
أنشئ محوِّلًا وسجِّله لتنفيذ
createSuggestionElement
،
createFacetResultElement
،
أو createSearchResultElement
على التوالي.
توضّح المحوِّلات التالية كيفية إنشاء عناصر مخصّصة للاقتراحات ونتائج البحث باستخدام علامات HTML <template>
.
لتسجيل المُحوِّل عند إعداد التطبيق المصغّر، استخدِم طريقة setAdapter()
لفئة Builder
المعنية:
يخضع إنشاء عناصر شرائح مخصّصة باستخدام createFacetResultElement
لعدة قيود:
- يجب إرفاق فئة CSS
cloudsearch_facet_bucket_clickable
بال العنصر الذي ينقر عليه المستخدمون لتبديل حزمة. - يجب لف كل حزمة في عنصر يحتوي عليها باستخدام فئة CSS
cloudsearch_facet_bucket_container
. - لا يمكنك عرض الحِزم بترتيب مختلف عن الترتيب الذي تظهر به في الردّ.
على سبيل المثال، يعرض المقتطف التالي السمات باستخدام الروابط بدلاً من مربّعات الاختيار.
تخصيص سلوك البحث
تمثّل إعدادات تطبيق البحث الإعدادات التلقائية لواجهة البحث، وهي ثابتة. لتنفيذ فلاتر أو واجهات ديناميكية، مثل السماح للمستخدمين بتبديل مصادر البيانات، يمكنك تجاوز إعدادات تطبيق البحث من خلال اعتراض طلب البحث باستخدام محوِّل.
نفِّذ محوِّلًا باستخدام الأسلوب
interceptSearchRequest
لتعديل الطلبات المقدَّمة إلى
Search API
قبل التنفيذ.
على سبيل المثال، يعترض المحوِّل التالي الطلبات لحصر طلبات البحث بمصدر يختارّه المستخدم:
لتسجيل المحوِّل عند إعداد التطبيق المصغّر، استخدِم الأسلوب
setAdapter()
عند إنشاء ResultsContainer
.
يتم استخدام رمز HTML التالي لعرض مربّع اختيار للفلترة حسب المصادر:
تستمع التعليمة البرمجية التالية إلى التغيير، وتضبط الاختيار، و تُعيد تنفيذ الطلب إذا لزم الأمر.
يمكنك أيضًا اعتراض استجابة البحث من خلال تنفيذ
interceptSearchResponse
في المحوِّل.
تثبيت إصدار واجهة برمجة التطبيقات
يستخدم التطبيق المصغّر تلقائيًا أحدث إصدار ثابت من واجهة برمجة التطبيقات. لقفل
إصدار معيّن، اضبط مَعلمة الضبط cloudsearch.config/apiVersion
على الإصدار المفضّل قبل بدء التطبيق المصغّر.
سيتم ضبط إصدار واجهة برمجة التطبيقات تلقائيًا على 1.0 في حال عدم ضبطه أو ضبطه على قيمة غير صالحة.
تثبيت إصدار التطبيق المصغّر
لتجنّب حدوث تغييرات غير متوقّعة على واجهات البحث، اضبط مَعلمة الضبط
cloudsearch.config/clientVersion
على النحو الموضّح:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
سيتم ضبط إصدار التطبيق المصغّر تلقائيًا على 1.0 في حال عدم ضبطه أو ضبطه على قيمة غير صالحة.
تأمين واجهة البحث
تحتوي نتائج البحث على معلومات حسّاسة للغاية. اتّبِع أفضل الممارسات لتأمين تطبيقات الويب، خاصةً ضد هجمات التصيّد الاحتيالي بالنقر.
لمزيد من المعلومات، يُرجى الاطّلاع على مشروع دليل OWASP.
تفعيل تصحيح الأخطاء
استخدِم interceptSearchRequest
لتفعيل تصحيح الأخطاء لأداة البحث المصغّرة. على سبيل المثال:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;