Zu Handbuch Javascript-API

Golem.Api.Article.Search – Artikel suchen

Mit der Klasse Golem.Api.Article.Search durchsuchen Sie Artikel nach einem oder mehreren Begriffen im Volltext auf Golem.de.

Inhalt

Einbindung

Javascript-Datei Golem/Api/Article/Search.js
Golem/Api/Article/Search-min.js
Package-Javascript-Datei Golem/Api/Article-full.js
Golem/Api/Article-full-min.js
Erforderliche Klassen Golem.Request
Golem.Api
<!-- Erforderlich -->
<script type="text/javascript" src="http://api.golem.de/download/js/latest/Golem/Core-min.js"></script>

<!-- Klasse -->
<script type="text/javascript" src="http://api.golem.de/download/js/latest/Golem/Api/Article/Search.js"></script>

Verwendung

Die Parameter einer Suchabfrage

Für eine Suche können Sie neben den eigentlichen Suchbegriffen weitere Parameter angeben, welche die Menge der Suchergebnisse regulieren.

Die Suchergebnisse werden auf "Seiten" (Pages) aufgeteilt, mit einer Suchanfrage erhalten Sie nur eine einzelne Seite, mit weiteren Suchabfragen blättern Sie durch die Suchergebnisse. Pro Seite können Sie sich zwischen 1 und 50 Ergebnisse liefern lassen.

Rufen Sie die Suche zum ersten Mal auf, reicht es aus, die Suchbegriffe und die Anzahl der Ergebnisse (Items) pro Seite zu setzen. Werden bei einer Suche mehr Artikel gefunden als pro Seite übergeben werden, und wollen Sie weitere Ergebnisse erhalten, starten Sie weitere Anfragen. Bei den nachfolgenden Abfragen müssen sie zusätzlich die jeweilige gewünschte Seite (Start-Index) angeben.

Beispiel: Für eine Suche wurde die Anzahl der Items auf 20 gesetzt. Es wurden aber 47 Artikel gefunden. Die 1. Seite enthält die ersten 20 Suchergebnisse. Wenn Sie nun die nächsten 20 Artikel haben möchten, führen Sie eine weitere Abfrage durch, bei der sie den Start-Index auf 2 setzen. Für die restlichen 7 Artikel setzen Sie in einer dritten Abfrage den Start-Index auf 3.

  Übergebene Parameter: Zurückgelieferte Suchergebnisse
Start-Index Items pro Seite
1. Aufruf 1 20 1. - 20. Artikel
2. Aufruf 2 20 21. - 40. Artikel
3. Aufruf 3 20 41. - 47. Artikel

Einfache Suche ausführen

Nehmen wir an, Sie bauen für die Suche ein einfaches Formular zur Eingabe der Suchbegriffe, darunter befindet sich eine HTML-Liste, welche die Suchresultate darstellen wird:

  <form onsubmit="return search(1);">
   Suchen nach: <input type="text" id="query">
   <input type="submit" value="Suchen!">
  </form>
  <ul id="results">
  </ul>
Beispiel 1: HTML-Formular für die Suche
Die eigentliche Suche wird beim onsubmit-Event ausgeführt.

Am Beginn der Seite initialisieren Sie ein Golem.Api.Article.Search-Objekt. Die Anzahl der Einträge pro Ergebnis-Seite setzen Sie konstant auf 10 fest.

<script type="text/javascript">

 var oSearch = new Golem.Api.Article.Search();

 oSearch.setItemsPerPage(10);

</script>
Beispiel 2: Initialisierung der Abfrage

Die eigentliche Suche findet in der Methode search statt. Zuerst werden in der Methode die Suchbegriffe aus dem Eingabelement geholt, dem Suchobjekt übergeben. Die darzustellende Suchseite wird als Parameter der search-Methode übergeben. Wenn die Methode durch den Klick auf den Submit-Button aufgerufen wird, fordern Sie die erste Seite an.

function search(iPage) {

 var strQuery = document.getElementById('query').value;

 oSearch.setQuery(strQuery);
 oSearch.setStartIndex(iPage);

 ...

}
Beispiel 3: Abfrageparameter setzen

Die eigentlich Abfrage führen Sie mit oSearch.fetch durch:

function search(iPage) {

 var strQuery = document.getElementById('query').value;

 oSearch.setQuery(strQuery);
 oSearch.setStartIndex(iPage);

 oSearch.fetch(
  {
   fnSuccess : fillList
  }
 );

}
Beispiel 4: Abfrage durchführen

fetch() wird ein Objekt-Literal übergeben mit der Methode fillList(), die bei erfolgreicher Ausführung der Anfrage aufgerufen wird.

In fillList() leeren Sie zuerst die HTML-Liste und rufen danach each() auf. Die Füll-Funktion läuft dabei innerhalb des Scopes des oSearch-Objektes, weshalb Sie diese mit this referenzieren können. Die bei each() übergebene Methode wird für jedes erhaltene Suchergebnis aufgerufen.

function fillList() {

 var elList = document.getElementById('results');

 elList.innerHTML = '';

 oSearch.each(
  function(record) {

   var elItem = document.createElement('LI');

   elItem.innerHTML = '<a href="'+record.url+'">'+
                        record.headline+'</a>'+
                        '<br>'+
                        record.abstracttext;

   elList.appendChild(elResult);

  }

 );

}
Beispiel 5: Suchresultate darstellen

Seitennavigation

Wenn die Suche mehr Ergebnisse zurückliefert als auf eine Seite passen, müssen Sie noch Vor-/Zurück-Links zum Blättern durch die Ergebnisse anbieten.

Dazu erweitern Sie den HTML-Code um zwei A-Tags, die per CSS standardmäßig nicht sichtbar sind.

  <span style="float:left;">
   <a id="backlink" href="javascript:void(0);" onclick="return window.search(oSearch.getStartIndex() - 1);" style="visibility:hidden;">
    Vorherige Seite
   </a>
  </span>
  <span style="float:right;">
   <a id="nextlink" href="javascript:void(0);" onclick="return window.search(oSearch.getStartIndex() + 1);" style="visibility:hidden;">
    Nächste Seite
   </a>
  </span>
Beispiel 6: HTML-Code der Navigationselemente

Ähnlich wie beim onsubmit-Event im Formular rufen Sie auch hier beim Anklicken des Links die globale search()-Funktion auf. Als Parameter übergeben Sie den Vorgänger bzw. den Nachfolger der aktuellen Suchergebnis-Seite.

Die Funktion fillList() ergänzen Sie nun um die entsprechende Funktion zum Ein- und Ausblenden der Links.

function fillList() {

 var elResult = document.getElementById('results');

 elResult.innerHTML = '';

 oSearch.each(
 ...
 );

 var elBack = document.getElementById('backlink');
 var elNext = document.getElementById('nextlink');

 if(0 < (this.getStartIndex() - 1)) {

  elBack.style.visibility = 'visible';

 } else {

  elBack.style.visibility = 'hidden';

 }

 if(this.getTotalResults() > (this.getStartIndex() * this.getItemsPerPage())) {

  elNext.style.visibility = 'visible';

 } else {

  elNext.style.visibility = 'hidden';

 }

}
Beispiel 7: Funktion zum Ein- bzw. Ausblenden der Navigationselements

In der ersten Bedingung wird geprüft, ob die aktuelle Seite größer 0 ist, in dem Fall gibt es eine vorherige Seite. In der Zweiten prüfen Sie, ob die Anzahl der gesamten Suchergebnisse (getTotalResult()) größer ist als das Produkt aus der aktuellen Seitenzahl (getStartIndex()) und der Anzahl der Ergebnisse pro Seite (getItemsPerPage). Die Methoden getTotalResult(), getStartIndex() und getItemsPerPage gehören zum oSearch-Objekt.

Fehlerbehandlung

Während der Datenabfrage können Fehler auftreten:

  • Golem.Api.Article.Search.ERROR_QUERY_TOO_LONG bedeutet, dass die Query zu lang war.
  • Golem.Api.Article.Search.ERROR_TOO_MUCH_WORDS bedeutet, dass die Query zu viele Suchbegriffe enthält.
  • Golem.Api.Article.Search.ERROR_WORD_TOO_LONG bedeutet, dass die Query einen Suchbegriff enthält, der länger ist als erlaubt.
  • Golem.Api.Article.Search.ERROR_WORD_TOO_SHORT bedeutet, dass die Query einen Suchbegriff enthält, der zu kurz ist, um als Suchbegriff verwendet zu werden.

Um eine fehlerhafte Abfrage abzufangen, geben Sie bei der Methode fetch() eine Funktion für die Fehlerbehandlung an:

...
oSearch.fetch(
    {
        fnSuccess : fillList,
        fnError   : handleError
    }
);
...
Beispiel 8: Abfrage ergänzt um Fehlerbehandlung

Der Fehler-Funktion wird als erster Parameter der Fehlercode übergeben, als zweiter eine Fehlermeldung. Auch diese Funktion läuft innerhalb des Scopes des oSearch-Objektes.


function handleError(errorCode, errorMessage) {

    var msg = '';

    switch(errorCode) {

        case Golem.Api.Article.Search.ERROR_QUERY_TOO_LONG :
            msg = 'Die Eingabe ist zu lang!';
            break;

        case Golem.Api.Article.Search.ERROR_TOO_MUCH_WORDS :
            msg = 'Die Eingabe enthält zu viele Suchbegriffe!';
            break;

        case Golem.Api.Article.Search.ERROR_WORD_TOO_LONG :
            msg = 'Ein Suchbegriff ist zu lang!';
            break;

        case Golem.Api.Article.Search.ERROR_WORD_TOO_SHORT :
            msg = 'Ein Suchbegriff ist zu kurz!';
            break;

        default :
            msg = 'Unbekannter Fehler!';
    }

    alert(msg);

}
Beispiel 9: Funktion zur Fehlerbehandlung

Verfügbare Artikeldaten

Für jeden Artikel werden folgende Eigenschaften mitgeliefert:

Name Bedeutung
articleid Artikel-Identifier
abstracttext Der Abstract des Artikels, eine Kurzzusammenfassung des Inhaltes
headline Die Überschrift des Artikels
date Das Veröffentlichungsdatum als UNIX-Timestamp in Millisekunden
url Die URL des Artikels

Vollständiges Beispiel

<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <script type="text/javascript" src="http://api.golem.de/download/js/latest/Golem/Core-min.js"></script>
  <script type="text/javascript" src="http://api.golem.de/download/js/latest/Golem/Api/Article/Search.js"></script>
  
  <script type="text/javascript">

   Golem.Request.KEY = '2_1_1';

   var oSearch = new Golem.Api.Article.Search();

   oSearch.setItemsPerPage(10);

   function search(startIndex) {

    var strQuery = document.getElementById('query').value;

    oSearch.setQuery(strQuery);
    oSearch.setStartIndex(startIndex);

    oSearch.fetch(
     {
      fnSuccess : fillList,
      fnError   : handleError
     }
    );

    return false;
   }


   function fillList() {

    var elList = document.getElementById('results');

    elList.innerHTML = '';

    oSearch.each(
     function(record) {

      var elItem = document.createElement('LI');

      elItem.innerHTML = '<a href="'+record.url+'">'+
                        record.headline+'</a>'+
                        '<br>'+
                        record.abstracttext;

      elList.appendChild(elItem);

     }

    );
    
    var elBack = document.getElementById('backlink');
    var elNext = document.getElementById('nextlink');

    if(0 < (this.getStartIndex() - 1)) {

     elBack.style.visibility = 'visible';

    } else {

     elBack.style.visibility = 'hidden';

    }

    if(this.getTotalResults() > (this.getStartIndex() * this.getItemsPerPage())) {

     elNext.style.visibility = 'visible';

    } else {

     elNext.style.visibility = 'hidden';

    }

   }
   
   function handleError(errorCode, errorMessage) {

    var msg = '';

    switch(errorCode) {

        case Golem.Api.Article.Search.ERROR_QUERY_TOO_LONG :
            msg = 'Die Eingabe ist zu lang!';
            break;

        case Golem.Api.Article.Search.ERROR_TOO_MUCH_WORDS :
            msg = 'Die Eingabe enthält zu viele Suchbegriffe!';
            break;

        case Golem.Api.Article.Search.ERROR_WORD_TOO_LONG :
            msg = 'Ein Suchbegriff ist zu lang!';
            break;

        case Golem.Api.Article.Search.ERROR_WORD_TOO_SHORT :
            msg = 'Ein Suchbegriff ist zu kurz!';
            break;

        default :
            msg = 'Unbekannter Fehler!';
    }

    alert(msg);

   }

  </script>

 </head>
 <body>
   <form onsubmit="return search(1);">
   Suchen nach: <input type="text" id="query" />
   <input type="submit" value="Suchen!">
  </form>

  <ul id="results">
  </ul>

  <span style="float:left;">
   <a id="backlink" href="javascript:void(0);" onclick="return window.search(oSearch.getStartIndex() - 1);" style="visibility:hidden;">
    Vorherige Seite
   </a>
  </span>
  <span style="float:right;">
   <a id="nextlink" href="javascript:void(0);" onclick="return window.search(oSearch.getStartIndex() + 1);" style="visibility:hidden;">
    Nächste Seite
   </a>
  </span>

 </body>
</html>


Zu Handbuch Javascript-API