یک رابط جستجو با ویجت جستجو ایجاد کنید

ویجت جستجو یک رابط جستجوی قابل تنظیم برای برنامه‌های وب ارائه می‌دهد. برای پیاده‌سازی به حداقل HTML و جاوا اسکریپت نیاز دارد و از ویژگی‌های رایجی مانند facets و صفحه‌بندی پشتیبانی می‌کند. همچنین می‌توانید رابط را با CSS و جاوا اسکریپت سفارشی کنید.

اگر به انعطاف‌پذیری بیشتری نیاز دارید، از رابط برنامه‌نویسی کاربردی پرس‌وجو (Query API) استفاده کنید. به بخش ایجاد رابط جستجو با استفاده از رابط برنامه‌نویسی کاربردی پرس‌وجو مراجعه کنید.

ساخت رابط جستجو

ساخت رابط جستجو مستلزم این مراحل است:

  1. یک برنامه جستجو پیکربندی کنید.
  2. یک شناسه کلاینت برای برنامه ایجاد کنید.
  3. نشانه‌گذاری HTML را برای کادر جستجو و نتایج اضافه کنید.
  4. ویجت را در صفحه بارگذاری کنید.
  5. ویجت را مقداردهی اولیه کنید.

پیکربندی یک برنامه جستجو

هر رابط جستجو به یک برنامه جستجو نیاز دارد که در کنسول مدیریت تعریف شده باشد. این برنامه تنظیمات پرس و جو، مانند منابع داده، جنبه‌ها و پارامترهای کیفیت جستجو را ارائه می‌دهد.

برای ایجاد یک برنامه جستجو، به ایجاد یک تجربه جستجوی سفارشی مراجعه کنید.

ایجاد شناسه کلاینت برای برنامه

علاوه بر مراحل موجود در پیکربندی دسترسی به Cloud Search API ، یک شناسه کلاینت برای برنامه وب خود ایجاد کنید.

پیکربندی یک پروژه

هنگام پیکربندی پروژه:

  • نوع کلاینت مرورگر وب را انتخاب کنید.
  • آدرس مبدا (Origin URI) برنامه خود را وارد کنید.
  • به شناسه کلاینت توجه کنید. این ویجت به رمز کلاینت نیاز ندارد.

برای اطلاعات بیشتر، به OAuth 2.0 برای برنامه وب سمت کلاینت مراجعه کنید.

اضافه کردن نشانه‌گذاری HTML

این ویجت به این عناصر HTML نیاز دارد:

  • یک عنصر input برای کادر جستجو.
  • عنصری برای تثبیت کادر محاوره‌ای پیشنهاد.
  • یک عنصر برای نتایج جستجو.
  • (اختیاری) عنصری برای کنترل‌های وجه.

این قطعه کد عناصری را نشان می‌دهد که با استفاده از ویژگی‌های id خود شناسایی شده‌اند:

خدمت/ابزارک/عمومی/با_css/index.html
<div id="search_bar">
  <div id="suggestions_anchor">
    <input type="text" id="search_input" placeholder="Search for...">
  </div>
</div>
<div id="facet_results"></div>
<div id="search_results"></div>

ویجت را بارگذاری کنید

لودر را با استفاده از تگ <script> اضافه کنید:

خدمت/ابزارک/عمومی/با_css/index.html
<!-- Google API loader -->
<script src="https://apis.google.com/js/api.js?mods=enable_cloud_search_widget&onload=onLoad" async defer></script>

یک فراخوانی مجدد onload ارائه دهید. وقتی لودر آماده شد، gapi.load() را برای بارگذاری ماژول‌های کلاینت API، ورود به سیستم گوگل و جستجوی ابری فراخوانی کنید.

سرویس/ویجت/عمومی/با_css/app.js
/**
* Load the cloud search widget & auth libraries. Runs after
* the initial gapi bootstrap library is ready.
*/
function onLoad() {
  gapi.load('client:auth2:cloudsearch-widget', initializeApp)
}

مقداردهی اولیه ویجت

کتابخانه کلاینت را با استفاده از gapi.client.init() یا gapi.auth2.init() با شناسه کلاینت خود و دامنه https://www.googleapis.com/auth/cloud_search.query مقداردهی اولیه کنید. از کلاس‌های سازنده برای پیکربندی و اتصال ویجت استفاده کنید.

مثال مقداردهی اولیه:

سرویس/ویجت/عمومی/با_css/app.js
/**
 * Initialize the app after loading the Google API client &
 * Cloud Search widget.
 */
function initializeApp() {
  // Load client ID & search app.
  loadConfiguration().then(function() {
    // Set API version to v1.
    gapi.config.update('cloudsearch.config/apiVersion', 'v1');

    // Build the result container and bind to DOM elements.
    var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setSearchResultsContainerElement(document.getElementById('search_results'))
      .setFacetResultsContainerElement(document.getElementById('facet_results'))
      .build();

    // Build the search box and bind to DOM elements.
    var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setInput(document.getElementById('search_input'))
      .setAnchor(document.getElementById('suggestions_anchor'))
      .setResultsContainer(resultsContainer)
      .build();
  }).then(function() {
    // Init API/oauth client w/client ID.
    return gapi.auth2.init({
        'clientId': clientId,
        'scope': 'https://www.googleapis.com/auth/cloud_search.query'
    });
  });
}

متغیرهای پیکربندی:

سرویس/ویجت/عمومی/با_css/app.js
/**
* Client ID from OAuth credentials.
*/
var clientId = "...apps.googleusercontent.com";

/**
* Full resource name of the search application, such as
* "searchapplications/<your-id>".
*/
var searchApplicationName = "searchapplications/...";

سفارشی‌سازی تجربه ورود به سیستم

این ویجت هنگام شروع تایپ، از کاربران می‌خواهد که وارد سیستم شوند. برای یک تجربه شخصی‌سازی‌شده، می‌توانید از ورود به سیستم گوگل برای وب‌سایت‌ها استفاده کنید.

مستقیماً به کاربران اجازه دهید

برای نظارت و مدیریت حالت‌های ورود به سیستم ، از ورود با گوگل استفاده کنید. این مثال از GoogleAuth.signIn() هنگام کلیک روی دکمه استفاده می‌کند:

سرویس/ویجت/عمومی/with_signin/app.js
// Handle sign-in/sign-out.
let auth = gapi.auth2.getAuthInstance();

// Watch for sign in status changes to update the UI appropriately.
let onSignInChanged = (isSignedIn) => {
  // Update UI to switch between signed in/out states
  // ...
}
auth.isSignedIn.listen(onSignInChanged);
onSignInChanged(auth.isSignedIn.get()); // Trigger with current status.

// Connect sign-in/sign-out buttons.
document.getElementById("sign-in").onclick = function(e) {
  auth.signIn();
};
document.getElementById("sign-out").onclick = function(e) {
  auth.signOut();
};

ورود خودکار کاربران

برای ساده‌سازی ورود به سیستم، برنامه را برای کاربران سازمان خود از قبل تأیید کنید. این کار با Cloud Identity Aware Proxy نیز مفید است. به بخش «استفاده از ورود به سیستم گوگل با برنامه‌های فناوری اطلاعات» مراجعه کنید.

رابط کاربری را سفارشی کنید

شما می‌توانید ظاهر ویجت را به روش‌های زیر تغییر دهید:

  • نادیده گرفتن استایل‌ها با CSS.
  • تزئین عناصر با آداپتور.
  • ایجاد عناصر سفارشی با آداپتور

استایل‌ها را با CSS نادیده بگیرید

این ویجت شامل CSS مخصوص به خود است. برای لغو آن، از انتخابگرهای والد برای افزایش ویژگی استفاده کنید:

#suggestions_anchor .cloudsearch_suggestion_container {
  font-size: 14px;
}

به مرجع کلاس‌های CSS پشتیبانی‌شده مراجعه کنید.

عناصر را با آداپتور تزئین کنید

یک آداپتور ایجاد و ثبت کنید تا عناصر را قبل از رندر تغییر دهد. این مثال یک کلاس CSS سفارشی اضافه می‌کند:

سرویس/ویجت/عمومی/با_تزئین_عنصر/برنامه.js
/**
 * Search box adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.decorateSuggestionElement = function(element) {
  element.classList.add('my-suggestion');
}

/**
 * Results container adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.decorateSearchResultElement = function(element) {
  element.classList.add('my-result');
}

ثبت آداپتور در هنگام مقداردهی اولیه:

سرویس/ویجت/عمومی/با_تزئین_عنصر/برنامه.js
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

ایجاد عناصر سفارشی با آداپتور

برای ساخت کامپوننت‌های رابط کاربری سفارشی createSuggestionElement ، createFacetResultElement یا createSearchResultElement استفاده کنید. این مثال از تگ‌های <template> در HTML استفاده می‌کند:

سرویس/ویجت/عمومی/با_سفارش_عنصر/برنامه.js
/**
 * Search box adapter that overrides creation of suggestion elements.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.createSuggestionElement = function(suggestion) {
  let template = document.querySelector('#suggestion_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.suggested_query').textContent = suggestion.suggestedQuery;
  return fragment.firstElementChild;
}

/**
 * Results container adapter that overrides creation of result elements.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.createSearchResultElement = function(result) {
  let template = document.querySelector('#result_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.title').textContent = result.title;
  fragment.querySelector('.title').href = result.url;
  let snippetText = result.snippet != null ?
    result.snippet.snippet : '';
  fragment.querySelector('.query_snippet').innerHTML = snippetText;
  return fragment.firstElementChild;
}

آداپتور را ثبت کنید:

سرویس/ویجت/عمومی/با_سفارش_عنصر/برنامه.js
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

عناصر وجهی سفارشی باید از این قوانین پیروی کنند:

  • تابع cloudsearch_facet_bucket_clickable را به عناصر قابل کلیک اضافه کنید.
  • هر سطل را در یک cloudsearch_facet_bucket_container بپیچید.
  • ترتیب سطل‌ها را از پاسخ حفظ کنید.

برای مثال، قطعه کد زیر، وجه‌ها را با استفاده از لینک‌ها به جای چک‌باکس‌ها رندر می‌کند.

خدمت/ابزارک/عمومی/با_سفارش_چهره/برنامه.js
/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}

ResultsContainerAdapter.prototype.createFacetResultElement = function(result) {
  // container for the facet
  var container = document.createElement('div');

  // Add a label describing the facet (operator/property)
  var label = document.createElement('div')
  label.classList.add('facet_label');
  label.textContent = result.operatorName;
  container.appendChild(label);

  // Add each bucket
  for(var i in result.buckets) {
    var bucket = document.createElement('div');
    bucket.classList.add('cloudsearch_facet_bucket_container');

    // Extract & render value from structured value
    // Note: implementation of renderValue() not shown
    var bucketValue = this.renderValue(result.buckets[i].value)
    var link = document.createElement('a');
    link.classList.add('cloudsearch_facet_bucket_clickable');
    link.textContent = bucketValue;
    bucket.appendChild(link);
    container.appendChild(bucket);
  }
  return container;
}

// Renders a value for user display
ResultsContainerAdapter.prototype.renderValue = function(value) {
  // ...
}

سفارشی‌سازی رفتار جستجو

با استفاده از یک آداپتور، تنظیمات برنامه جستجو را با رهگیری درخواست‌ها لغو کنید. interceptSearchRequest را برای تغییر درخواست‌ها قبل از اجرا پیاده‌سازی کنید. این مثال، پرس‌وجوها را به یک منبع انتخاب‌شده محدود می‌کند:

سرویس/ویجت/عمومی/با_درخواست_رهگیر/برنامه.js
/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}
ResultsContainerAdapter.prototype.interceptSearchRequest = function(request) {
  if (!this.selectedSource || this.selectedSource == 'ALL') {
    // Everything selected, fall back to sources defined in the search
    // application.
    request.dataSourceRestrictions = null;
  } else {
    // Restrict to a single selected source.
    request.dataSourceRestrictions = [
      {
        source: {
          predefinedSource: this.selectedSource
        }
      }
    ];
  }
  return request;
}

آداپتور را ثبت کنید:

سرویس/ویجت/عمومی/با_درخواست_رهگیر/برنامه.js
var resultsContainerAdapter = new ResultsContainerAdapter();
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(resultsContainerAdapter)
  // ...
  .build();

کد HTML زیر برای نمایش یک کادر انتخاب جهت فیلتر کردن بر اساس منابع استفاده می‌شود:

سرویس/ویجت/عمومی/با_درخواست_رهگیر/index.html
<div>
  <span>Source</span>
  <select id="sources">
    <option value="ALL">All</option>
    <option value="GOOGLE_GMAIL">Gmail</option>
    <option value="GOOGLE_DRIVE">Drive</option>
    <option value="GOOGLE_SITES">Sites</option>
    <option value="GOOGLE_GROUPS">Groups</option>
    <option value="GOOGLE_CALENDAR">Calendar</option>
    <option value="GOOGLE_KEEP">Keep</option>
  </select>
</div>

کد زیر به تغییرات گوش می‌دهد، انتخاب را تنظیم می‌کند و در صورت لزوم، کوئری را دوباره اجرا می‌کند.

سرویس/ویجت/عمومی/با_درخواست_رهگیر/برنامه.js
// Handle source selection
document.getElementById('sources').onchange = (e) => {
  resultsContainerAdapter.selectedSource = e.target.value;
  let request = resultsContainer.getCurrentRequest();
  if (request.query) {
    // Re-execute if there's a valid query. The source selection
    // will be applied in the interceptor.
    resultsContainer.resetState();
    resultsContainer.executeRequest(request);
  }
}

همچنین می‌توانید با پیاده‌سازی interceptSearchResponse در آداپتور، پاسخ جستجو را رهگیری کنید.

نسخه‌های پین

  • نسخه API : قبل از مقداردهی اولیه، cloudsearch.config/apiVersion را تنظیم کنید.
  • نسخه ویجت : از gapi.config.update('cloudsearch.config/clientVersion', 1.1) استفاده کنید.

اگر تنظیم نشده باشد، هر دو به طور پیش‌فرض روی ۱.۰ تنظیم می‌شوند.

برای مثال، برای پین کردن ویجت به نسخه ۱.۱:

سرویس/ویجت/عمومی/پایه/برنامه.js
gapi.config.update('cloudsearch.config/apiVersion', 'v1');

رابط جستجو را ایمن کنید

از بهترین شیوه‌های امنیتی برای برنامه‌های وب، به ویژه برای جلوگیری از کلیک‌ربایی، پیروی کنید.

اشکال‌زدایی را فعال کنید

برای فعال کردن اشکال‌زدایی interceptSearchRequest استفاده کنید: 

if (!request.requestOptions) {
  request.requestOptions = {};
}
request.requestOptions.debugOptions = {enableDebugging: true};
return request;
،

ویجت جستجو یک رابط جستجوی قابل تنظیم برای برنامه‌های وب ارائه می‌دهد. برای پیاده‌سازی به حداقل HTML و جاوا اسکریپت نیاز دارد و از ویژگی‌های رایجی مانند facets و صفحه‌بندی پشتیبانی می‌کند. همچنین می‌توانید رابط را با CSS و جاوا اسکریپت سفارشی کنید.

اگر به انعطاف‌پذیری بیشتری نیاز دارید، از رابط برنامه‌نویسی کاربردی پرس‌وجو (Query API) استفاده کنید. به بخش ایجاد رابط جستجو با استفاده از رابط برنامه‌نویسی کاربردی پرس‌وجو مراجعه کنید.

ساخت رابط جستجو

ساخت رابط جستجو مستلزم این مراحل است:

  1. یک برنامه جستجو پیکربندی کنید.
  2. یک شناسه کلاینت برای برنامه ایجاد کنید.
  3. نشانه‌گذاری HTML را برای کادر جستجو و نتایج اضافه کنید.
  4. ویجت را در صفحه بارگذاری کنید.
  5. ویجت را مقداردهی اولیه کنید.

پیکربندی یک برنامه جستجو

هر رابط جستجو به یک برنامه جستجو نیاز دارد که در کنسول مدیریت تعریف شده باشد. این برنامه تنظیمات پرس و جو، مانند منابع داده، جنبه‌ها و پارامترهای کیفیت جستجو را ارائه می‌دهد.

برای ایجاد یک برنامه جستجو، به ایجاد یک تجربه جستجوی سفارشی مراجعه کنید.

ایجاد شناسه کلاینت برای برنامه

علاوه بر مراحل موجود در پیکربندی دسترسی به Cloud Search API ، یک شناسه کلاینت برای برنامه وب خود ایجاد کنید.

پیکربندی یک پروژه

هنگام پیکربندی پروژه:

  • نوع کلاینت مرورگر وب را انتخاب کنید.
  • آدرس مبدا (Origin URI) برنامه خود را وارد کنید.
  • به شناسه کلاینت توجه کنید. این ویجت به رمز کلاینت نیاز ندارد.

برای اطلاعات بیشتر، به OAuth 2.0 برای برنامه وب سمت کلاینت مراجعه کنید.

اضافه کردن نشانه‌گذاری HTML

این ویجت به این عناصر HTML نیاز دارد:

  • یک عنصر input برای کادر جستجو.
  • عنصری برای تثبیت کادر محاوره‌ای پیشنهاد.
  • یک عنصر برای نتایج جستجو.
  • (اختیاری) عنصری برای کنترل‌های وجه.

این قطعه کد عناصری را نشان می‌دهد که با استفاده از ویژگی‌های id خود شناسایی شده‌اند:

خدمت/ابزارک/عمومی/با_css/index.html
<div id="search_bar">
  <div id="suggestions_anchor">
    <input type="text" id="search_input" placeholder="Search for...">
  </div>
</div>
<div id="facet_results"></div>
<div id="search_results"></div>

ویجت را بارگذاری کنید

لودر را با استفاده از تگ <script> اضافه کنید:

خدمت/ابزارک/عمومی/با_css/index.html
<!-- Google API loader -->
<script src="https://apis.google.com/js/api.js?mods=enable_cloud_search_widget&onload=onLoad" async defer></script>

یک فراخوانی مجدد onload ارائه دهید. وقتی لودر آماده شد، gapi.load() را برای بارگذاری ماژول‌های کلاینت API، ورود به سیستم گوگل و جستجوی ابری فراخوانی کنید.

سرویس/ویجت/عمومی/با_css/app.js
/**
* Load the cloud search widget & auth libraries. Runs after
* the initial gapi bootstrap library is ready.
*/
function onLoad() {
  gapi.load('client:auth2:cloudsearch-widget', initializeApp)
}

مقداردهی اولیه ویجت

کتابخانه کلاینت را با استفاده از gapi.client.init() یا gapi.auth2.init() با شناسه کلاینت خود و دامنه https://www.googleapis.com/auth/cloud_search.query مقداردهی اولیه کنید. از کلاس‌های سازنده برای پیکربندی و اتصال ویجت استفاده کنید.

مثال مقداردهی اولیه:

سرویس/ویجت/عمومی/با_css/app.js
/**
 * Initialize the app after loading the Google API client &
 * Cloud Search widget.
 */
function initializeApp() {
  // Load client ID & search app.
  loadConfiguration().then(function() {
    // Set API version to v1.
    gapi.config.update('cloudsearch.config/apiVersion', 'v1');

    // Build the result container and bind to DOM elements.
    var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setSearchResultsContainerElement(document.getElementById('search_results'))
      .setFacetResultsContainerElement(document.getElementById('facet_results'))
      .build();

    // Build the search box and bind to DOM elements.
    var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
      .setSearchApplicationId(searchApplicationName)
      .setInput(document.getElementById('search_input'))
      .setAnchor(document.getElementById('suggestions_anchor'))
      .setResultsContainer(resultsContainer)
      .build();
  }).then(function() {
    // Init API/oauth client w/client ID.
    return gapi.auth2.init({
        'clientId': clientId,
        'scope': 'https://www.googleapis.com/auth/cloud_search.query'
    });
  });
}

متغیرهای پیکربندی:

سرویس/ویجت/عمومی/با_css/app.js
/**
* Client ID from OAuth credentials.
*/
var clientId = "...apps.googleusercontent.com";

/**
* Full resource name of the search application, such as
* "searchapplications/<your-id>".
*/
var searchApplicationName = "searchapplications/...";

سفارشی‌سازی تجربه ورود به سیستم

این ویجت هنگام شروع تایپ، از کاربران می‌خواهد که وارد سیستم شوند. برای یک تجربه شخصی‌سازی‌شده، می‌توانید از ورود به سیستم گوگل برای وب‌سایت‌ها استفاده کنید.

مستقیماً به کاربران اجازه دهید

برای نظارت و مدیریت حالت‌های ورود به سیستم ، از ورود با گوگل استفاده کنید. این مثال از GoogleAuth.signIn() هنگام کلیک روی دکمه استفاده می‌کند:

سرویس/ویجت/عمومی/with_signin/app.js
// Handle sign-in/sign-out.
let auth = gapi.auth2.getAuthInstance();

// Watch for sign in status changes to update the UI appropriately.
let onSignInChanged = (isSignedIn) => {
  // Update UI to switch between signed in/out states
  // ...
}
auth.isSignedIn.listen(onSignInChanged);
onSignInChanged(auth.isSignedIn.get()); // Trigger with current status.

// Connect sign-in/sign-out buttons.
document.getElementById("sign-in").onclick = function(e) {
  auth.signIn();
};
document.getElementById("sign-out").onclick = function(e) {
  auth.signOut();
};

ورود خودکار کاربران

برای ساده‌سازی ورود به سیستم، برنامه را برای کاربران سازمان خود از قبل تأیید کنید. این کار با Cloud Identity Aware Proxy نیز مفید است. به بخش «استفاده از ورود به سیستم گوگل با برنامه‌های فناوری اطلاعات» مراجعه کنید.

رابط کاربری را سفارشی کنید

شما می‌توانید ظاهر ویجت را به روش‌های زیر تغییر دهید:

  • نادیده گرفتن استایل‌ها با CSS.
  • تزئین عناصر با آداپتور.
  • ایجاد عناصر سفارشی با آداپتور

استایل‌ها را با CSS نادیده بگیرید

این ویجت شامل CSS مخصوص به خود است. برای لغو آن، از انتخابگرهای والد برای افزایش ویژگی استفاده کنید:

#suggestions_anchor .cloudsearch_suggestion_container {
  font-size: 14px;
}

به مرجع کلاس‌های CSS پشتیبانی‌شده مراجعه کنید.

عناصر را با آداپتور تزئین کنید

یک آداپتور ایجاد و ثبت کنید تا عناصر را قبل از رندر تغییر دهد. این مثال یک کلاس CSS سفارشی اضافه می‌کند:

سرویس/ویجت/عمومی/با_تزئین_عنصر/برنامه.js
/**
 * Search box adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.decorateSuggestionElement = function(element) {
  element.classList.add('my-suggestion');
}

/**
 * Results container adapter that decorates suggestion elements by
 * adding a custom CSS class.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.decorateSearchResultElement = function(element) {
  element.classList.add('my-result');
}

ثبت آداپتور در هنگام مقداردهی اولیه:

سرویس/ویجت/عمومی/با_تزئین_عنصر/برنامه.js
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

ایجاد عناصر سفارشی با آداپتور

برای ساخت کامپوننت‌های رابط کاربری سفارشی createSuggestionElement ، createFacetResultElement یا createSearchResultElement استفاده کنید. این مثال از تگ‌های <template> در HTML استفاده می‌کند:

سرویس/ویجت/عمومی/با_سفارش_عنصر/برنامه.js
/**
 * Search box adapter that overrides creation of suggestion elements.
 */
function SearchBoxAdapter() {}
SearchBoxAdapter.prototype.createSuggestionElement = function(suggestion) {
  let template = document.querySelector('#suggestion_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.suggested_query').textContent = suggestion.suggestedQuery;
  return fragment.firstElementChild;
}

/**
 * Results container adapter that overrides creation of result elements.
 */
function ResultsContainerAdapter() {}
ResultsContainerAdapter.prototype.createSearchResultElement = function(result) {
  let template = document.querySelector('#result_template');
  let fragment = document.importNode(template.content, true);
  fragment.querySelector('.title').textContent = result.title;
  fragment.querySelector('.title').href = result.url;
  let snippetText = result.snippet != null ?
    result.snippet.snippet : '';
  fragment.querySelector('.query_snippet').innerHTML = snippetText;
  return fragment.firstElementChild;
}

آداپتور را ثبت کنید:

سرویس/ویجت/عمومی/با_سفارش_عنصر/برنامه.js
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(new ResultsContainerAdapter())
  // ...
  .build();

// Build the search box and bind to DOM elements.
var searchBox = new gapi.cloudsearch.widget.searchbox.Builder()
  .setAdapter(new SearchBoxAdapter())
  // ...
  .build();

عناصر وجهی سفارشی باید از این قوانین پیروی کنند:

  • تابع cloudsearch_facet_bucket_clickable را به عناصر قابل کلیک اضافه کنید.
  • هر سطل را در یک cloudsearch_facet_bucket_container بپیچید.
  • ترتیب سطل‌ها را از پاسخ حفظ کنید.

برای مثال، قطعه کد زیر، وجه‌ها را با استفاده از لینک‌ها به جای چک‌باکس‌ها رندر می‌کند.

خدمت/ابزارک/عمومی/با_سفارش_چهره/برنامه.js
/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}

ResultsContainerAdapter.prototype.createFacetResultElement = function(result) {
  // container for the facet
  var container = document.createElement('div');

  // Add a label describing the facet (operator/property)
  var label = document.createElement('div')
  label.classList.add('facet_label');
  label.textContent = result.operatorName;
  container.appendChild(label);

  // Add each bucket
  for(var i in result.buckets) {
    var bucket = document.createElement('div');
    bucket.classList.add('cloudsearch_facet_bucket_container');

    // Extract & render value from structured value
    // Note: implementation of renderValue() not shown
    var bucketValue = this.renderValue(result.buckets[i].value)
    var link = document.createElement('a');
    link.classList.add('cloudsearch_facet_bucket_clickable');
    link.textContent = bucketValue;
    bucket.appendChild(link);
    container.appendChild(bucket);
  }
  return container;
}

// Renders a value for user display
ResultsContainerAdapter.prototype.renderValue = function(value) {
  // ...
}

سفارشی‌سازی رفتار جستجو

با استفاده از یک آداپتور، تنظیمات برنامه جستجو را با رهگیری درخواست‌ها لغو کنید. interceptSearchRequest را برای تغییر درخواست‌ها قبل از اجرا پیاده‌سازی کنید. این مثال، پرس‌وجوها را به یک منبع انتخاب‌شده محدود می‌کند:

سرویس/ویجت/عمومی/با_درخواست_رهگیر/برنامه.js
/**
 * Results container adapter that intercepts requests to dynamically
 * change which sources are enabled based on user selection.
 */
function ResultsContainerAdapter() {
  this.selectedSource = null;
}
ResultsContainerAdapter.prototype.interceptSearchRequest = function(request) {
  if (!this.selectedSource || this.selectedSource == 'ALL') {
    // Everything selected, fall back to sources defined in the search
    // application.
    request.dataSourceRestrictions = null;
  } else {
    // Restrict to a single selected source.
    request.dataSourceRestrictions = [
      {
        source: {
          predefinedSource: this.selectedSource
        }
      }
    ];
  }
  return request;
}

آداپتور را ثبت کنید:

سرویس/ویجت/عمومی/با_درخواست_رهگیر/برنامه.js
var resultsContainerAdapter = new ResultsContainerAdapter();
// Build the result container and bind to DOM elements.
var resultsContainer = new gapi.cloudsearch.widget.resultscontainer.Builder()
  .setAdapter(resultsContainerAdapter)
  // ...
  .build();

کد HTML زیر برای نمایش یک کادر انتخاب جهت فیلتر کردن بر اساس منابع استفاده می‌شود:

سرویس/ویجت/عمومی/با_درخواست_رهگیر/index.html
<div>
  <span>Source</span>
  <select id="sources">
    <option value="ALL">All</option>
    <option value="GOOGLE_GMAIL">Gmail</option>
    <option value="GOOGLE_DRIVE">Drive</option>
    <option value="GOOGLE_SITES">Sites</option>
    <option value="GOOGLE_GROUPS">Groups</option>
    <option value="GOOGLE_CALENDAR">Calendar</option>
    <option value="GOOGLE_KEEP">Keep</option>
  </select>
</div>

کد زیر به تغییرات گوش می‌دهد، انتخاب را تنظیم می‌کند و در صورت لزوم، کوئری را دوباره اجرا می‌کند.

سرویس/ویجت/عمومی/با_درخواست_رهگیر/برنامه.js
// Handle source selection
document.getElementById('sources').onchange = (e) => {
  resultsContainerAdapter.selectedSource = e.target.value;
  let request = resultsContainer.getCurrentRequest();
  if (request.query) {
    // Re-execute if there's a valid query. The source selection
    // will be applied in the interceptor.
    resultsContainer.resetState();
    resultsContainer.executeRequest(request);
  }
}

همچنین می‌توانید با پیاده‌سازی interceptSearchResponse در آداپتور، پاسخ جستجو را رهگیری کنید.

نسخه‌های پین

  • نسخه API : قبل از مقداردهی اولیه، cloudsearch.config/apiVersion را تنظیم کنید.
  • نسخه ویجت : از gapi.config.update('cloudsearch.config/clientVersion', 1.1) استفاده کنید.

اگر تنظیم نشده باشد، هر دو به طور پیش‌فرض روی ۱.۰ تنظیم می‌شوند.

برای مثال، برای پین کردن ویجت به نسخه ۱.۱:

سرویس/ویجت/عمومی/پایه/برنامه.js
gapi.config.update('cloudsearch.config/apiVersion', 'v1');

رابط جستجو را ایمن کنید

از بهترین شیوه‌های امنیتی برای برنامه‌های وب، به ویژه برای جلوگیری از کلیک‌ربایی، پیروی کنید.

اشکال‌زدایی را فعال کنید

برای فعال کردن اشکال‌زدایی interceptSearchRequest استفاده کنید: 

if (!request.requestOptions) {
  request.requestOptions = {};
}
request.requestOptions.debugOptions = {enableDebugging: true};
return request;