sumas-xml.md

-Die Suche würde ab jetzt funktionieren, allerdings können ohne Suchmaschinen auch keine Ergebnisse gefunden werden. Ich verdeutliche nachfolgend, wie der Zugang zu einer Suchmaschinen-API definiert werden kann:  
+## Eine Suchmaschine zur `sumas.xml` hinzufügen
+
+Die Datei `~/MetaGer/config/sumas.xml` enthält Informationen, die zeigen, wie Ergebnisse von einer Suchmaschine abgerufen werden sollen.  
+In der Regel gibt es einen Link der Form `https://example.com/search?q=test&encoding=utf8`.  
+Wenn man diesen Link abruft, liefert die Suchmaschine Ergebnisse für das Suchwort `test`.  
   
-In der Datei `~/MetaGer/config/sumas.xml` wird jede Suchmaschine durch ein XML Element `<suma />` dargestellt. Der Aufbau ist demnach wie folgt:  
+Wir nehmen nun an, dass obiges Beispiel tatsächlich eine Suchmaschine wäre und fügen diese zur `sumas.xml`hinzu.  
+  
+Ich spalte den Link in einzelne Teile auf, die zeigen und erklären in welchem Attribut diese in der `sumas.xml` angegeben sind:  
+
+### https://
+
+beginnt der Link mit `https://` bedeutet dies, dass die Ergebnisse über eine sichere Verbindung abgerufen werden. 
+Wir setzen hierfür das Attribut `port` auf 443 und erhalten:  
+`<suma port="443" />`  
+  
+**Hinweis:** Wenn der Link mit `http://`beginnt, braucht dieses Attribut nicht gesetzt zu werden, da der dazugehörige Wert "80" als Standardwert gesetzt wird.
+
+### example.com
+
+Dies ist der Hostname, der definiert unter welcher Adresse der Server gefunden werden kann.  
+Wir setzen hierfür das Attribut `host`auf example.com und erhalten:  
+`<suma port="443" host="example.com" />`  
+
+### /search?
+
+Dies ist der Pfad zum Skript, welches die Suchanfrage behandeln soll. Wir lassen das `?`weg, da es immer vorhanden ist, setzen `skript` auf /search und erhalten: 
+`<suma port="443" host="example.com" skript="/search" />` 
+
+### q=test&encoding=utf8
+
+Dies sind die Argumente, welche an die Suchmaschine übergeben werden sollen. Der Parameter `q` beinahltet hierbei das Suchwort / die Suchworte und der Paramter `encoding` ist offensichtlich immer vorhanden.  
+Für die Suchworte fügen wir den Platzhalter `<<QUERY>>` ein. Er wird von MetaGer automatisch durch die bei MetaGer eingegebenen Suchworte ersetzt. Beachte bitte, dass die statischen Argumente bereits URL-Enkodiert und der gesamte String XML-Enkodiert sein muss, damit Fehler vermieden werden.
+Wir setzen also `formData` auf `q=&lt;&lt;QUERY&gt;&gt;&amp;encoding=utf8` und erhalten:  
+`<suma port="443" host="example.com" skript="/search" formData="q=&lt;&lt;QUERY&gt;&gt;&amp;encoding=utf8" />`
+  
+### Parameter `name`
+
+Dieser Parameter ist nicht optional und muss eine innerhalb der XML-Datei eindeutige Identifizierung enthalten.  
+Wir wählen also den Namen `example` und erhalten:  
+`<suma port="443" host="example.com" skript="/search" formData="q=&lt;&lt;QUERY&gt;&gt;&amp;encoding=utf8" name="example" />`
+
+### Parameter `package`
+
+Jede Suchmaschine benötigt ein zugehöriges PHP-Skript, welches beschreibt, wie die Ergebnisse aus dem Antwortstring der Suchmaschine extrahiert werden.  
+Die Antwort kann z.B.: ein XML, oder ein JSON String sein. Alle Parser können unter `~/MetaGer/app/Models/parserSkripte` gefunden werden.
+`package` beinhaltet den klein geschriebenen Klassennamen des zugehörigen parsers.  
+Wir nennen unsere Klasse `Example` und erhalten:  
+`<suma port="443" host="example.com" skript="/search" formData="q=&lt;&lt;QUERY&gt;&gt;&amp;encoding=utf8" name="example" package="example" />`  
+
+### Parameter `displayName` und Parameter `homepage`
+
+Jede Suchmaschine (sofern diese vom Benutzer ausgewählt werden kann) taucht automatisch mit einem angezeigten Namen und einer Verlinkung auf deren Home unter `localhost:8000/settings` auf.  
+Wir setzen `displayName="Example"` und `homepage="https://example.com"` und erhalten:  
+`<suma port="443" host="example.com" skript="/search" formData="q=&lt;&lt;QUERY&gt;&gt;&amp;encoding=utf8" name="example" package="example" displayName="Example" homepage="https://example.com" />` 
+  
+**Achtung:** Denke daran, dass du nun auch noch die Datei `~/MetaGer/app/Models/parserSkripte/Example.php` erstellen musst, um MetaGer mitzuteilen, wie die Antwort der Suchmaschine ausgewertet werden muss.  
+**Tip:** Nimm ein anderes Suchmaschinenskript als Vorlage. Du musst lediglich den Dateinamen, den Klassennamen und natürlich den Inhalt der Funktion `loadResults()` anpassen. Die Variable `$result`, die der Funktion übergeben wird enthält dabei den ungeparsten Antwortstring der Suchmaschine.
+  
+
+***
+
+  
+Dies sind alle notwendigen Attribute, damit eine API abgefragt werden kann. Eine übersicht über alle Attribute erhaltet ihr am Ende der Seite.  
+**Hinweis:** wenn eure hinzugefügte Suchmaschine bei einer Websuche(Standard) abgefragt werden soll, müsst ihr `type="web"` setzen.  
+  
+Die Datei `sumas.xml` würde nach dem hinzufügen wie folgt aussehen:   
   
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;  
 &lt;sumas&gt;  
-&nbsp;&nbsp;&nbsp;&nbsp;&lt;suma /&gt;  
+&nbsp;&nbsp;&nbsp;&nbsp;&lt;suma port="443" host="example.com" skript="/search" formData="q=&amp;lt;&amp;lt;QUERY&amp;gt;&amp;gt;&amp;amp;encoding=utf8" name="example" package="example" displayName="Example" homepage="https://example.com" /&gt;  
 &lt;/sumas&gt;   
   
 Jedes einzelne `<suma />` Element benötigt dabei folgende Attribute: