Kategorie:IES API: Unterschied zwischen den Versionen

Die IES-API steht für zwei Programmiersprachen zur Verfügung. Diese sind für bestimmte Einsatzgebiete gedacht.

Java IES-API

• Entwicklung von Werkzeugen und projektspezifische Funktionen (auch Imports) auf Kommandozeilen-Ebene.
• Interne Verwendung innerhalb des IES auch für Server-Logik von IES-Modulen.

PHP IES-API

• In Web-Seiten eingebundene Applikationen und zur Darstellung von dynamischen Inhalten.

Dokumentation und http://iesapi.sitepark.com

Java IES-API

• Der Rechner auf dem das Java-Programm ausgeführt wird, muss den IES-Server per HTTP auf Port 80 oder auf Port 8080 erreichen können (wenn nötig auch über einen HTTP-Proxy).

PHP IES-API

• Der Web-Server auf dem die PHP-Seiten ausgeführt werden, muss den IES-Server per HTTP auf Port 80 oder auf Port 8080 erreichen können (wenn nötig auch über einen HTTP-Proxy).
• In der Apache-Konfiguration sollte für jeden Virtuellen-Host, der die PHP IES-API verwenden soll, der PHP-Include-Pfad gesetzt werden. Z.B.

<VirtualHost *:80>
    ServerName www.domain.com
    DocumentRoot /srv/www/www.domain.com
    ...

    php_value include_path ".:/srv/www/www.domain.com/WEB-IES/zend/:/srv/www/www.domain.com/WEB-IES/ies-api/php/"
</VirtualHost>

Suche über die IES-API

Für die IES API wird ein neuer Query-Parser entwickelt der die Anforderung an die IES API erfüllen kann. Eine Query muss folgender Syntax entsprechen:

   SELECT {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]] [AS {alias}], ...
   [
      PARENT {parent} |
      REFERRER {parent} {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]] |
      REFERENCE {parent} {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]]
   ]
   WHERE {where_condition}
   [SORT {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]]][ ASC | DESC], ...|RANDOM
   [LIMIT {offset} [,{row_count}]]
   [OPTIONS {name}={value}, ...]

Felddefinition für SELECT, REFERRER, REFERENCE, WHERE und SORT

Felder über Links

Es ist möglich Felder von Objekten zurückzuliefern, auf die das Treffer-Objekt verweist. So wird mit

sp_mylink->sp_mytext

auf das Feld 'sp_mytext' des Objektes zugegriffen auf das das Treffer-Objekt über den Link 'sp_mylink' verweist.

Feldtypen (Nur für IES-2 Abwärtskompatibilität)

Um auf Felder zuzugreifen bei denen ein Type definiert wurde wird der Trenner § verwendet. So wird mit

sp_mylink§link

auf das Feld 'sp_mylink' vom Type link zugegriffen.

Sprache des Feldes

Bei mehrsprachigen Feldern kann die gewünschte Sprache mit dem Trenner # angegeben werden. So wird mit

sp_mytext#de

das Feld mit der Sprache de zurückgegeben.

Wird keine Sprache angegeben, wird die Default-Sprache verwendet

sp_mytext

ist äquivalent zu

sp_text#default

Um Sprachübergreifend zu suchen, kann * angegeben werden

sp_text#*

Achtung: Sprachübergreifende Suchen können nicht im Volltext-Index (LUCENE_SEACH()) angewendet werden. Der Grund dafür ist, das sprachspezifische Stopp-Wörter und Wort-Stämme in dem Volltext-Index relavant sind.

Wildcards für hierarchische Feldnamen

Für hierarchische Feldnamen können Wildcards angegeben werden, um Feldnamen in verschiedenen Ebenen anzusprechen. Hierfür kann ein einfacher Stern (*) für eine Ebenen oder zwei Sterne (**) für beliebige Ebenen verwendet werden.

Beispiele: Ein bestimmtes Feld in einer Ebene

*.sp_mytext

Verwendet alle Felder mit dem Namen sp_mytext, die in der zweiten Ebene liegen wie

mylist[2].sp_mytext
mylist[5].sp_mytext
mysub.sp_mytext

Beispiele: Ein bestimmtes Feld in beliebiger Ebene

**.sp_mytext

Verwendet alle Felder mit dem Namen sp_mytext, die in mindestens der zweiten Ebene liegen

mylist[2].sp_mytext
mylist[5].sp_mytext
mysub.sp_mytext
mysub.mylist[1].mytext
mylist[5].mysub.sp_mytext
mylist[5].mysublist[3].sp_mytext
mylist[5].mysublist[3].mysub.sp_mytext

Beispiele: Beliebiges Feld in einer bestimmten Ebene

sp_mylist.*

Verwendet alle Felder die in der ersten Ebene vom sp_mylist liegen

sp_mylist[2].sp_text
sp_mylist.sp_text2

Beispiele: Beliebiges Feld ab einer bestimmten Ebene

sp_mylist.**

Verwendet alle Felder die unterhalb von sp_mylist liegen

sp_mylist[2].sp_text
sp_mylist.sp_text2
sp_mylist[4].sp_sub.sp_text3

Bei tieferen Strukturen können * und ** kombiniert werden. Hier einige Beispiele

*.a.**
**.a.**
**.a.*.c
*.a.x.**

Aus Performanz-gründen können maximal 4 Felder angegeben. Bei Feldnamen mit mehr als 4 Ebenen kann nur nach den ersten bzw. letzten Ebenen gesucht werden. Folgender Feldname

a.b.c.d.e.f.g

kann nur bis zu den ersten 3 Feldern oder den letzten 3 Felder mit Wildcards angegeben werden

a.b.c.**
a.**.g
**.e.f.g

Alle Kombinationen die sich auf die ersten und letzten Felder beschränken sind möglich.

Wildcards innerhalb von Feldnamen wie sp_* sind nicht möglich!

Kombinationen für die Felddefinition

Die Oben angegebenen Felddefinitionen können beliebig mit einander kombiniert werden. Wichtig ist dabei nur das die Reihenfolge

{field}§{type}#{locale}->{field}...

eingehalten wird. Hier ein paar Beispiele

sp_mylink§systemlink->sp_mytext#de
sp_mylink§link->sp_myLocaleLink#de->sp_mytext
sp_myLocaleLink#de->sp_myimage§url
**.sp_mylink§systemlink->mylist.**.sp_mytext#de

SELECT

Alle nach SELECT angegebenen Felder werden im QueryResult zurückgegeben. Folgende Felder werden immer zurückgegeben:

• id - ID des Treffers
• real - ID des Objektes (nur wenn id ein symbolischer Link ist.
• anchor - Anchor des Treffers oder null, wenn Treffer keinen Anchor hat
• parent - Parent des Treffers

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition

Alias

Der in dem QueryResult enthaltene Feldname kann mit Hilfe von {field} AS {alias} gändert werden. So kann Beispielsweise mit

sp_mytext AS text

das Feld sp_mytext in dem QueryResult unter dem Name text enthalten sein.

Sonderfelder

Folgende Feldnamen sind Schlüsselwörter und übernehmen Sonderfunktionen

worklist

Mit diesem Schlüsselwort kann eine Worklist eines Nutzers oder einer Nutzergruppe abgefragt werden. Z.Z. in nur der gleich-Operator möglich. Als Wert kann eine ID oder ein Anchor angegeben werden

worklist = 100010100000001076-3002

responsible

Mit diesem Schlüsselwort kann der Verantworliche für Objekte des Systems abgefragt werden. Z.Z. in nur der gleich-Operator möglich. Als Wert kann eine ID oder ein Anchor angegeben werden

responsible = 100010100000007846-1015

Geplante Erweiterung:

Merhfachwerte als Liste zurück liefern.

list({field})

Wenn mehrere Felder mit dem Namen field existieren wird eine Liste zurück geliefert.

field: [ "value1", "value2", "value3" ]

Mehrfachwerte mit erweiterten Daten

complex({field})

Wenn mehrere Felder mit dem Namen field existieren wird eine Liste zurück geliefert.

field: [ { path: "mylist[1].mylink->100010100000001143-1015:mylist[3]" value: "value1" },{ path: "mylist[3].mylink->100010100000001143-1015:mylist[4]" value: "value2" } ]

Condition innerhalb eines Iterator-Blocks

{ mynum = 10 & mytext = "hans" }

Nur Objekte finden, in denen die beiden Felder innerhalb eines Iterator-Blocks die angegebenen Werte haben

{ mynum = 10 & { mylink->mylink->{mytext = "hans" | mytext = "peter" } } }

Nur Objekte finden, die innerhalb eines Iteratorblocks mynum = 10 haben und mylink entsprechend gesetzt ist.

PARENT | REFERRER | REFERENCE

Mit diesen Schlüsselwörtern kann eine NodeQuery definiert werden. Eine NodeQuery ist eine Suchabfrage die Objekte anhand einer Verknüpfung zu einen obergeordneten Objekt zurückliefert.

Im IES gibt es 3 verschiedene Arten von Verknüpfungen, die hierarchische Strukturen abbilden können:

• Parent eines Objektes: Jedes Objekt besitzt einen Parent, in dem es eingeordnet ist (Im IES-2 wird diese Parent 'Pool' genannt, Im IES-3 sollte hier nur noch von Parent gesprochen werden)
• Link auf ein übergeordnetes Objekt: Ein Objekt ist mit einem übergeordneten Objekt verknüpft. Über diese Art der Verknüpfung werden z.B. in Infosite Navigations-Strukturen für Webseite definiert.
• Link auf ein Untergeordnetes Objekt Ein Objekt ist min einem untergeordnetem Objekt verknüfpt.

Mit Hilfe der Schlüsselwörter PARENT, REFERRER und REFERENCE kann die Art der Verknüpfung angegeben werden über die nach den Untergeordneten Objekten gesucht werden soll.

Mit {parent} wird der Parent angegeben, dessen Unterelemente zurück geliefert werden sollen. Hier kann der Anchor oder die ID angegeben werden.

PARENT 100080100000002418-1017

oder

PARENT gui.informations

PARENT {parent}

Definition einer NodeQuery, die Objekte zurück liefert, die den angegebenen Parent haben.

Im IES-2 ist es nicht möglich Unter-Elemente und Unter-Pools in einer Suchabfrage zurück zuliefern (das Datenmodell lässt das nicht zu). Deswegen muss in dem WHERE Statement eine Einschränkung wie

WHERE objectclass = 'Parent'

oder

WHERE objectclass != 'Parent'

angegeben werden. Dadurch ist gewährleistet das die Query auch im IES-3 die gleichen Treffer liefern wird. Wird diese Einschränkung nicht angegeben wird ein Fehler zurückgegeben.

REFERRER {parent} {field}[§{linktype}][#{locale}]

Definition einer NodeQuery, die Objekte zurück liefert, die auf das mit {parent} definierten Objekt verlinken. Weiter muss angegeben werden, über welchen Link die Verknüpfung angelegt ist.

REFERRER information.g09.homepage sp_parent§link

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition

REFERENCE {parent} {field}[§{linktype}][#{locale}]

Definition einer NodeQuery, die Objekte zurück liefert, auf die das mit {parent} definierte Objekt verlinkt. Weiter muss angegeben werden, über welchen Link die Verknüpfung angelegt ist.

REFERENCE information.g09.homepage sp_parent§link

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition

WHERE

Definition der Bedingungen, die für die zurück zu liefernden Treffer erfüllt sein müssen. Aufgrund des Datenmodells des IES-2 ist es nicht möglich eine Trefferliste zu erstellen, die unterschiedlichen Objekt-Typen enthält (Artikel, Templates, User, ...). Damit die im IES-2 definierten Suchabfragen auch im IES-3 die gleichen Treffer liefert muss diese Einschränkung auch in der Suchabfrage formuliert werden. Aus diesem Grund ist die erste Bedingung immer

WHERE objectclass = '...' AND (...)

Für eine NodeQuery vom Typ PARENT ist noch die Bedingung

WHERE objectclass != 'Parent' AND (...)

erlaubt.

Die Suchkriterien werden immer in der Form

Feld Operator Wert

angegeben

Diese Suchkriterien können beliebig mit AND und OR verknüpft werden. Für Vorzugsregeln könne runde Klammern verwendet werden

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition

TODO:

Hier folgt die Doku zur Definition der Bedingungen. Diese kann von der SPQL Doku im Wiki übernommen weden, wenn alle dort Dokumentierten funktionen implementiert sind.

SORT

Sortierung eines Suchergebnisses. Hier können kommasepariert Feldnamen (mit Typen) angegeben werden um die Sortierkriterien zu definieren. Die Sortierrichtung kann mit ASC aufsteigend oder DESC absteigend angegeben werden. Wird keine Sortierrichtung angegeben wird aufsteigend sortiert.

SORT sp_date DESC, sp_title

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition

LIMIT

Um nur eine begrenzte Anzahl von Treffer zurück zu liefert, kann LIMIT verwendet werden. LIMIT kann mit ein oder zwei Argumenten verwendet werden. Wird LIMIT mit einem Argument verwendet wird die Anzahl der angegeben Treffer zurückgeliefert.

LIMIT 10

Liefert die ersten 10 Treffer zurück.

Wird LIMT mit zwei Argumenten verwendet, gibt das erste Argument den Offset der Treffer an. Der Offset beginnt mit 0. Das zweite Argument gibt die Anzahl der zurück zu liefernden Treffer an.

LIMIT 0,10

Liefert die ersten 10 Treffer zurück,

LIMIT 9,10

Liefert die Treffer 10 bis 19 zurück.

OPTIONS

Mit der Angabe von Optionen kann das verhalten der Suche noch weiter beeinflusst werden. Optionen werden kommasepariert, Name und Wert durch ein Gleich (=) getrennt.

OPTIONS number=1, boolean=true, text='abc'

Folgende Optionen stehen zur Verfügung:

showHide=true|false

Eine Suche liefert immer nur die Objekte, auf die der angemeldete Nutzer lesende Rechte hat. Zusätzlich zu dem lese-Recht gibt es noch den Zusatz 'hide'. Damit können Objekte einem Nutzer vorenthalten werden, auch wenn dieser die nötigen Rechte besitzt. Mit Angabe dieser Option kann gesteuert werden, ob die 'versteckten' Objekte in dem Ergebnis enthalten sein sollen.

Geplante Optionen:

locale='de'

Wird diese Option angegeben werden bei der Suche nur die Daten einer bestimmten Sprache berücksichtigt.

published='www|preview'

Wird diese Option angegeben werden bei der Suche nur die Daten berücksichtigt, die ein den angegebenen Publikationsbereichen publiziert sind. Es können mehrere Publikationsbereiche angegeben werden (Anchor oder ID). Werden die Publikationsbereiche mit (|) getrennt müssen die Objekte mindestens in einem der angegebenen Publikationsbereiche publiziert sein. Werden die Publikationsbereiche mit (&) getrennt müssen die Objekte in allen angegebenen Bereichen publiziert sein.

Hinweis zum IES-3

Für den IES-3 wird bei Angabe diese Option auch nur in den Daten gesucht, die für die angegebenen Publikationsbereiche publiziert sind.

</source>