Programmable Search Element Control API

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

يتم تحميل جميع رموز JavaScript بشكل غير متزامن، ما يسمح لصفحة الويب بمواصلة التحميل بينما يسترد المتصفّح رمز JavaScript الخاص بـ "محرك البحث المبرمَج".

Introduction

يقدّم هذا المستند نموذجًا أساسيًا لإضافة عناصر "محرك البحث المبرمَج" إلى صفحة الويب، بالإضافة إلى شرح للمكوّنات القابلة للضبط في العنصر وJavaScript API المرن.

النطاق

يوضِّح هذا المستند كيفية استخدام الدوال والخصائص الخاصة بواجهة برمجة التطبيقات Programmable Search Engine Control API.

توافُق المتصفّح

يمكنك الاطّلاع على قائمة المتصفحات المتوافقة مع "محرك البحث المبرمَج" هنا.

الجمهور

هذا المستند موجّه للمطوّرين الذين يريدون إضافة وظيفة "البحث المبرمَج من Google" إلى صفحاتهم.

عناصر "البحث المبرمَج"

يمكنك استخدام ترميز HTML لإضافة عنصر "البحث المبرمَج" إلى صفحتك. يتألف كل عنصر من مكوّن واحد على الأقل: مربّع بحث أو مجموعة من نتائج البحث أو كليهما. يقبل مربّع البحث البيانات التي يدخلها المستخدم بأي من الطرق التالية:

  • طلب بحث مكتوب في حقل إدخال النص
  • سلسلة طلب مضمّنة في عنوان URL
  • التنفيذ الآلي

بالإضافة إلى ذلك، يقبل قسم نتائج البحث الإدخال بالطرق التالية:

  • سلسلة طلب مضمّنة في عنوان URL
  • التنفيذ الآلي

تتوفّر الأنواع التالية من عناصر "البحث المبرمَج":

نوع العنصر المكوّنات الوصف
القيمة العادية <div class="gcse-search"> مربّع بحث ونتائج بحث، يتم عرضها في <div> نفسه.
عمودان <div class="gcse-searchbox"> و<div class="gcse-searchresults"> تنسيق من عمودَين مع نتائج البحث على أحد الجانبَين ومربّع بحث على الجانب الآخر إذا كنت تخطّط لإدراج عناصر متعدّدة في وضع العمودين في صفحة الويب، يمكنك استخدام السمة gname لربط مربّع بحث بمجموعة من نتائج البحث.
searchbox-only <div class="gcse-searchbox-only"> مربّع بحث مستقل
searchresults-only <div class="gcse-searchresults-only"> مجموعة مستقلة من نتائج البحث

يمكنك إضافة أي عدد من "عناصر البحث" الصالحة إلى صفحة الويب. في وضع العمودين، يجب توفّر جميع المكوّنات المطلوبة (مربّع بحث وكتلة نتائج البحث).

في ما يلي مثال على "عنصر بحث" بسيط:

<!-- Put the following javascript before the closing </head> tag
and replace 123456 with your own Programmable Search Engine ID. -->
<script async src="https://cse.google.com/cse.js?cx=123456"></script>

<!-- Place this tag where you want both of the search box and the search results to render -->
<div class="gcse-search"></div>

إنشاء خيارات تنسيق مختلفة باستخدام "عناصر البحث المبرمَج"

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

Option المكوّنات
العرض الكامل <div class="gcse-search">
الوضع المكثّف <div class="gcse-search">
عمودان ‫<div class="gcse-searchbox">، <div class="gcse-searchresults">
صفحتان <div class="gcse-searchbox-only"> في الصفحة الأولى، <div class="gcse-searchresults-only"> (أو عناصر أخرى) في الصفحة الثانية
النتائج فقط <div class="gcse-searchresults-only">
مستضاف على Google <div class="gcse-searchbox-only">

مزيد من المعلومات حول خيارات التنسيق

تخصيص عناصر "البحث المبرمَج"

لتخصيص الألوان أو الخط أو نمط الارتباط، انتقِل إلى صفحة "المظهر والطابع" في محرك البحث المبرمَج.

يمكنك استخدام سمات اختيارية لتعديل الإعدادات التي تم إنشاؤها في لوحة تحكّم محرك البحث المبرمَج. يتيح لك ذلك إنشاء تجربة بحث خاصة بالصفحة. على سبيل المثال، تنشئ التعليمة البرمجية التالية مربّع بحث يفتح صفحة نتائج (http://www.example.com?search=lady+gaga) في نافذة جديدة. يتم استخدام قيمة السمة queryParameterName، بالإضافة إلى سلسلة طلب بحث المستخدم، لإنشاء عنوان URL الخاص بالنتائج.

يُرجى العِلم أنّ السمة queryParameterName مسبوقة بالرمز data-. هذه البادئة مطلوبة لجميع السمات.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

إذا كنت قد استخدمت لوحة التحكّم في &quot;محرك البحث المبرمَج&quot; لتفعيل ميزات مثل الإكمال التلقائي أو عمليات البحث المحسّنة، يمكنك استخدام السمات لتخصيص هذه الميزات. أي تخصيصات تحدّدها باستخدام هذه السمات ستلغي الإعدادات التي تم إجراؤها في لوحة التحكّم. ينشئ المثال التالي عنصر بحث يتضمّن عمودَين مع الميزات التالية:

  • تم تفعيل إدارة السجلّ
  • تم ضبط الحد الأقصى لعدد عمليات الإكمال التلقائي المعروضة على 5
  • يتم عرض عمليات التحسين على شكل روابط.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

السمات المتاحة

السمة النوع الوصف المكوّن
الإعدادات العامة
gname سلسلة (اختياري) اسم لكائن "عنصر البحث". يُستخدَم الاسم لاسترداد مكوّن مرتبط به حسب الاسم، أو لربط مكوّن searchbox بمكوّن searchresults. في حال عدم توفيرها، سينشئ &quot;محرك البحث المبرمَج&quot; تلقائيًا gname استنادًا إلى ترتيب المكوّنات في صفحة الويب. على سبيل المثال، يحتوي searchbox-only الأول الذي لم يتم تسميته على gname "searchbox-only0"، ويحتوي الثاني على gname "seachbox-only1"، وهكذا. يُرجى العِلم أنّ قيمة gname التي يتم إنشاؤها تلقائيًا لأحد المكوّنات في تنسيق من عمودَين ستكون two-column. يستخدم المثال التالي الاسم العام storesearch لربط مكوّن searchbox بمكوّن searchresults: 
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

عند استرداد عنصر، إذا كان أكثر من مكوّن واحد يتضمّن gname نفسه، سيستخدم &quot;محرك البحث المبرمَج&quot; المكوّن الأخير في الصفحة.

 أي
autoSearchOnLoad منطقي تحدّد هذه السمة ما إذا كان سيتم تنفيذ بحث باستخدام طلب البحث المضمّن في عنوان URL الخاص بالصفحة التي يتم تحميلها. يُرجى العِلم أنّه يجب توفُّر سلسلة طلب بحث في عنوان URL لتنفيذ البحث التلقائي. القيمة التلقائية: true أي
enableHistory منطقي إذا كانت القيمة true، يتم تفعيل إدارة السجلّ لزرَّي الرجوع والتقديم في المتصفّح. مشاهدة عرض توضيحي

مربّع البحث

searchbox-only
queryParameterName سلسلة اسم مَعلمة طلب البحث، مثل q (القيمة التلقائية) أو query سيتم تضمين هذا المعرّف في عنوان URL (على سبيل المثال، http://www.example.com?q=lady+gaga). يُرجى العِلم أنّ تحديد اسم مَعلمة طلب البحث وحده لا يؤدي إلى تشغيل البحث التلقائي عند التحميل. يجب أن تتضمّن سلسلة طلب البحث عنوان URL لتنفيذ البحث التلقائي. أي
resultsUrl عنوان URL تمثّل هذه السمة عنوان URL لصفحة النتائج. (الإعداد التلقائي هو الصفحة المستضافة على Google). searchbox-only
newWindow منطقي تحدّد هذه السمة ما إذا كانت صفحة النتائج ستُفتح في نافذة جديدة. القيمة التلقائية: false searchbox-only
ivt منطقي

تتيح لك هذه المَعلمة تقديم قيمة منطقية تُعلم Google بأنّك تريد السماح بالإعلانات التي تستخدم ملف تعريف ارتباط مخصّص لرصد الزيارات غير الصالحة فقط ومساحة التخزين المحلية، وذلك في كل الزيارات سواء مُنحت الموافقة أو لم تُمنَح.

true عندما لا تكون هذه المَعلمة متوفّرة أو عندما تضبطها على "true"، سنضبط ملف تعريف ارتباط مخصّص لرصد الزيارات غير الصالحة فقط ونستخدم مساحة التخزين المحلية للزيارات التي تمّت الموافقة عليها فقط.

false عند ضبط هذه المَعلمة على "false"، سنضبط ملف تعريف ارتباط مخصّصًا لرصد الزيارات غير الصالحة فقط، وسنستخدم مساحة التخزين المحلية لجميع زيارات المستخدمين، أيًا كانت حالة موافقتهم على جمع البيانات.

عناوين URL التلقائية: false

مثال على الاستخدام: <div class="gcse-search" data-ivt="true"></div>

searchresults

searchresults-only
mobileLayout سلسلة

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

تستخدم enabled التنسيق المناسب للأجهزة الجوّالة فقط.

disabled لا تستخدم التنسيق المتوافق مع الأجهزة الجوّالة لأي أجهزة.

forced استخدام التنسيق المناسب للأجهزة الجوّالة على جميع الأجهزة

عناوين URL التلقائية: enabled

مثال على الاستخدام: <div class="gcse-search" data-mobileLayout="disabled"></div>

أي
الإكمال التلقائي
enableAutoComplete منطقي لا تتوفّر هذه الميزة إلا إذا تم تفعيل الإكمال التلقائي في لوحة التحكّم في "محرك البحث المبرمَج". تتيح true ميزة الإكمال التلقائي. أي
autoCompleteMaxCompletions عدد صحيح الحد الأقصى لعدد عمليات الإكمال التلقائي التي سيتم عرضها

مربّع البحث

searchbox-only
autoCompleteMaxPromotions عدد صحيح الحدّ الأقصى لعدد العروض الترويجية التي سيتم عرضها في الإكمال التلقائي

مربّع البحث

searchbox-only
autoCompleteValidLanguages سلسلة قائمة مفصولة بفواصل تتضمّن اللغات التي يجب تفعيل ميزة الإكمال التلقائي فيها. اللغات المتاحة

مربّع البحث

searchbox-only
عمليات التحسين
defaultToRefinement سلسلة لا تتوفّر هذه الميزة إلا إذا تم إنشاء عمليات تحسين في لوحة التحكّم في &quot;محرك البحث المبرمَج&quot;. تحدّد هذه السمة تصنيف التنقيح التلقائي الذي سيتم عرضه.ملاحظة: لا تتوافق هذه السمة مع التصميم المستضاف على Google. أي
refinementStyle سلسلة القيم المقبولة هي tab (تلقائية) وlink. لا يتوفّر عامل التشغيل link إلا إذا تم إيقاف ميزة &quot;البحث بالصور&quot; أو إذا تم تفعيلها مع إيقاف ميزة &quot;بحث الويب&quot;.

searchresults

searchresults-only
البحث بالصور
enableImageSearch منطقي لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

إذا كانت القيمة true، يتم تفعيل البحث بالصور. ستظهر نتائج الصور في علامة تبويب منفصلة.

searchresults

searchresults-only
defaultToImageSearch منطقي لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

في حال ضبط القيمة على true، ستعرض صفحة نتائج البحث نتائج بحث الصور تلقائيًا. ستتوفّر نتائج الويب في علامة تبويب منفصلة.

أي
imageSearchLayout سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

تحدّد هذه السمة تخطيط صفحة نتائج البحث عن الصور. القيم المقبولة هي classic أو column أو popup.

searchresults

searchresults-only
imageSearchResultSetSize عدد صحيح، سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

تحدّد هذه السمة الحد الأقصى لحجم مجموعة نتائج البحث في "بحث الصور". على سبيل المثال، large وsmall وfiltered_cse و10.

 أي
image_as_filetype سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

لحصر النتائج على الملفات التي لها امتداد محدّد.

الامتدادات المتوافقة هي jpg وgif وpng وbmp وsvg وwebp وico وraw.

أي
image_as_oq سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

فلترة نتائج البحث باستخدام معامِل OR المنطقي

مثال على الاستخدام إذا كنت تريد نتائج بحث تتضمّن "العبارة 1" أو "العبارة 2":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

أي
image_as_rights سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

فلاتر تستند إلى الترخيص

القيم المسموح بها هي cc_publicdomain وcc_attribute وcc_sharealike وcc_noncommercial وcc_nonderived ومجموعات من هذه القيم.

اطّلِع على التركيبات النموذجية.

أي
image_as_sitesearch سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

لحصر النتائج على صفحات من موقع إلكتروني معيّن

مثال على الاستخدام: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

أي
image_colortype سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

يحصر البحث في الصور بالأبيض والأسود (أحادية اللون) أو الصور ذات تدرّج الرمادي أو الصور الملوّنة. القيم المسموح بها هي mono وgray وcolor.

أي
image_cr سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

لحصر نتائج البحث على المستندات التي مصدرها بلد معيّن.

القيم المسموح بها

أي
image_dominantcolor سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

لحصر البحث على الصور التي تتضمّن لونًا سائدًا معيّنًا. القيم المسموح بها هي red وorange وyellow وgreen وteal وblue وpurple وpink وwhite وgray وblack وbrown.

أي
image_filter سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

الفلترة التلقائية لنتائج البحث

القيم المسموح بها: 0 أو 1

مثال على الاستخدام: <div class="gcse-search" data-image_filter="0"></div>

أي
image_gl سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج". تعزيز نتائج البحث التي يتطابق بلد منشئها مع قيمة المَعلمة

القيم المسموح بها

أي
image_size سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

تعرض هذه السمة صورًا بحجم محدّد، ويمكن أن يكون الحجم أحد القيم التالية: icon أو small أو medium أو large أو xlarge أو xxlarge أو huge.

أي
image_sort_by سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

ترتيب النتائج باستخدام التاريخ أو محتوى منظَّم آخر

للتصنيف حسب الصلة، استخدِم سلسلة فارغة (image_sort_by="").

مثال على الاستخدام: <div class="gcse-search" data-image_sort_by="date"></div>

أي
image_type سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث في الصور في لوحة التحكّم في "محرك البحث المبرمَج".

لحصر البحث على صور من نوع معيّن. القيم المتاحة هي clipart (قصاصات فنية) وface (وجوه أشخاص) وlineart (رسومات خطية) وstock (صور جاهزة للاستخدام) وphoto (صور فوتوغرافية) وanimated (ملفات GIF متحركة).

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

searchresults

searchresults-only
webSearchQueryAddition سلسلة لإضافة المزيد من العبارات إلى طلب البحث باستخدام معامِل OR المنطقي

مثال على الاستخدام: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

 أي
webSearchResultSetSize عدد صحيح، سلسلة الحد الأقصى لحجم مجموعة النتائج ينطبق ذلك على كلّ من البحث بالصور والبحث على الويب. يعتمد الإعداد التلقائي على التنسيق وما إذا كان &quot;محرك البحث المبرمَج&quot; مضبوطًا للبحث في الويب بالكامل أو في مواقع إلكترونية محدّدة فقط. تشمل القيم المقبولة ما يلي:
  • عدد صحيح من 1 إلى 20
  • small: يطلب مجموعة صغيرة من النتائج، عادةً 4 نتائج في كل صفحة.
  • ‫large: يطلب مجموعة كبيرة من النتائج، عادةً 8 نتائج لكل صفحة.
  • ‫filtered_cse: يطلب ما يصل إلى 10 نتائج في كل صفحة، وبحد أقصى 10 صفحات أو 100 نتيجة.
 أي
webSearchSafesearch سلسلة تحدّد هذه السمة ما إذا كانت ميزة SafeSearch مفعّلة لنتائج البحث على الويب. القيم المقبولة هي off وactive. أي
as_filetype سلسلة لحصر النتائج على الملفات التي لها امتداد محدّد. يمكنك الاطّلاع على قائمة بأنواع الملفات التي يمكن لمحرّك بحث Google فهرستها في مركز مساعدة Search Console.

أي
as_oq سلسلة فلترة نتائج البحث باستخدام معامِل OR المنطقي

مثال على الاستخدام إذا كنت تريد نتائج بحث تتضمّن "العبارة 1" أو "العبارة 2":<div class="gcse-search" data-as_oq="term1 term2"></div>

 أي
as_rights سلسلة فلاتر تستند إلى الترخيص

القيم المسموح بها هي cc_publicdomain وcc_attribute وcc_sharealike وcc_noncommercial وcc_nonderived ومجموعات من هذه القيم.

يمكنك الاطّلاع على https://wiki.creativecommons.org/wiki/CC_Search_integration لمعرفة التركيبات النموذجية.

أي
as_sitesearch سلسلة لحصر النتائج على صفحات من موقع إلكتروني معيّن

مثال على الاستخدام: <div class="gcse-search" data-as_sitesearch="example.com"></div>

 أي
cr سلسلة لحصر نتائج البحث على المستندات التي مصدرها بلد معيّن.

القيم المسموح بها

مثال على الاستخدام: <div class="gcse-search" data-cr="countryFR"></div>

 أي
filter سلسلة الفلترة التلقائية لنتائج البحث

القيم المسموح بها: 0/1

مثال على الاستخدام: <div class="gcse-search" data-filter="0"></div>

 أي
gl سلسلة تعزيز نتائج البحث التي يتطابق بلد منشئها مع قيمة المَعلمة

لن يعمل هذا الخيار إلا بالتزامن مع إعداد قيمة اللغة.

القيم المسموح بها

مثال على الاستخدام: <div class="gcse-search" data-gl="fr"></div>

 أي
lr سلسلة لحصر نتائج البحث على المستندات المكتوبة بلغة معيّنة.

القيم المسموح بها

مثال على الاستخدام: <div class="gcse-search" data-lr="lang_fr"></div>

أي
sort_by سلسلة ترتيب النتائج باستخدام التاريخ أو محتوى منظَّم آخر يجب أن تكون قيمة السمة إحدى الخيارات المقدَّمة في إعدادات ترتيب النتائج لمحرك البحث القابل للبرمجة.

للتصنيف حسب الصلة، استخدِم سلسلة فارغة (sort_by="").

مثال على الاستخدام: <div class="gcse-search" data-sort_by="date"></div>

 أي
نتائج البحث
enableOrderBy منطقي يتيح ترتيب النتائج حسب مدى الصلة بالموضوع أو التاريخ أو التصنيف. أي
linkTarget سلسلة تضبط هذه السمة هدف الرابط. القيمة التلقائية: _blank

searchresults

searchresults-only
noResultsString سلسلة لتحديد النص التلقائي الذي سيتم عرضه عند عدم العثور على نتائج مطابِقة لطلب البحث. يمكن استخدام سلسلة النتائج التلقائية لعرض سلسلة مترجَمة إلى جميع اللغات المتوافقة، بينما لا يمكن استخدام السلسلة المخصّصة.

searchresults

searchresults-only
resultSetSize عدد صحيح، سلسلة الحد الأقصى لحجم مجموعة النتائج على سبيل المثال، large وsmall وfiltered_cse و10. يعتمد الإعداد التلقائي على التنسيق وما إذا كان محرك البحث مضبوطًا للبحث على الويب بالكامل أو في مواقع إلكترونية معيّنة فقط. أي
safeSearch سلسلة تحدّد هذه السمة ما إذا كانت ميزة البحث الآمن مفعّلة لكل من بحث الويب وبحث الصور. القيم المقبولة هي off وactive. أي

عمليات معاودة الاتصال

مخطط التسلسل الخاص بمعاودة الاتصال
مخطط تسلسل لعمليات رد الاتصال من JavaScript الخاص بـ &quot;عنصر البحث&quot;

تتيح عمليات الرجوع إمكانية التحكّم المفصّل في عملية تهيئة عنصر البحث وعمليات البحث. يتم تسجيلها باستخدام Search Element JavaScript من خلال الكائن العام __gcse. يوضّح Register Callbacks عملية تسجيل جميع عمليات الرجوع إلى الرمز البرمجي المتوافقة.

تسجيل عمليات إعادة الاستدعاء

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };

دالة معاودة الاتصال الخاصة بعملية الإعداد

يتم استدعاء دالة معاودة الاتصال الخاصة ببدء التشغيل قبل أن يعرض JavaScript الخاص بـ &quot;عنصر البحث&quot; عناصر البحث في نموذج العناصر في المستند. إذا تم ضبط parsetags على explicit في __gcse، سيترك برنامج JavaScript الخاص بعنصر البحث عملية عرض عناصر البحث لدالّة ردّ الاتصال الخاصة بعملية التهيئة (كما هو موضّح في تسجيل دوال ردّ الاتصال). قد يتم استخدام ذلك لاختيار العناصر المطلوب عرضها، أو لتأجيل عرض العناصر إلى حين الحاجة إليها. يمكنه أيضًا تجاهل سمات العناصر، مثلاً، يمكنه تحويل مربّع بحث تم ضبطه من خلال &quot;لوحة التحكّم&quot; أو سمات HTML إلى مربّع بحث تلقائي على الويب، أو تحديد أنّ طلبات البحث التي يتم إرسالها من خلال نموذج &quot;محرك بحث مبرمَج&quot; يتم تنفيذها في عنصر مخصّص لنتائج البحث فقط. مشاهدة عرض توضيحي

يتم التحكّم في دور دالة معاودة الاتصال الخاصة بالإعداد من خلال قيمة السمة parsetags في __gcse.

  • إذا كانت القيمة onload، يعرض JavaScript الخاص بـ &quot;عنصر البحث&quot; جميع عناصر البحث على الصفحة تلقائيًا. سيظل يتم استدعاء دالة معاودة الاتصال الخاصة بعملية التهيئة، ولكنّها لن تكون مسؤولة عن عرض &quot;عناصر البحث&quot;.
  • إذا كانت القيمة explicit، لن يعرض JavaScript الخاص بـ &quot;عنصر البحث&quot; أي &quot;عناصر بحث&quot;. يمكن أن تعرض الدالة رد الاتصال هذه العناصر بشكل انتقائي باستخدام الدالة render()، أو تعرض جميع "عناصر البحث" باستخدام الدالة go().

يوضّح الرمز التالي كيفية عرض مربّع بحث، بالإضافة إلى نتائج البحث، في div باستخدام explicit parsetag ودالة معاودة الاتصال الخاصة ببدء التشغيل:

مثال على معاودة الاتصال عند بدء التشغيل

يجب تضمين <div> مع قيمة معرّف في المكان الذي نريد أن يظهر فيه رمز "عنصر البحث": 

    <div id="test"></div>
 أضِف رمز JavaScript هذا بعد العلامة <div>. يُرجى العِلم أنّها تشير إلى test، أي id الذي استخدمناه لتحديد <div>
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

أدرِج رمز HTML هذا لبدء تحميل "عنصر البحث". استبدِل القيمة cx في العبارة src بقيمة cx خاصة بك. 

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

عمليات إعادة الاستدعاء في البحث

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

  • بدء البحث
    • للبحث بالصور
    • للبحث على الويب
  • النتائج جاهزة
    • للبحث بالصور
    • للبحث على الويب
  • النتائج المعروضة
    • للبحث بالصور
    • للبحث على الويب

كما هو الحال مع دالة معاودة الاتصال الخاصة ببدء التشغيل، يتم ضبط دوال معاودة الاتصال الخاصة بالبحث باستخدام إدخالات في العنصر __gcse. يحدث ذلك عند بدء تشغيل JavaScript الخاص بـ &quot;عنصر البحث&quot;. يتم تجاهل التعديلات التي يتم إجراؤها على __gcse بعد بدء التشغيل.

يتم تمرير كل من عمليات الاسترجاع هذه إلى gName الخاصة بـ "عنصر البحث" كوسيط. يكون gname مفيدًا عندما تحتوي الصفحة على أكثر من عملية بحث واحدة. امنح عنصر بحث قيم gname باستخدام السمة data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

إذا لم يحدّد رمز HTML اسم gname، ستنشئ JavaScript الخاصة بـ &quot;عنصر البحث&quot; قيمة ستظل ثابتة إلى أن يتم تعديل رمز HTML.

Image/Web Search-Starting Callback

يتم استدعاء عمليات الرجوع عند بدء البحث مباشرةً قبل أن يطلب JavaScript الخاص بـ &quot;عنصر البحث&quot; نتائج البحث من الخادم. من الأمثلة على حالات الاستخدام، استخدام الوقت المحلي من اليوم للتحكّم في التغييرات التي تطرأ على طلب البحث. 

searchStartingCallback(gname, query)
gname
السلسلة التعريفية لعنصر البحث
query
القيمة التي أدخلها المستخدم (قد يتم تعديلها بواسطة عنصر JavaScript الخاص بالبحث)

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

بدلاً من ذلك، يمكنك وضع دالة رد الاتصال في العنصر __gcse أو إضافة دالة رد الاتصال ديناميكيًا إلى العنصر باستخدام JavaScript: 

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
مثال على ردّ الاتصال عند بدء البحث

يضيف مثال معاودة الاتصال عند بدء البحث في مثال معاودة الاتصال عند بدء البحث إما morning أو afternoon إلى طلب البحث استنادًا إلى الوقت من اليوم.

مثال على معاودة الاتصال عند بدء البحث 
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

تثبيت وظيفة الاستدعاء هذه في window.__gcse: 

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      image: {
        starting: 'myImageSearchStartingCallbackName',
      },
      web: {
        starting: myWebSearchStartingCallback,
      },
    };
  
  <script
  async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

معاودة الاتصال عند توفّر نتائج البحث بالصور أو الويب

يتم استدعاء عمليات الرجوع هذه مباشرةً قبل أن يعرض JavaScript الخاص بـ &quot;عنصر البحث&quot; العروض الترويجية والنتائج. من الأمثلة على حالات الاستخدام دالة ردّ تعرض العروض الترويجية والنتائج بأسلوب لا يمكن تحديده باستخدام التخصيص العادي. 

resultsReadyCallback(gname, query, promos, results, div)
gname
السلسلة التعريفية لعنصر البحث
query
طلب البحث الذي أدّى إلى ظهور هذه النتائج
promos
مصفوفة من عناصر العروض الترويجية التي تتطابق مع العروض الترويجية لطلب بحث المستخدم. اطّلِع على تعريف عنصر العرض الترويجي.
results
مصفوفة من عناصر النتائج اطّلِع على تعريف عنصر النتيجة.
div
عنصر HTML div موضوع في نموذج المستند (DOM) حيث يضع &quot;عنصر البحث&quot; عادةً الإعلانات الترويجية ونتائج البحث. في العادة، يتولّى رمز JavaScript الخاص بعنصر البحث ملء هذا القسم، ولكن يمكن أن يختار هذا الإجراء الاحتياطي إيقاف العرض التلقائي للنتائج واستخدام div لعرض النتائج بنفسه.

إذا عرضت هذه الدالة قيمة true، ستنتقل JavaScript الخاصة بعنصر البحث إلى عملها في تذييل الصفحة.

مثال على ردّ الاتصال عند توفّر النتائج

يحلّ المثال resultsReady لردّ الاتصال في Example Results Ready Callback محل العرض التقديمي التلقائي للعروض الترويجية والنتائج من خلال استبدال بسيط جدًا.

مثال على دالة معاودة الاتصال الجاهزة للنتائج 
    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

تثبيت وظيفة الاستدعاء هذه في window.__gcse: 

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
 
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

كما هو الحال مع معاودة الاتصال لبدء البحث، فإنّ ما ورد أعلاه هو إحدى الطرق العديدة لوضع معاودة الاتصال في الكائن __gcse.

Image/Web Search Results-Rendered Callback

يتم استدعاء عمليات الرجوع هذه مباشرةً قبل أن يعرض JavaScript الخاص بـ &quot;عنصر البحث&quot; تذييل الصفحة. تشمل أمثلة حالات الاستخدام معاودة الاتصال التي تضيف محتوى نتائج لا تعرضه أداة البحث، مثل مربّع اختيار حفظ هذا أو معلومات لا يتم عرضها تلقائيًا، أو معاودة الاتصال التي تضيف أزرار لمزيد من المعلومات.

إذا كانت دالة معاودة الاتصال لعرض النتائج بحاجة إلى معلومات كانت في المَعلمتَين promos وresults الخاصتَين بدالة معاودة الاتصال الخاصة بتجهيز النتائج، يمكنها نقل هذه المعلومات بينهما، على النحو التالي: 

callback(gname, query, promoElts, resultElts);
gname
السلسلة التعريفية لعنصر البحث
query
سلسلة البحث
promoElts
مصفوفة من عناصر DOM التي تحتوي على عروض ترويجية
resultElts
مصفوفة من عناصر DOM التي تحتوي على النتائج.

لا توجد قيمة معروضة.

مثال على ردّ الاتصال المعروض للنتائج

يضيف مثال رد الاتصال resultsRendered في مثال على رد اتصال معروض للنتائج مربّع اختيار وهميًا حفظ إلى كل عرض ترويجي ونتيجة.

مثال على دالة معاودة الاتصال التي تعرض النتائج 
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

تثبيت وظيفة الاستدعاء هذه في window.__gcse: 

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
 
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

إذا كان برنامج معالجة النتائج المعروضة يحتاج إلى معلومات تم تمريرها إلى برنامج معالجة النتائج الجاهزة، يمكنه تمرير هذه البيانات بين برامج المعالجة. يعرض المثال التالي إحدى الطرق العديدة لتمرير قيمة التقييم من richSnippet من دالة معاودة الاتصال الجاهزة للنتائج إلى دالة معاودة الاتصال المعروضة للنتائج.

مثال على عملية إعادة استدعاء "النتائج جاهزة" تعمل مع عملية إعادة استدعاء "عرض النتائج" 
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
 ثبِّت معاودة الاتصال هذه باستخدام رمز مثل هذا أثناء إعداد __gcse: 
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
 
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
مثال على ردّ الاتصال الذي يتم عرضه في النتائج: فتح أنواع ملفات معيّنة في علامة تبويب أو نافذة جديدة

يمكن لمثال دالة الرجوع التالي تعديل روابط نتائج البحث بعد عرضها لفتح ملف معيّن في علامة تبويب أو صفحة جديدة بدلاً من النافذة الحالية (على سبيل المثال: ملف PDF أو Excel أو Word). يؤدي ذلك إلى تحسين تجربة التصفّح عندما لا يريد المستخدمون فتح ملف في النافذة نفسها والانتقال بعيدًا عن صفحة النتائج.

يحدّد مثال دالة معاودة الاتصال هذا روابط ملفات PDF في نتائج البحث ويضبط السمة target="_blank" على روابط ملفات PDF لكي يتم فتحها في علامة تبويب جديدة. يتم استخدام MutationObserver للتعامل ديناميكيًا مع النتائج الجديدة في حال تعديل الصفحة. ملاحظة: يمكنك استبدال .pdf في handleSearchResults بأي نوع ملف آخر حسب متطلباتك.

لا يعمل مثال معاودة الاتصال هذا على تنسيقات Google Hosted وOverlay.

فتح أنواع ملفات معيّنة في علامة تبويب أو نافذة جديدة 
function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

تثبيت وظيفة الاستدعاء هذه في window.__gcse: 

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: myWebResultsRenderedCallback,
  },
};
 
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

المزيد من الأمثلة على عمليات إعادة الاستدعاء

يمكنك الاطّلاع على أمثلة إضافية على ردود الاتصال في مستند المزيد من الأمثلة على ردود الاتصال.

سمات العرض الترويجي والنتيجة

باستخدام ترميز JSDoc، إليك خصائص الكائنَين promotion وresult. في ما يلي، ندرج جميع السمات التي قد تكون متوفّرة. يعتمد توفّر العديد من السمات على تفاصيل العرض الترويجي أو نتيجة البحث.

خصائص العرض الترويجي
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
سمات عنصر النتيجة
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

يحتوي richSnippet في النتائج على النوع غير المحدد لمصفوفة من الكائنات. يتم التحكّم في قيم الإدخالات في هذه المصفوفة من خلال البيانات المنظَّمة الموجودة على صفحة الويب لكل نتيجة بحث. على سبيل المثال، قد يتضمّن موقع إلكتروني للمراجعات بيانات منظَّمة تضيف إدخال المصفوفة هذا إلى richSnippet: 

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

‫Programmable Search Element Control API (الإصدار 2)

ينشر العنصر google.search.cse.element الدوال الثابتة التالية:

الوظيفة الوصف
.render(componentConfig, opt_componentConfig) تعرض هذه السمة "عنصر بحث".

المعلّمات

الاسم الوصف
componentConfig إعدادات مكوّن Programmable Search Element تحدّد هذه السمة ما يلي:
  • ‫div (string|Element): id <div> أو عنصر div الذي سيتم عرض "عنصر البحث المبرمَج" فيه.
  • ‫tag (سلسلة): نوع المكوّنات التي سيتم عرضها. (عند توفير opt_componentConfig، يجب أن تكون قيمة السمة tag هي searchbox.) القيم المسموح بها هي:
    • search: مربّع بحث ونتائج بحث، يتم عرضها معًا
    • ‫searchbox: مربّع بحث هو أحد مكوّنات "عنصر البحث المبرمَج".
    • ‫searchbox-only: مربّع بحث مستقل سيتم إقرانه بمجموعة من نتائج البحث المحدّدة بواسطة opt_componentConfig في تخطيط من عمودَين.
    • searchresults-only: هي مجموعة مستقلة من نتائج البحث. يتم بدء عمليات البحث من خلال مَعلمة طلب بحث مضمّنة في عنوان URL، أو من خلال التنفيذ البرمجي.
  • ‫gname (string): (اختياري) اسم فريد لهذا المكوّن. في حال عدم توفيرها، سينشئ "محرك البحث المبرمَج" تلقائيًا gname.
  • attributes (كائن): سمات اختيارية في شكل زوج مفتاح:قيمة. السمات المتوافقة:
opt_componentConfig اختياريّ. وسيط إعداد المكوّن الثاني. يُستخدَم في وضع TWO_COLUMN لتوفير المكوّن searchresults. تحدّد هذه السمة ما يلي:
  • ‫div (سلسلة): تمثّل هذه السمة id الخاصة بالعنصر <div> أو العنصر div الذي سيتم عرض العنصر فيه.
  • ‫tag (سلسلة): نوع المكوّنات التي سيتم عرضها. عند توفير opt_componentConfig، يجب أن تكون قيمة السمة tag هي searchresults. بالإضافة إلى ذلك، يجب أن تكون قيمة السمة tag الخاصة بالعنصر componentConfig هي searchbox.
  • ‫gname (string): (اختياري) اسم فريد لهذا المكوّن. في حال عدم توفيرها، سينشئ &quot;محرك البحث المبرمَج&quot; تلقائيًا gname لهذا المكوّن. في حال توفّره، يجب أن يتطابق مع gname في componentConfig.
  • ‫attributes (Object): سمات اختيارية على شكل زوج مفتاح:قيمة. السمات المتوافقة
.go(opt_container) تعرض هذه السمة جميع علامات/فئات "عنصر البحث" في الحاوية المحدّدة.

المعلّمات

الاسم الوصف
opt_container الحاوية التي تحتوي على مكوّنات "عنصر البحث" المطلوب عرضه. حدِّد إما معرّف الحاوية (سلسلة) أو العنصر نفسه. في حال عدم تضمينها، سيتم عرض جميع مكوّنات &quot;عنصر البحث المبرمَج&quot; داخل علامة body الخاصة بالصفحة.
.getElement(gname) يحصل على عنصر الكائن من خلال gname. إذا لم يتم العثور على السمة، يتم عرض قيمة فارغة.

يحتوي عنصر element الذي يتم عرضه على السمات التالية:

  • ‫gname: اسم عنصر العنصر. في حال عدم توفيرها، سينشئ محرّك البحث المبرمَج تلقائيًا gname للعنصر. مزيد من المعلومات
  • ‫type: تمثّل هذه السمة نوع العنصر.
  • ‫uiOptions: السمات النهائية المستخدَمة لعرض العنصر
  • ‫execute - function(string): تنفّذ طلب بحث آليًا.
  • ‫prefillQuery - function(string): تملأ مربّع البحث مسبقًا بسلسلة طلب بحث بدون تنفيذ طلب البحث.
  • ‫getInputQuery - function(): للحصول على القيمة الحالية المعروضة في مربّع الإدخال
  • clearAllResults - function(): يمحو عنصر التحكّم عن طريق إخفاء كل شيء باستثناء مربّع البحث، إن وُجد.

ينفّذ الرمز التالي طلب البحث "news" في "عنصر البحث" "element1":

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() تعرض هذه الطريقة خريطة لجميع عناصر الكائنات التي تم إنشاؤها بنجاح، ويتم تحديد مفاتيحها حسب gname.