Arama widget'ı, web uygulamaları için özelleştirilebilir bir arama arayüzü sağlar. Widget'ı uygulamak için yalnızca az miktarda HTML ve JavaScript gerekir. Bu widget, özellikler ve sayfalara ayırma gibi yaygın arama özelliklerini etkinleştirir. Arayüzün bazı bölümlerini CSS ve JavaScript ile de özelleştirebilirsiniz.
Widget'ın sunduğundan daha fazla esnekliğe ihtiyacınız varsa Query API'yi kullanabilirsiniz. Query API ile arama arayüzü oluşturma hakkında bilgi için Query API ile arama arayüzü oluşturma bölümüne bakın.
Arama arayüzü oluşturma
Arama arayüzünü oluşturmak için birkaç adım gerekir:
- Bir arama uygulamasını yapılandırma
- Uygulama için istemci kimliği oluşturma
- Arama kutusu ve sonuçlar için HTML işaretlemesi ekleme
- Sayfada widget'ı yükle
- Widget'ı başlatma
Bir arama uygulamasını yapılandırma
Yönetici Konsolu'nda her arama arayüzü için tanımlanmış bir arama uygulaması olmalıdır. Arama uygulaması, sorgu için veri kaynakları, özellikler ve arama kalitesi ayarları gibi ek bilgiler sağlar.
Arama uygulaması oluşturmak için Özel arama deneyimi oluşturma bölümüne bakın.
Uygulama için istemci kimliği oluşturma
Google Cloud Search API'ye erişimi yapılandırma bölümündeki adımlara ek olarak, web uygulaması için bir istemci kimliği de oluşturmanız gerekir.
Projeyi yapılandırdığınızda:
- Web tarayıcısı istemci türünü seçin
- Uygulamanızın kaynak URI'sini sağlayın.
- Oluşturulan istemci kimliğini not edin. Sonraki adımları tamamlamak için istemci kimliğine ihtiyacınız olacak. Widget için istemci gizli anahtarı gerekli değildir.
Daha fazla bilgi için İstemci Tarafı Web Uygulaması için OAuth 2.0 sayfasına bakın.
HTML işaretlemesi ekleyin
Widget'ın çalışması için az miktarda HTML gerekir. Aşağıdakileri sağlamanız gerekir:
- Arama kutusu için
input
öğesi. - Öneri pop-up'ının bağlanacağı öğe.
- Arama sonuçlarını içerecek öğe.
- (İsteğe bağlı) Özellik kontrollerini içerecek bir öğe sağlayın.
Aşağıdaki HTML snippet'i, bağlanacak öğelerin id
özelliğiyle tanımlandığı bir arama widget'ına ilişkin HTML'yi gösterir:
Widget'ı yükleyin
Widget, bir yükleyici komut dosyası aracılığıyla dinamik olarak yüklenir. Yükleyiciyi dahil etmek için <script>
etiketini aşağıda gösterildiği gibi kullanın:
Komut dosyası etiketinde onload
geri çağırması sağlamanız gerekir. Bu işlev, yükleyici hazır olduğunda çağrılır. Yükleyici hazır olduğunda API istemcisi, Google ile Oturum Açma ve Cloud Search modüllerini yüklemek için gapi.load()
yöntemini çağırarak widget'ı yüklemeye devam edin.
initializeApp()
işlevi, tüm modüller yüklendikten sonra çağrılır.
Widget'ı başlatma
Öncelikle, oluşturulan istemci kimliği ve https://www.googleapis.com/auth/cloud_search.query
kapsamıyla gapi.client.init()
veya gapi.auth2.init()
yöntemini çağırarak istemci kitaplığını başlatın. Daha sonra, widget'ı yapılandırmak ve HTML öğelerinize bağlamak için gapi.cloudsearch.widget.resultscontainer.Builder
ve gapi.cloudsearch.widget.searchbox.Builder
sınıflarını kullanın.
Aşağıdaki örnekte widget'ın nasıl başlatılacağı gösterilmektedir:
Yukarıdaki örnekte, şu şekilde tanımlanan yapılandırma için iki değişkene başvurulur:
Oturum açma deneyimini özelleştirme
Widget varsayılan olarak, sorgu yazmaya başladıklarında kullanıcılardan oturum açmalarını ve uygulamayı yetkilendirmelerini ister. Kullanıcılara daha özel bir oturum açma deneyimi sunmak için Web Siteleri İçin Google ile Oturum Açma'yı kullanabilirsiniz.
Kullanıcıları doğrudan yetkilendirin
Kullanıcının oturum açma durumunu izlemek ve gerektiğinde kullanıcıların oturum açmak veya oturumlarını kapatmak için Google ile Oturum Açma'yı kullanın. Örneğin, aşağıdaki örnekte, oturum açma değişikliklerini izlemek için isSignedIn
durumu gözlemlenmekte ve oturum açma işlemini bir düğme tıklamasıyla başlatmak için GoogleAuth.signIn()
yöntemi kullanılmaktadır:
Daha fazla bilgi için Google ile oturum açma başlıklı makaleyi inceleyin.
Kullanıcıların otomatik olarak oturum açmasını sağlayın
Uygulamayı kuruluşunuzdaki kullanıcılar adına önceden yetkilendirerek oturum açma deneyimini daha da kolaylaştırabilirsiniz. Bu teknik, uygulamayı korumak için Cloud Identity Aware Proxy kullanıldığında da faydalıdır.
Daha fazla bilgi için Google ile Oturum Açma'yı BT Uygulamalarıyla kullanma başlıklı makaleye göz atın.
Arayüzü özelleştirme
Arama arayüzünün görünümünü bir teknik kombinasyonu kullanarak değiştirebilirsiniz:
- Stilleri CSS ile geçersiz kılma
- Öğeleri adaptörle süsleyin
- Adaptörle özel öğeler oluşturma
Stilleri CSS ile geçersiz kılma
Arama widget'ı, stil önerisi ve sonuç öğelerinin yanı sıra sayfalara ayırma denetimleri için kendi CSS'si ile birlikte gelir. Bu öğeleri gerektiği gibi yeniden biçimlendirebilirsiniz.
Arama widget'ı, yükleme sırasında varsayılan stil sayfasını dinamik bir şekilde yükler. Bu durum, uygulama stil sayfaları yüklendikten sonra gerçekleşir ve kuralların önceliğini artırır. Kendi stillerinizin varsayılan stillere göre öncelikli olmasını sağlamak için varsayılan kuralların belirliliğini artırmak amacıyla üst öğe seçicileri kullanın.
Örneğin, aşağıdaki kuralın dokümandaki statik bir link
veya style
etiketine yüklenmesi durumunda hiçbir etkisi olmaz.
.cloudsearch_suggestion_container {
font-size: 14px;
}
Bunun yerine, sayfada belirtilen üst kapsayıcının kimliği veya sınıfıyla kuralı niteleyin.
#suggestions_anchor .cloudsearch_suggestion_container {
font-size: 14px;
}
Destek sınıflarının listesi ve widget tarafından oluşturulan örnek HTML için Desteklenen CSS sınıfları referansına bakın.
Öğeleri adaptörle süsleyin
Bir öğeyi oluşturma işleminden önce süslemek için decorateSuggestionElement
veya decorateSearchResultElement.
gibi dekorasyon yöntemlerinden birini uygulayan bir adaptör oluşturup yeniden düzenleyin.
Örneğin, aşağıdaki bağdaştırıcılar öneri ve sonuç öğelerine özel bir sınıf ekler.
Widget'ı başlatırken bağdaştırıcıyı kaydetmek için ilgili Builder
sınıfının setAdapter()
yöntemini kullanın:
Dekoratörler, kapsayıcı öğenin özelliklerini ve alt öğeleri değiştirebilir. Dekorasyon sırasında alt öğeler eklenebilir veya kaldırılabilir. Ancak öğelerde yapısal değişiklikler yapıyorsanız süslemek yerine öğeleri doğrudan oluşturmayı düşünün.
Adaptörle özel öğeler oluşturma
Bir öneri, özellik kapsayıcısı veya arama sonucu için özel öğe oluşturmak isterseniz createSuggestionElement
,
createFacetResultElement
veya createSearchResultElement
kodunu tekrar tekrar uygulayan bir bağdaştırıcı oluşturup kaydedin.
Aşağıdaki bağdaştırıcılarda, HTML <template>
etiketleri kullanılarak özel öneri ve arama sonuçları öğelerinin oluşturulması gösterilmektedir.
Widget'ı başlatırken bağdaştırıcıyı kaydetmek için ilgili Builder
sınıfının setAdapter()
yöntemini kullanın:
createFacetResultElement
ile özel özellik öğeleri oluşturmak çeşitli kısıtlamalara tabidir:
cloudsearch_facet_bucket_clickable
CSS sınıfını, kullanıcıların paketi açıp kapatmak için tıkladığı öğeye eklemeniz gerekir.- Her paketi
cloudsearch_facet_bucket_container
CSS sınıfıyla bir kapsayıcı öğe içinde sarmalamanız gerekir. - Paketleri yanıtta göründüklerinden farklı bir sırada oluşturamazsınız.
Örneğin, aşağıdaki snippet, onay kutuları yerine bağlantılar kullanarak façetaları oluşturur.
Arama davranışını özelleştirin
Arama uygulaması ayarları, bir arama arayüzü için varsayılan yapılandırmayı temsil eder ve statiktir. Kullanıcıların veri kaynaklarını değiştirmelerine izin vermek gibi dinamik filtreler veya özellikler uygulamak için arama isteğine bir bağdaştırıcı ile müdahale ederek arama uygulaması ayarlarını geçersiz kılabilirsiniz.
Yürütmeden önce search API'ye yapılan istekleri değiştirmek için interceptSearchRequest
yöntemiyle bir bağdaştırıcı uygulayın.
Örneğin, aşağıdaki bağdaştırıcı, sorguları kullanıcı tarafından seçilen bir kaynakla kısıtlama isteklerine müdahale eder:
Widget'ı başlatırken bağdaştırıcıyı kaydetmek için ResultsContainer
oluştururken setAdapter()
yöntemini kullanın
Aşağıdaki HTML, kaynaklara göre filtrelemeye yönelik bir seçim kutusu görüntülemek için kullanılır:
Aşağıdaki kod değişikliği izler, seçimi ayarlar ve gerekirse sorguyu yeniden yürütür.
Ayrıca bağdaştırıcıda interceptSearchResponse
uygulayarak arama yanıtına müdahale edebilirsiniz.
API sürümünü sabitleyin
Widget varsayılan olarak API'nin en son kararlı sürümünü kullanır. Belirli bir sürümü kilitlemek için widget'ı başlatmadan önce cloudsearch.config/apiVersion
yapılandırma parametresini tercih edilen sürüme ayarlayın.
Ayarlanmadan bırakılırsa veya geçersiz bir değere ayarlanırsa API sürümü varsayılan olarak 1.0 olur.
Widget sürümünü sabitleme
Arama arayüzlerinde beklenmedik değişiklikler önlemek için cloudsearch.config/clientVersion
yapılandırma parametresini gösterildiği gibi ayarlayın:
gapi.config.update('cloudsearch.config/clientVersion', 1.1);
Ayarlanmadan bırakılırsa veya geçersiz bir değere ayarlanırsa widget sürümü varsayılan olarak 1.0 olur.
Arama arayüzünün güvenliğini sağlayın
Arama sonuçları son derece hassas bilgiler içeriyor. Web uygulamalarını güvenli hale getirmek için özellikle tıklama korsanlığı saldırılarına karşı en iyi uygulamaları takip edin.
Daha fazla bilgi için OWASP Rehber Projesi'ne bakın.
Hata ayıklamayı etkinleştir
Arama widget'ında hata ayıklamayı açmak için interceptSearchRequest
bağlantısını kullanın. Örneğin:
if (!request.requestOptions) {
// Make sure requestOptions is populated
request.requestOptions = {};
}
// Enable debugging
request.requestOptions.debugOptions = {enableDebugging: true}
return request;