אתם יכולים להטמיע רכיבים של Programmable Search Engine (תיבות חיפוש ודפי תוצאות חיפוש) בדפי האינטרנט ובאפליקציות אינטרנט אחרות באמצעות תגי HTML. רכיבי Programmable Search Engine מורכבים מרכיבים שעוברים עיבוד על סמך הגדרות שמאוחסנות בשרת של Programmable Search, וגם על סמך התאמות אישיות שאתם מבצעים.
כל ה-JavaScript נטען באופן אסינכרוני, כך שדף האינטרנט יכול להמשיך להיטען בזמן שהדפדפן מאחזר את ה-JavaScript של Programmable Search Engine.
מבוא
במסמך הזה מוסבר איך להוסיף רכיבים של Programmable Search Engine לדף אינטרנט, ומוצג מודל בסיסי לכך. בנוסף, מוסבר על הרכיבים הניתנים להגדרה של האלמנט ועל JavaScript API הגמיש.
היקף
במסמך הזה מוסבר איך להשתמש בפונקציות ובמאפיינים שספציפיים ל-Programmable Search Engine Control API.
תאימות לדפדפנים
רשימת הדפדפנים שנתמכים ב-Programmable Search Engine מופיעה כאן.
קהל
התיעוד הזה מיועד למפתחים שרוצים להוסיף פונקציונליות של Programmable Search של Google לדפים שלהם.
Programmable Search Elements
אפשר להשתמש בתגי HTML כדי להוסיף רכיב של Programmable Search לדף. כל רכיב מורכב לפחות מרכיב אחד: תיבת חיפוש, בלוק של תוצאות חיפוש או שניהם. תיבת החיפוש מקבלת קלט מהמשתמש באחת מהדרכים הבאות:
- שאילתת חיפוש שהוקלדה בשדה להזנת טקסט
- מחרוזת שאילתה שמוטמעת בכתובת URL
- ביצוע פרוגרמטי
בנוסף, אפשר להזין נתונים לבלוק של תוצאות החיפוש בדרכים הבאות:
- מחרוזת שאילתה שמוטמעת בכתובת URL
- ביצוע פרוגרמטי
אלה סוגי הרכיבים של Programmable Search שזמינים:
| סוג הרכיב | רכיבים | תיאור |
|---|---|---|
| רגיל | <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>
יצירת אפשרויות שונות של פריסה באמצעות רכיבי Programmable Search
אפשרויות הפריסה הבאות זמינות בדף 'מראה ותחושה' בלוח הבקרה של Programmable Search Engine. הנה כמה הנחיות כלליות לגבי יצירת אפשרויות פריסה באמצעות רכיבי Programmable Search. כדי לראות הדגמה של אחת מהאפשרויות האלה, לוחצים על הקישור.
| אפשרות | רכיבים |
|---|---|
| רוחב מלא | <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"> |
התאמה אישית של רכיבי Programmable Search
כדי להתאים אישית את הצבעים, הגופן או סגנון הקישור, עוברים לדף 'מראה ותחושה' של מנוע החיפוש הניתן לתכנות.
אפשר להשתמש במאפיינים אופציונליים כדי לשכתב הגדרות שנוצרו בלוח הבקרה של Programmable Search Engine. כך תוכלו ליצור חוויית חיפוש ספציפית לדף.
לדוגמה, הקוד הבא יוצר תיבת חיפוש שפותחת דף תוצאות (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">
אם השתמשתם בלוח הבקרה של Programmable Search Engine כדי להפעיל תכונות כמו השלמה אוטומטית או הגדרות מדויקות יותר, אתם יכולים להשתמש במאפיינים כדי להתאים אישית את התכונות האלה. כל התאמה אישית שתציינו באמצעות המאפיינים האלה תבטל את ההגדרות שנקבעו בלוח הבקרה. בדוגמה הבאה נוצר רכיב חיפוש עם שתי עמודות והתכונות הבאות:
- הניהול של ההיסטוריה מופעל
- מספר ההשלמות האוטומטיות שיוצגו מוגדר ל-5
- ההצעות לשיפור מוצגות כקישורים.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
מאפיינים נתמכים
| מאפיין | סוג | תיאור | רכיב |
|---|---|---|---|
| כללי | |||
gname |
מחרוזת | (אופציונלי) שם לאובייקט Search Element. השם משמש לאחזור רכיב משויך לפי שם, או לשיוך רכיב searchbox לרכיב searchresults. אם לא מספקים,
Programmable Search Engine ייצור באופן אוטומטי gname, על סמך
סדר הרכיבים בדף האינטרנט. לדוגמה, ל-searchbox-only הראשון ללא שם יש את gname searchbox-only0, לשני יש את gname seachbox-only1 וכן הלאה.
שימו לב: ה-gname שנוצר באופן אוטומטי לרכיב בפריסה של שתי עמודות יהיה two-column. בדוגמה הבאה נעשה שימוש ב-gname storesearch כדי לקשר בין רכיב searchbox לרכיב searchresults:
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> כשמאחזרים אובייקט, אם ליותר מרכיב אחד יש את אותו |
הכול |
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 שאתם רוצים לאפשר הצגת מודעות שמשתמשות באחסון מקומי ובקובצי Cookie לזיהוי תנועה פסולה בלבד, גם למשתמשים שהביעו הסכמה לשימוש בקובצי Cookie וגם למשתמשים שלא הביעו הסכמה.
ברירת מחדל: דוגמאות לשימוש: |
searchresults searchresults-only |
mobileLayout |
מחרוזת |
המדיניות קובעת אם להשתמש בסגנונות הפריסה לניידים במכשירים ניידים.
ברירת מחדל: דוגמאות לשימוש: |
הכול |
| השלמה אוטומטית | |||
enableAutoComplete |
בוליאני | האפשרות הזו זמינה רק אם הפעלתם את ההשלמה האוטומטית בלוח הבקרה של Programmable Search Engine.
true מפעיל את ההשלמה האוטומטית. |
הכול |
autoCompleteMaxCompletions |
מספר שלם | המספר המקסימלי של השלמות אוטומטיות שיוצגו. | תיבת חיפוש searchbox-only |
autoCompleteMaxPromotions |
מספר שלם | המספר המקסימלי של מבצעים שיוצגו בהשלמה האוטומטית. | תיבת חיפוש searchbox-only |
autoCompleteValidLanguages |
מחרוזת | רשימה של שפות מופרדות בפסיקים שבהן צריך להפעיל את ההשלמה האוטומטית. שפות נתמכות. | תיבת חיפוש searchbox-only |
| שיפורים | |||
defaultToRefinement |
מחרוזת | האפשרות הזו זמינה רק אם יצרתם הצעות לשיפור החיפוש בלוח הבקרה של Programmable Search Engine. מציין את התווית של ברירת המחדל לסינון התוצאות שתוצג.הערה: המאפיין הזה לא נתמך בפריסה שמתארחת ב-Google. | הכול |
refinementStyle |
מחרוזת | הערכים הקבילים הם tab (ברירת מחדל) ו-link.
יש תמיכה ב-link רק אם חיפוש התמונות מושבת, או אם חיפוש התמונות מופעל אבל חיפוש האינטרנט מושבת. |
searchresults searchresults-only |
| חיפוש לפי תמונה | |||
enableImageSearch |
בוליאני | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
אם הערך הוא |
searchresults searchresults-only |
defaultToImageSearch |
בוליאני | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
אם |
הכול |
imageSearchLayout |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
מציינת את הפריסה של דף תוצאות החיפוש של תמונות. הערכים הקבילים הם |
searchresults searchresults-only |
imageSearchResultSetSize |
מספר שלם, מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
מציין את הגודל המקסימלי של קבוצת תוצאות החיפוש בחיפוש תמונות.
לדוגמה, |
הכול |
image_as_filetype |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הגבלת התוצאות לקבצים עם סיומת שצוינה. הסיומות הנתמכות הן | הכול |
image_as_oq |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
סינון של תוצאות החיפוש באמצעות האופרטור הלוגי OR. דוגמה לשימוש אם רוצים תוצאות חיפוש שכוללות את המונח term1 או את המונח term2: | הכול |
image_as_rights |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
מסננים לפי רישוי. הערכים הנתמכים הם | הכול |
image_as_sitesearch |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הגבלת התוצאות לדפים מאתר ספציפי. דוגמאות לשימוש: | הכול |
image_colortype |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הגבלת החיפוש לתמונות בשחור-לבן (מונו), בגווני אפור או בצבע. הערכים הנתמכים הם | הכול |
image_cr |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הגבלת תוצאות החיפוש למסמכים שמקורם במדינה מסוימת. | הכול |
image_dominantcolor |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הגבלת החיפוש לתמונות בצבע דומיננטי ספציפי.
הערכים הנתמכים הם | הכול |
image_filter |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
סינון אוטומטי של תוצאות החיפוש. ערכים נתמכים: 0/1 דוגמאות לשימוש: | הכול |
image_gl |
מחרוזת | האפשרות הזו זמינה רק אם חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine. הגברת תוצאות החיפוש שמדינת המקור שלהן תואמת לערך הפרמטר. | הכול |
image_size |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הפונקציה מחזירה תמונות בגודל שצוין, כאשר הגודל יכול להיות אחד מהערכים הבאים: | הכול |
image_sort_by |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
אפשר למיין את התוצאות לפי תאריך או לפי תוכן מובנה אחר. כדי למיין לפי רלוונטיות, משתמשים במחרוזת ריקה (image_sort_by=""). דוגמאות לשימוש: | הכול |
image_type |
מחרוזת | האפשרות הזו זמינה רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine.
הגבלת החיפוש לתמונות מסוג מסוים.
הערכים הנתמכים הם | הכול |
| חיפוש באינטרנט | |||
disableWebSearch |
בוליאני | אם הערך הוא true, החיפוש באינטרנט מושבת. המאפיין הזה משמש בדרך כלל רק אם
חיפוש התמונות הופעל בלוח הבקרה של Programmable Search Engine. |
searchresults searchresults-only |
webSearchQueryAddition |
מחרוזת | הוספת עוד מונחים לשאילתת החיפוש באמצעות האופרטור הלוגי 'או'.
דוגמאות לשימוש: |
הכול |
webSearchResultSetSize |
מספר שלם, מחרוזת | הגודל המקסימלי של קבוצת התוצאות. רלוונטי גם לחיפוש תמונות וגם לחיפוש באינטרנט. ברירת המחדל תלויה בפריסה ובשאלה אם ה-Programmable Search Engine מוגדר לחפש בכל האינטרנט או רק באתרים ספציפיים. ערכים קבילים:
|
הכול |
webSearchSafesearch |
מחרוזת |
קובעת אם SafeSearch מופעל בתוצאות של חיפוש באינטרנט. הערכים הקבילים הם off ו-active.
|
הכול |
as_filetype |
מחרוזת | הגבלת התוצאות לקבצים עם סיומת שצוינה. רשימה של סוגי קבצים ש-Google יכולה להוסיף לאינדקס זמינה במרכז העזרה של Search Console. | הכול |
as_oq |
מחרוזת | סינון של תוצאות החיפוש באמצעות האופרטור הלוגי OR.
דוגמה לשימוש אם רוצים תוצאות חיפוש שכוללות את המונח term1 או את המונח term2: |
הכול |
as_rights |
מחרוזת | מסננים לפי רישוי.
הערכים הנתמכים הם מידע על שילובים אופייניים זמין בכתובת https://wiki.creativecommons.org/wiki/CC_Search_integration. | הכול |
as_sitesearch |
מחרוזת | הגבלת התוצאות לדפים מאתר ספציפי.
דוגמאות לשימוש: |
הכול |
cr |
מחרוזת | הגבלת תוצאות החיפוש למסמכים שמקורם במדינה מסוימת.
דוגמאות לשימוש: |
הכול |
filter |
מחרוזת | סינון אוטומטי של תוצאות החיפוש.
ערכים נתמכים: 0/1 דוגמאות לשימוש: |
הכול |
gl |
מחרוזת | הגברת תוצאות החיפוש שמדינת המקור שלהן תואמת לערך הפרמטר.
האפשרות הזו פועלת רק בשילוב עם ההגדרה ערך השפה. דוגמאות לשימוש: |
הכול |
lr |
מחרוזת | הגבלת תוצאות החיפוש למסמכים שכתובים בשפה מסוימת.
דוגמאות לשימוש: |
הכול |
sort_by |
מחרוזת | אפשר למיין את התוצאות לפי תאריך או לפי תוכן מובנה אחר. ערך המאפיין צריך להיות אחת מהאפשרויות שמופיעות בהגדרות מיון תוצאות של מנוע החיפוש הניתן לתכנות.
כדי למיין לפי רלוונטיות, משתמשים במחרוזת ריקה (sort_by=""). דוגמאות לשימוש: |
הכול |
| תוצאות חיפוש | |||
enableOrderBy |
בוליאני | מאפשר מיון של התוצאות לפי רלוונטיות, תאריך או תווית. | הכול |
linkTarget |
מחרוזת | הגדרת יעד הקישור. ברירת מחדל: _blank. |
searchresults searchresults-only |
noResultsString |
מחרוזת | ציון הטקסט שיוצג כברירת מחדל כשאין תוצאות שתואמות לשאילתה. אפשר להשתמש במחרוזת התוצאה שמוגדרת כברירת מחדל כדי להציג מחרוזת מותאמת לשפה בכל השפות הנתמכות, אבל אי אפשר לעשות את זה עם מחרוזת מותאמת אישית. | searchresults searchresults-only |
resultSetSize |
מספר שלם, מחרוזת | הגודל המקסימלי של קבוצת התוצאות. לדוגמה, large,
small, filtered_cse, 10. ברירת המחדל תלויה בפריסה ובשאלה אם מנוע החיפוש מוגדר לחפש בכל האינטרנט או רק באתרים ספציפיים. |
הכול |
safeSearch |
מחרוזת | מציין אם
החיפוש הבטוח מופעל גם בחיפוש באינטרנט וגם בחיפוש תמונות. הערכים הקבילים הם off
ו-active. |
הכול |
התקשרות חזרה
הפונקציות לביצוע חוזר מאפשרות שליטה מפורטת בתהליכי האתחול והחיפוש של רכיב החיפוש.
הם רשומים ב-JavaScript של רכיב החיפוש דרך האובייקט הגלובלי __gcse. במאמר Register Callbacks מוסבר איך לרשום את כל ה-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,
},
},
};
התקשרות חזרה לאתחול
הקריאה החוזרת (callback) של האתחול מופעלת לפני שסקריפט ה-JavaScript של רכיב החיפוש מעבד רכיבי חיפוש ב-DOM. אם הערך של parsetags מוגדר ל-explicit ב-__gcse, קוד ה-JavaScript של אלמנט החיפוש משאיר את העיבוד של אלמנט החיפוש לפונקציית הקריאה החוזרת של ההפעלה (כפי שמוצג ברישום פונקציות קריאה חוזרות).
יכול להיות שהמאפיין הזה ישמש לבחירת רכיבים לעיבוד, או לדחיית עיבוד רכיבים עד שיהיה צורך בהם. הוא יכול גם לשנות את מאפייני הרכיבים. לדוגמה, הוא יכול לשנות תיבת חיפוש שהוגדרה דרך לוח הבקרה או מאפייני HTML כך שברירת המחדל שלה תהיה חיפוש באינטרנט, ולהפוך אותה לתיבת חיפוש תמונות. הוא יכול גם לציין ששאילתות שנשלחות דרך טופס של מנוע חיפוש שניתן לתכנות יופעלו ברכיב של תוצאות חיפוש בלבד.
לצפייה בהדגמה
התפקיד של קריאת החזרה לאתחול נקבע לפי הערך של המאפיין parsetags של __gcse.
- אם הערך שלו הוא
onload, קוד ה-JavaScript של רכיב החיפוש מעבד את כל רכיבי החיפוש בדף באופן אוטומטי. הקריאה החוזרת לאתחול עדיין מופעלת, אבל היא לא אחראית לעיבוד של רכיבי החיפוש. - אם הערך הוא
explicit, קוד ה-JavaScript של רכיב החיפוש לא מעבד את רכיבי החיפוש. פונקציית ה-callback יכולה להציג אותם באופן סלקטיבי באמצעות הפונקציהrender(), או להציג את כל רכיבי החיפוש באמצעות הפונקציהgo().
בדוגמת הקוד הבאה מוצג איך להציג תיבת חיפוש יחד עם תוצאות חיפוש ב-div באמצעות התג explicit וקריאה חוזרת (callback) לאתחול:
צריך לכלול <div> עם ערך מזהה
במקום שבו רוצים להציב את קוד רכיב החיפוש:
<div id="test"></div><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 של רכיב החיפוש תומך בשש פונקציות קריאה חוזרת (callback) שפועלות בתהליך העבודה של החיפוש. התקשרויות החזרה של החיפוש מגיעות בזוגות, התקשרות חזרה של חיפוש באינטרנט והתקשרות חזרה תואמת של חיפוש תמונות:
- חיפוש התחלתי
- חיפוש תמונות
- לחיפוש באינטרנט
- התוצאות מוכנות
- חיפוש תמונות
- לחיפוש באינטרנט
- תוצאות שנוצרו
- חיפוש תמונות
- לחיפוש באינטרנט
בדומה לפונקציית הקריאה החוזרת (callback) של ההפעלה,פונקציות הקריאה החוזרת של החיפוש מוגדרות באמצעות רשומות באובייקט __gcse. המצב הזה קורה כשה-JavaScript של רכיב החיפוש מתחיל. המערכת מתעלמת משינויים ב-__gcse אחרי ההפעלה.
כל אחת מהקריאות החוזרות האלה מקבלת את gName של רכיב החיפוש כארגומנט.
התכונה gname שימושית כשהדף מכיל יותר מחיפוש אחד. נותנים לרכיב search ערכים של gname באמצעות המאפיין data-gname:
<div class="gcse-searchbox" data-gname="storesearch"></div>
אם לא מצוין gname ב-HTML, קוד ה-JavaScript של רכיב החיפוש יוצר ערך שיישאר עקבי עד שיבוצע שינוי ב-HTML.
קריאה חוזרת (callback) להפעלת חיפוש תמונות או חיפוש באינטרנט
הקריאות החוזרות (callback) להפעלת החיפוש מופעלות מיד לפני שרכיב החיפוש JavaScript מבקש תוצאות חיפוש מהשרת שלו. תרחיש לדוגמה לשימוש: שימוש בשעה המקומית ביום כדי לשלוט בשינויים בשאילתה.
searchStartingCallback(gname, query)
gname- המחרוזת המזהה של רכיב החיפוש
query- הערך שהמשתמש הזין (יכול להיות ששונה על ידי JavaScript של רכיב החיפוש).
פונקציית ההתקשרות חזרה מחזירה את הערך שצריך לשמש כשאילתה לחיפוש הזה. אם הפונקציה מחזירה מחרוזת ריקה, המערכת מתעלמת מהערך המוחזר והקריאה לפונקציה משתמשת בשאילתה ללא שינוי.
אפשר גם להוסיף את פונקציית הקריאה החוזרת לאובייקט __gcse או להוסיף אותה לאובייקט באופן דינמי באמצעות JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};דוגמה לקריאה חוזרת (callback) של התחלת חיפוש
הדוגמה של פונקציית הקריאה החוזרת (callback) שמופעלת בתחילת החיפוש ב-Example Search Starting Callback מוסיפה את המחרוזת morning או afternoon לשאילתה, בהתאם לשעה ביום.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
התקנת פונקציית ה-callback הזו ב-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>קריאה חוזרת (callback) שמוכנה לתוצאות חיפוש תמונות או חיפוש באינטרנט
הקריאות החוזרות האלה מופעלות מיד לפני שקוד ה-JavaScript של רכיב החיפוש מעבד את המבצעים ואת התוצאות. דוגמה לתרחיש שימוש היא קריאה חוזרת (callback) שמעבדת מבצעים ומובילה לסגנון שלא ניתן לציין באמצעות התאמה אישית רגילה.
resultsReadyCallback(gname, query, promos, results, div)
gname- המחרוזת המזהה של רכיב החיפוש
query- השאילתה שהניבה את התוצאות האלה
promos- מערך של אובייקטים של מבצעים, שמתאימים למבצעים שתואמים לשאילתת המשתמש. הגדרת אובייקט קידום המכירות
results
- מערך של אובייקטים של תוצאות. אפשר לעיין בהגדרת אובייקט התוצאה.
div
- HTML div שממוקם ב-DOM במקום שבו רכיב החיפוש בדרך כלל מציב מבצעים ותוצאות חיפוש. בדרך כלל, קוד ה-JavaScript של רכיב החיפוש מטפל באכלוס של ה-div הזה, אבל פונקציית הקריאה החוזרת הזו יכולה להפסיק את העיבוד האוטומטי של התוצאות ולהשתמש ב-
divכדי לעבד את התוצאות בעצמה.
אם פונקציית ההתקשרות חזרה הזו מחזירה ערך של true, קוד ה-JavaScript של רכיב החיפוש מדלג לעבודה שלו בכותרת התחתונה של הדף.
דוגמה לקריאה חוזרת (callback) של התוצאות מוכנות
הקריאה החוזרת 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;
};
התקנת פונקציית ה-callback הזו ב-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.
קריאה חוזרת (callback) של עיבוד תוצאות חיפוש תמונות או חיפוש באינטרנט
הקריאות החוזרות האלה מופעלות מיד לפני שקוד ה-JavaScript של רכיב החיפוש מעבד את הכותרת התחתונה של הדף. דוגמאות למקרים לשימוש כוללות קריאה חוזרת שמוסיפה תוכן לתוצאה שלא מוצג ברכיב החיפוש, כמו תיבת סימון של שמירת התוצאה או מידע שלא מוצג באופן אוטומטי, או קריאה חוזרת שמוסיפה לחצנים של מידע נוסף.
אם קריאה חוזרת (callback) של תוצאות שעברו עיבוד צריכה מידע שהיה בפרמטרים promos ו-results של קריאה חוזרת (callback) של תוצאות מוכנות, היא יכולה להעביר את המידע הזה ביניהן, באופן הבא:
callback(gname, query, promoElts, resultElts);
gname- המחרוזת המזהה של רכיב החיפוש
query- מחרוזת החיפוש.
promoElts- מערך של רכיבי DOM שמכילים מבצעים.
resultElts- מערך של רכיבי DOM שמכילים תוצאות.
אין ערך להחזרה.
דוגמה לקריאה חוזרת (callback) של תוצאות שעברו רינדור
הקריאה החוזרת resultsRendered בדוגמה Example Results Rendered Callback מוסיפה לכל מבצע ולכל תוצאה תיבת סימון פיקטיבית Keep.
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);
}
};
התקנת פונקציית ה-callback הזו ב-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 מתוך הקריאה החוזרת (callback) של התוצאות שמוכנות אל הקריאה החוזרת (callback) של התוצאות שמוצגות.
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>דוגמה לקריאה חוזרת (callback) של עיבוד תוצאות: פתיחת סוגים ספציפיים של קבצים בכרטיסייה או בחלון חדשים
בדוגמה הבאה של קריאה חוזרת אפשר לשנות קישורים לתוצאות חיפוש אחרי שהם מוצגים, כדי לפתוח קובץ ספציפי בכרטיסייה או בדף חדשים במקום בחלון הנוכחי (לדוגמה: 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.');
}
};
התקנת פונקציית ה-callback הזו ב-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>דוגמאות נוספות לקריאה חוזרת (callback)
דוגמאות נוספות לקריאות חוזרות (callback) זמינות במסמך דוגמאות נוספות לקריאות חוזרות.
מאפייני מבצע ותוצאה
אלה המאפיינים של האובייקטים promotion ו-result באמצעות הסימון של JSDoc. בטבלה הבאה מפורטים כל המאפיינים שיכולים להופיע. הנוכחות של רוב המאפיינים תלויה בפרטי המבצע או תוצאת החיפוש.
{
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 ב-results הוא סוג חופשי של מערך אובייקטים. הערכים של הרשומות במערך הזה נקבעים על ידי הנתונים המובְנים שנמצאים בדף האינטרנט של כל תוצאת חיפוש. לדוגמה, אתר עם ביקורות יכול לכלול נתונים מובְנים שמוסיפים את רשומת המערך הזו ל-richSnippet:
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},Programmable Search Element Control API (V2)
אובייקט google.search.cse.element מפרסם את הפונקציות הסטטיות הבאות:
| פונקציה | תיאור | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
רכיב Search מוצג.
פרמטרים
|
||||||
.go(opt_container) |
הפונקציה מעבדת את כל התגים או המחלקות של רכיב החיפוש במאגר שצוין.
פרמטרים
|
||||||
.getElement(gname) |
הפונקציה מחזירה את אובייקט הרכיב לפי gname. אם לא נמצא, מחזירים null.
לאובייקט
הקוד הבא מריץ את השאילתה 'news' ברכיב החיפוש 'element1': var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
הפונקציה מחזירה מפה של כל אובייקטי האלמנטים שנוצרו בהצלחה, עם מפתח gname. |