Methoden-Referenz
Die ausgelieferte Bibliothek stellt verschiedene Methoden bereit, um mit der Icony JS-API zu kommunizieren.
Sobald der Icony JS-API JavaScript-Code auf Ihrer Seite eingebaut ist, wird ein globales Objekt mit dem Namen
icony
erzeugt. Dieses Objekt wird nun dazu verwendet Daten von der Icony JS-API anzufordern.
create
Erzeugt eine Verbindung zur Icony JS-API.
icony('create', platformId);
Parameter
-
String
platformId
- Die ID Ihrer Icony-Plattform.
Beispiel
Stellt eine Verbindung für die Partner-Plattform flirt.de her.
icony('create', 'flirt');
get
Stellt eine Anfrage, um ein bestimmtes Modul vom Server zu laden.
icony('get', moduleType, responseFormat, callback, opt_fieldObject);
Parameter
-
String
moduleType
- Die Art des Moduls das ausgeliefert werden soll. Die möglichen Werte sind -
String
responseFormat
- Das gewünschte Format des Moduls in der Antwort. -
function
callback
- Callback-Funktion die nach Erhalt einer Antwort ausgeführt wird. -
Object
opt_fieldObject
- JavaScript-Objekt mit Feld-Wert-Paaren. Enthält mindestens die Pflichtfelder und optional weitere Felder um Standard-Werte zu überschreiben.
Rückgabewert
-
String
requestId
- ID der Anfrage zur späteren Referenzierung, z.B. bei set.
Beispiele
Lädt das Benutzer-Tipps-Modul im JSON-Format und registriert parseTips
als Callback-Funktion.
icony('get', 'tips', 'json', parseTips, {count: 10});
Anfrage für das Aktivitäten-Modul im DOM-Format mit parseActivities
als Callback-Funktion und
speichert eine Referenz auf das Modul in activitiesId
.
var activitiesId = icony('get', 'activities', 'dom', parseActivities, {count: 50});
script
Lädt asynchron ein Script vom Icony JS-API Server zur Ausführung von Widgets.
icony('script', moduleType, jsLibrary);
Parameter
-
String
moduleType
- DermoduleType
für den ein Script geladen werden soll. -
String
jsLibrary
- Name der Ziel-Bibliothek (und evtl. Version).
Die angebotenen Scripte setzen eine bestimmte JavaScript-Bibliothek (und evtl. Version) voraus; die entsprechenden Bibilotheken werden daher zwingend zur Ausführung benötigt. Nicht für alle Module sind überhaupt Widgets verfügbar und nicht alle Scripte wurden für jede Bibliothek portiert.
Die derzeit verfügbaren Modul/Bibliothek-Kombinationen sind:
Beispiel
Lädt das Script für das activities
-Widget asynchron vom Server und bindet es in die Seite ein.
icony('script', 'activities', 'native');
set
Setzt den Wert einer Variablen für eine bestimmte get-Anfrage oder allgemein für ein Modul. Explizit für eine Anfrage gesetzte Werte überschreiben dabei die allgemeineren Modul-Werte.
icony('set', referenceId, variableName, variableValue);
Parameter
-
String
referenceId
- Entweder dierequestId
eines gets oder einmoduleType
(activities tips search) -
String
variableName
- Name der zu setzenden Variablen -
mixed
variableValue
- Wert der Variablen
Beispiele
Ändert einen Varialenwert für alle Widgets
icony('set', 'activities', 'pause', 3000);
Das Widgetes mit der ID requestId
soll 7 Elemente anzeigen.
icony('set', requestId, 'show', 7);
Feld-Referenz
Felder werden bei get
-Anfragen in einem Optionen-Objekt an die Icony JS-API geschickt. Je nach
Modultyp und Antwortformat können oder müssen verschiedene Felder gesetzt werden. In diesem Abschnitt werden
alle verfügbaren Felder aufgelistet und erleutert.
Affiliate
String affiliate
Optional.
Gültig für:
activities/dom
, activities/json
, search/dom
, tips/dom
,
tips/json
Setzt einen Affiliate zur Benutzerverfolgung. Der Affiliate wird an alle Links auf Ihre Partner-Plattform angehängt; Interaktionen die ein Benutzer dort ausführt, können dann einem bestimmten Modul zugeordnet werden. Damit ist z.B. eine Erfolgsbewertung möglich.
Der Affiliate ist zwar frei wählbar, muss aber zuvor im Backend-Bereich von Ihnen angelegt werden.
Feldame | Werttyp | Standardwert |
---|---|---|
affiliate |
String | [leer] |
Beispiel-Werte
-
myIconySearch
- Interaktionen werden dem Affiliate myIconySearch zugeordnet -
[leer]
- kein Affiliate
Beispiel-Verwendung
icony('get', 'search', 'dom', aCallback, {affiliate: 'myIconySearch'});
Maximales Alter
Integer age_max
Optional.
Gültig für:
activities/dom
, activities/json
, tips/dom
, tips/json
Legt die obere Altersgrenze bei der Auswahl von Benutzern fest.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
age_max |
Integer | 55 | 18-99 (größer als age_min ) |
Beispiel-Werte
-
35
- nur Benutzer die jünger als 35 Jahre alt sind
Beispiel-Verwendung
icony('get', 'activities', 'json', aCallback, {age_max: 35});
Minimales Alter
Integer age_min
Optional.
Gültig für:
activities/dom
, activities/json
, tips/dom
, tips/json
Legt die untere Altersgrenze bei der Auswahl von Benutzern fest.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
age_min |
Integer | 20 | 18-99 (kleiner als age_max ) |
Beispiel-Werte
-
30
- nur Benutzer die älter als 30 Jahre alt sind
Beispiel-Verwendung
icony('get', 'activities', 'json', aCallback, {age_min: 30});
Pfeil nach unten
String arrow_down
Optional.
Gültig für:
activities/dom
Legt das Pfeilsymbol fest, das im Aktivitäten-Modul für den "nach unten"-Button hinterlegt wird.
Feldame | Werttyp | Standardwert |
---|---|---|
arrow_down |
String | ⇓ |
Achtung: HTML wird nicht unterstützt. Um eine Grafik als Pfeil zu verwenden, setzen Sie einen leeren String. Sie können die Grafik dann via CSS einfügen oder im Callback das entsprechende DOM-Element manipulieren.
Beispiel-Werte
-
⇓
- Doppelter Pfeil nach unten (Standard-Symbol) -
↓
- Einfacher Pfeil nach unten -
nach unten
- Text "nach unten" wird dargestellt -
[leer]
- der leere String: Es wird kein Symbol dargestellt (z.B. um eine Grafik zu verwenden)
Beispiel-Verwendung
icony('get', 'activities', 'dom', aCallback, {arrow_down: ''});
Es wird kein "nach unten"-Pfeil dargestellt.
Pfeil nach oben
String arrow_up
Optional.
Gültig für:
activities/dom
Legt das Pfeilsymbol fest, das im Aktivitäten-Modul für den "nach oben"-Button hinterlegt wird.
Feldame | Werttyp | Standardwert |
---|---|---|
arrow_up |
String | ⇑ |
Achtung: HTML wird nicht unterstützt. Um eine Grafik als Pfeil zu verwenden, setzen Sie einen leeren String. Sie können die Grafik dann via CSS einfügen oder im Callback das entsprechende DOM-Element manipulieren.
Beispiel-Werte
-
⇑
- Doppelter Pfeil nach oben (Standard-Symbol) -
↑
- Einfacher Pfeil nach oben -
nach oben
- Text "nach oben" wird dargestellt -
[leer]
- der leere String: Es wird kein Symbol dargestellt (z.B. um eine Grafik zu verwenden)
Beispiel-Verwendung
icony('get', 'activities', 'dom', aCallback, {arrow_up: ''});
Es wird kein "nach oben"-Pfeil dargestellt.
Widget automatisch laden
Integer auto_load
Optional.
Gültig für:
activities/dom
, activities/json
Standardmäßig werden Widgets automatisch ausgeführt, sobald ein Script und die zugehörigen DOM-Elemente verfügbar sind. Dieses Feld kann dazu verwendet werden dieses Verhalten abzustellen.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
auto_load |
Integer | 1 | 0,1 |
Beispiel-Werte
-
0
- Widget nicht automatisch laden (kann immer noch manuell geladen werden) -
1
- Widget automatisch laden
Beispiel-Verwendung
icony('get', 'tips', 'dom', aCallback, {auto_load: 0});
Anzahl Datensätze
Integer count
Pflichtfeld.
Gültig für:
activities/dom
, activities/json
, tips/dom
, tips/json
Legt fest, wie viele Datensätze geladen werden sollen. Sind weniger Daten verfügbar, werden auch entsprechend weniger Datensätze zurück gegeben. Dies kann z.B. der Fall sein, wenn durch andere Felder die Auswahl stark eingeschränkt wurde.
Feldame | Werttyp | Pflichtfeld | Erlaubte Werte |
---|---|---|---|
count |
Integer | Ja | 1-100 |
Beispiel-Werte
-
10
- lädt zehn Datensätze vom Server
Beispiel-Verwendung
icony('get', 'tips', 'json', aCallback, {count: 10});
Land
Integer country
Optional.
Gültig für:
activities/dom
, activities/json
, search/dom
, tips/dom
,
tips/json
Es werden nur Benutzer aus dem angegebenen Land in das Ergebniss mit eingeschlossen.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
country |
Integer | [leer] | 41,43,49 CH,AT,DE [leer] |
Gültige Werte sind Ländercodes entsprechend der Beispiele.
Beispiel-Werte
-
41
- Schweiz -
43
- Österreich -
49
- Deutschland -
[leer]
- Keine Einschränkung im Bezug auf das Land
Beispiel-Verwendung
icony('get', 'tips', 'json', aCallback, {country: 49});
CSS-Prefix
String css_prefix
Pflichtfeld.
Gültig für:
activities/dom
, search/dom
, tips/dom
Prefix, dass allen IDs und Klassennamen in den erzeugten DOM-Elementen vorangestellt wird.
Feldame | Werttyp | Pflichtfeld | Erlaubte Werte |
---|---|---|---|
css_prefix |
String | Ja | gültige CSS-Bezeichner |
Beispiel-Werte
-
icony_
- Stellt das Prefix allen IDs und Klassennamen voran
Beispiel-Verwendung
icony('get', 'search', 'dom', aCallback, {css_prefix: 'icony_'});
Debugging-Modus
Integer debug
Optional.
Gültig für:
activities/dom
, activities/json
, search/dom
, tips/dom
,
tips/json
Aktiviert den Debugging-Modus. Das Caching von Anfragen wird abgeschaltet und Fehlermeldungen als Antwort gesendet.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
debug |
Integer | 0 | 0,1 |
Hinweis: Nicht für den produktiv Einsatz geeignet! Verzögert die Ladezeiten und erzeugt u.U. JavaScript-Fehler.
Beispiel-Werte
-
0
- kein Debugging -
1
- Debugging-Modus ist aktiviert
Beispiel-Verwendung
icony('get', 'tips', 'dom', aCallback, {debug: 1});
Geschlecht
Integer gender
Optional.
Gültig für:
tips/dom
, tips/json
Legt fest, ob nur weibliche oder nur männliche Benutzer in das Ergebniss mit eingeschlossen werden - oder ob keine Auswahl nach dem Geschlecht erfolgen soll.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
gender |
Integer | 0 | 0,1,2 |
Beispiel-Werte
-
0
- Benutzer beider Geschlechter -
1
- nur männliche Benutzer -
2
- nur weibliche Benutzer
Beispiel-Verwendung
icony('get', 'activities', 'json', aCallback, {gender: 2});
Kleine Vorschaubilder
Integer use_thumbnails
Optional.
Gültig für:
activities/dom
, activities/json
Legt fest, ob eine URL für kleine Vorschaubilder zurück geliefert werden soll.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
use_thumbnails |
Integer | 1 | 0,1 |
Beispiel-Werte
-
0
- normale Bildergröße -
1
- kleine Vorschaubilder
Beispiel-Verwendung
icony('get', 'activities', 'dom', aCallback, {use_thumbnails: 0});
Postleitzahlbereich
String zip
Optional.
Gültig für:
activities/dom
, activities/json
, tips/dom
, tips/json
Es werden nur Benutzer aus dem definierten Postleitzahlbereich in das Ergebniss mit eingeschlossen.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
zip |
String | [leer] | CSV |
Hinweis: Wird ignoriert, wenn Land nicht gesetzt ist.
Beispiel-Werte
-
70
- Benutzer aus dem Postleitzahlbereich 70 (Stuttgart) -
70,720,727
- Benutzer aus Stuttgart (70x), Tübingen (720x) oder Reutlingen (727x) -
10115
- Benutzer mit der PLZ 10115 -
[leer]
- keine Einschränkung im Bezug auf die PLZ
Beispiel-Verwendung
icony('get', 'activities', 'json', aCallback, {zip: '70,720,727'});
PLZ-Vorbelegung der Suchmaske
String zip
Optional.
Gültig für:
search/dom
Versteckt das PLZ-Feld der Suchmaske und belegt es mit dem angegebenen Wert vor. Die Suche wird damit auf Benutzer im Umkreis von 100km um diesen Ort/PLZ eingeschränkt.
Feldame | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
zip |
String | [leer] | eine vollständige PLZ |
Beispiel-Werte
-
72760
- Vorbelegung mit PLZ 72760 (Reutlingen) -
[leer]
- keine Vorbelegung
Beispiel-Verwendung
icony('get', 'search', 'dom', aCallback, {zip: '72760'});
Formate
Felder werden bei get
-Anfragen in einem Optionen-Objekt an die IconJS-API geschickt. Je nach
Modultyp und Antwortformat können oder müssen verschiedene Felder gesetzt werden. In diesem Abschnitt werden
alle verfügbaren Felder aufgelistet und erleutert.
Antwortformat Allgemeines Format einer Abfrage-Antwort
Nach Bearbeitung einer Anfrage durch den Sever wird die Callback-Funktion aufgerufen. Es wird ein Object
mit folgenden Feldern als Argument übergeben:
Feldame | Werttyp | Inhalt |
---|---|---|
data |
mixed |
Die eigentlichen Antwortdaten. Siehe JSON und DOM. |
format |
String |
Das angeforderte Format des Moduls. |
object_name |
String |
Name des globalen Icony JS-API Objekts. |
options |
Object |
Die bereinigten Anfrage-Optionen. |
request_id |
String |
ID der Anfrage, zur späteren Referenzierung |
time |
String |
Zeitpunkt der Anfrage-Antwort, formatiert nach RFC 2822 |
type |
String |
Der angefragte Modultyp. |
Beispiel-Daten
{ type: "activities", format: "json", time: "2013-11-28T11:30:20+01:00", object_name: "icony", request_id: "ie58c2958f63ff5a61385634620111", options: { age_max: "35", age_min: "20", count: "3", country: "49", zip: "70" }, data: [..] }
(Inhalt des data
-Felds ausgelassen.)
JSON
Wurde in der Anfrage JSON als Antwortformat gewählt, so enthält das data
-Feld des Antwortobjekts
ein Array aus Daten-Objekten Array[Object]
. Welche Felder die einzelnen Objekte bereitstellen
ist unter Module aufgeführt.
Beispiel-Daten
[{ username: "someRandomUser", vcardurl: "http://www.icony.de/vcard/someRandomUser/", age: "20", }, { username: "anOtherUser", vcardurl: "http://www.icony.de/vcard/anOtherUser/", age: "35", }]
Beispiel-Verwendung
var myCallback = function(jsonResponse) { for (var i=0; i < jsonResponse.data.length; i++) { var image = document.createElement("img"); image.src = jsonResponse.data[i].imageurl; var link = document.createElement("a"); link.href = jsonResponse.data[i].vcardurl; link.appendChild(image); document.body.appendChild(link); } };
DOM Document Object Model
Das DOM-Antwortformat liefert im data
-Feld des Antwortobjekts ein DOM Node
-Objekt
oder eine DOM NodeList
; die jeweils benötigten Elemente sind komplett darin enthalten. Das
Node
- bzw. NodeList
-Objekt kann - mit Rücksicht auf die HTML-Spezifikation - an
beliebiger Stelle in der Seite eingefügt werden.
Die Anfrage wird ausgeführt, sobald das DOM vollständig geladen wurden und manipuliert werden kann.
Beispiel-Verwendung
document.addEventListener("DOMContentLoaded", function(event) { var myCallback = function(domResponse) { document.getElementById("target").appendChild(domResponse.data); }; });
Modul-Referenz
Die Antwort einer get
-Anfrage ist ein Modul. Abhängig von dem angefragten Format enthält das data
-Feld
des Antwort-Objekts spezielle Daten die in der Callback-Funktion verarbeitet werden. Diese Referenz beschreibt
welche Antworten Sie für die möglichen Module und Formate erhalten werden.
Aktivitäten-Modul Document Object Model
Modul: activities
Format: dom
Widget-Scripte:
Es wird eine Anzahl von Benutzeraktivitäten zurückgegeben. Jeder Eintrag besteht dabei aus einer kurzen Benutzerinfo, dem Profilbild und einer Beschreibung der Aktivität. Bild und Name sind mit der Visitenkarte des Benutzers verlinkt.
Für dieses Modul gibt es ein Widget, das nur eine kleine Anzahl der letzten Aktivitäten anzeigt und automatisch die weiteren Einträge durchscrollt.
Beispiel-Verwendung
icony('get', 'activities', 'dom', myCallback, {count: 10, css_prefix: 'icony_'});
Antwortdaten
Die Antwort enthält einen DOM-Node
mit der folgenden HTML-Repräsentation:
<div class="icony_container" data-id="i606012d7f6d0b0201386589358598"> <div class="icony_button icony_button_up"><span>⇑</span></div> <div class="icony_button icony_button_down"><span>⇓</span></div> <div class="icony_scroll"> <div class="icony_entry"> <a href="http://partner-url.de/vcard/CoolerUser81/" target="_blank" class="icony_image"> <img src="//www.icony.com/userimages/icony/2013/06/12/1957AB151B6000.JPG" alt="CoolerUser81"> </a> <span class="icony_info"> <a href="http://www.icony.de/vcard/CoolerUser81/" target="_blank">CoolerUser81</a><br> 42 Jahre, Reutlingen (DE)<br> hat sich eben eingeloggt. </span> </div> </div> </div>
Für jede Aktivität wird ein weiteres div
-Element mit der Klasse icony_entry
eingefügt. Das Attribut data-id
des äußersten Elements, refernziert auf eine
requestId
(Rückgabewert von get
-Anfragen).
Bitte beachten Sie, dass im Beispiel icony_
als generischer CSS-Präfix verwendet wurde. Bei der
Implementierung ist dieser natürlich durch das von Ihnen gewählte Präfix zu ersetzen.
Aktivitäten-Modul JSON
Modul: activities
Format: json
Es wird eine Anzahl von Benutzeraktivitäten zurückgegeben. Jeder Eintrag besteht dabei aus den Benutzerdaten (Username, Alter, Geschlecht, Wohnort, PLZ und Land), URLs zu Visitenkarte und Profilbild des Benutzers, sowie einer Aktivitäts-ID. Zusätzlich ist ein kurzer Beschreibungstext mit Alter und Wohnort und eine textliche Aktivitätsbeschreibung in der Antwort enthalten.
Beispiel-Verwendung
icony('get', 'activities', 'json', myCallback, {count: 10});
Antwortdaten
response.data = [{ username: "CoolerUser81", vcardurl: "http:\/\/partner-url.de\/vcard\/CoolerUsername81\/", imageurl: "\/\/www.icony.com\/userimages\/icony\/2013\/06\/27\/1957AB151B6DEA1408CC2427-1372337000.JPG", age: "42", gender: "2", // 1 = männlich, 2 = weiblich zip: "7276xx", // PLZ wird nur gekürzt zurück gegeben city: "Reutlingen", country: "DE", userinfo_text: "42 Jahre, Reutlingen (DE)", // Text mit Alter und Wohnort action: "smiley_received", // Akitivitäts-ID: login, profile_pic, registration, // smiley_received, sticker_create, sticker_pickup action_text: "hat einen Smiley erhalten." // Aktivitätsbeschreibung }]
Das data
-Feld der Antwort enthält ein Array
mit den verschiedenen Datensätzen. Ein
einzelner Datensatz ist ein Objekt mit den oben stehenden Feldern.
Benutzertipps Document Object Model
Modul: tips
Format: dom
Die Antwort des Moduls ist eine Reihe von Benutzerbilder verlinkt mit der jeweiligen Visitenkarte.
Beispiel-Verwendung
icony('get', 'tips', 'dom', myCallback, {count: 5, css_prefix: 'icony_'});
Antwortdaten
Ein DOM-Node
der durch das folgende HTML repräsentiert wird:
<div class="icony_box"> <div class="icony_list_item"> <a href="http://partner-url.de/vcard/CoolerUser81/" title="CoolerUser81" target="_blank"> <img border="0" src="//www.icony.com/userimages/icony/2013/06/12/1957AB151B6000.JPG" alt="CoolerUser81"> </a> </div> <div class="icony_list_item"> <a href="http://partner-url.de/vcard/NochEinUser11/" title="NochEinUser11" target="_blank"> <img border="0" src="//www.icony.com/userimages/icony/2013/06/11/1957B6DCE077700.JPG" alt="NochEinUser11"> </a> </div> <div class="icony_list_end"></div> </div>
Für jeden Benutzertipp wird ein weiteres div
-Element mit der Klasse icony_list_item
eingefügt.
Bitte beachten Sie, dass im Beispiel icony_
als generischer CSS-Präfix verwendet wurde. Bei der
Implementierung ist dieser natürlich durch das von Ihnen gewählte Präfix zu ersetzen.
Benutzertipps JSON
Modul: tips
Format: json
Eine Anfrage an das Modul liefert eine Anzahl von Datensätzen zurück, bestehend aus den Informationen Username, Alter, Geschlecht, Wohnort, PLZ und Land. Zusätzlich enthalten die Daten URLs zur Visitenkarte und zum Profilbild des Benutzers.
Beispiel-Verwendung
icony('get', 'tips', 'json', myCallback, {count: 5});
Antwortdaten
response.data = [{ username: "CoolerUser81", vcardurl: "http:\/\/partner-url.de\/vcard\/CoolerUsername81\/", imageurl: "\/\/www.icony.com\/userimages\/icony\/2013\/06\/27\/1957AB151B6DEA1408CC2427-1372337000.JPG", age: "42", gender: "2", // 1 = männlich, 2 = weiblich zip: "7276xx", // PLZ wird nur gekürzt zurück gegeben city: "Reutlingen", country: "DE" }]
Das data
-Feld der Antwort enthält ein Array
mit den verschiedenen Datensätzen. Ein
einzelner Datensatz ist ein Objekt, das aus den oben stehenden Feldern besteht.
Suchmaske Document Object Model
Modul: search
Format: dom
Das Modul stellt eine Suchmaske dar, mit Eingabefeldern für das gesuchte Geschlecht, Alter und Postleitzahlenbereich. Die Ergebnisse werden auf der jeweilige Partner-Plattform in einem neuen Fenster angezeigt.
Beispiel-Verwendung
icony('get', 'search', 'dom', myCallback, {css_prefix: 'icony_'});
Antwortdaten
Eine Anfrage an das Modul gibt in der Anwort einen einzelnen DOM-Node
mit der folgenden
HTML-Entsprechung zurück.
<div class="icony_search_box"> <form action="http://partner-url.de/search/results.php" target="_blank" method="post"> <input type="hidden" value="myAffiliate" name="AID"> <input type="hidden" value="1" name="A1Q1"> <input type="hidden" value="1" name="A1Q2"> <div class="icony_gender"> <label for="GENDER[]" class="icony_default_label icony_gender_label">Ich suche:</label> <select name="GENDER[]" class="icony_default_field icony_gender_field"> <option value="0">Frauen/Männer</option> <option value="2">Frauen</option> <option value="1">Männer</option> </select> </div> <div class="icony_default_seperator icony_gender_seperator"></div> <div class="icony_age"> <label for="AGE_MIN" class="icony_default_label icony_age_label">von</label> <select name="AGE_MIN" class="icony_default_field icony_age_field">[..]</select> <label for="AGE_MAX" class="icony_default_label icony_age_label">bis</label> <select name="AGE_MAX" class="icony_default_field icony_age_field">[..]</select> </div> <div class="icony_default_seperator icony_age_seperator"></div> <div class="icony_zip"> <label for="ZIP" class="icony_default_label icony_zip_label">im PLZ-Bereich</label> <input type="text" maxlength="5" size="5" name="ZIP" class="icony_default_field icony_zip_field"> </div> <div class="icony_default_seperator icony_zip_seperator"></div> <div class="icony_submit"> <input type="submit" name="go" class="icony_submit_button" title="Anfrage abschicken" alt="Anfrage abschicken"> </div> </form> </div>
Bitte beachten Sie, dass im Beispiel icony_
als generischer CSS-Präfix verwendet wurde. Bei der
Implementierung ist dieser natürlich durch das von Ihnen gewählte Präfix zu ersetzen.
Widgets
Für einige Module wird zusätzlich ein sog. Widget angeboten. Im Wesentlichen können Sie darunter ein Script verstehen, dass einen eigentlich statischen Inhalt dynamisch darstellt. So kann beispielsweise eine lange Liste von Benutzeraktivitäten so dargestellt werden, dass immer nur ein kleiner Teil der Aktivitäten angezeigt wird; das Widget-Script würde dafür Sorge tragen, dass die Anzeige durchwechselt.
Aktivitäten-Widget
Modul: activities
Widget-Scripte:
Das Aktivitäten-Widget stellt die letzten Benutzeraktivitäten der Plattform dar. Es präsentiert dazu eine kleine Auswahl und wechselt regelmäßig die Ansicht um Aktivität zu simulieren. Technisch betrachtet besteht das Widget aus einer längeren Liste von Aktivitäten, aus der aber durch CSS und HTML nur ein Ausschnitt angezeigt wird. Ein Script animiert diese Liste mit einem Scroll-Effekt, so dass die Ansicht immer wechselt und letztlich alle Aktivitäten angezeigt werden.
Dazu berechnet das Script zuerst die Gesamthöhe des Containers aus der Anzahl der darzustellenden Einträge.
Die Berechnung erfolgt aus der Anzahl an darzustellenden Einträgen und der Höhe eines Eintrags inkl. padding
.
Da margin
hier ignoriert wird, sollte dieser auf 0px
gesetzt werden. Für jeden
Scroll-Vorgang berechnet das Script nun einen Wert für margin-top
um einen bestimmten Eintrag
an der ersten Stelle zu positionieren. Diese CSS-Änderung wird nun durch die verwendete
JavaScript-Bibliothek animiert.
Das Script und der DOM-Node
werden von der API bereitgestellt. Bestimmte CSS-Einträge müssen Sie
minimal selbst bereitstellen. Das weitere Styling liegt ebenfalls bei Ihnen, Sie können sich aber an unserem Beispiel orientieren.
Beispiel-Verwendung
Zuerst wird das Widget-Script vom Sever geladen. Danach wird eine get
-Anfrage gestellt, um die
Moduldaten zu erhalten. In Zeile 5 fügt der Callback den DOM-Node
in die Seite ein. Das Widget
wird automatisch gestartet, sobald alle nötigen Daten geladen wurden. In Zeile 8 und 9 werden noch zwei
Einstellungswerte geändert.
JavaScript
icony('script', 'activities', 'native'); document.addEventListener("DOMContentLoaded", function(event) { var activitiesId = icony('get', 'activities', 'dom', function(response) { document.getElementById("myActivitiesWidget").appendChild(response.data); }, {count: 50, css_prefix: 'icony_'}); icony('set', activitiesId, 'show', 7); icony('set', activitiesId, 'pause', 2000); });
CSS (minimales Setup)
/* Notwendig: */ #myActivitiesWidget div.icony_container { /* Versteckt das Element bis das Widget vollständig geladen wurde. Die Gesamthöhe wird durch das Script berechnet und gesetzt: Gesamthöhe = Anzahl Elemente * (Höhe + Padding eines Eintrags) */ height: 0px; /* Versteckt die Einträge außerhalb des aktuellen Sichtbereichs */ overflow: hidden; } /* Empfohlen: Diese Werte sollten Sie angegeben, um Probleme mit der Höhe eines Eintrags zu verhindern (z.B. bei überlangen Texten). Andernfalls kann die Ansicht verschoben werden. */ #myActivitiesWidget div.icony_container div.icony_entry { height: 70px; /* Wert kann frei gesetzt werden */ overflow: hidden; margin-top: 0px; margin-bottom: 0px; }
Variablen-Referenz
Variablen können über set-Befehle geändert werden und beeinflussen das Verhalten von Widgets. Es ist sowohl möglich Werte für alle Widgets eines Moduls zu setzen, als auch spezifisch für bestimmte Widgets. Spezifische Variablen werden gegenüber allgemeinen bevorzugt. Wenn keine Variablen gesetzt wurden, wird auf Standardwerte zurückgegriffen.
Beispiel-Verwendung
icony('set', 'activities', 'speed', 1000);
Automatisches Scrolling
Boolean auto_scroll
Gültig für:
activities
Legt fest, ob das Widget automatisch durch die Ergebnisse scrollt.
Variablenname | Werttyp | Standardwert |
---|---|---|
auto_scroll |
Boolean | true |
Beispiel-Werte
-
false
- kein automatisches Scrolling -
true
- automatisches Scrolling ist aktiv
Beispiel-Verwendung
Automatisches Scrolling für das Widget mit der ID requestId
wird dekativiert.
icony('set', requestId, 'auto_scroll', false);
Scrolling-Richtung
String direction
Gültig für:
activities
Legt die Start Scrolling-Richtung fest.
Variablenname | Werttyp | Standardwert | Erlaubte Werte |
---|---|---|---|
direction |
String | - (Minuszeichen) | -, + (Minus- oder Pluszeichen) |
Beispiel-Werte
-
-
- nach unten -
+
- nach oben
Beispiel-Verwendung
Setzt die Scrolling-Richtung so, dass zu Beginn nach oben gescrollt wird.
icony('set', 'activities', 'direction', '+');
Pausenzeit
Integer pause
Gültig für:
activities
Pausenzeit (in ms) zwischen zwei Scrolling-Animationen.
Variablenname | Werttyp | Standardwert |
---|---|---|
pause |
Integer | 4000 |
Beispiel-Werte
-
0
- kein Pause -
2000
- Pausenzeit von 2 Sekunden
Beispiel-Verwendung
Setzt die Pausenzeit für alle Aktivitäten-Widgetes auf 3 Sekunden.
icony('set', 'activities', 'pause', 3000);
Anzahl angezeigter Elemente
Integer show
Gültig für:
activities
Die Anzahl der Elemente die angezeigt werden.
Variablenname | Werttyp | Standardwert |
---|---|---|
show |
Integer | 3 |
Beispiel-Werte
-
0
- kein Element wird angezeigt -
5
- Darstellung von 5 Elementen
Beispiel-Verwendung
Das Widget mit der ID requestId
soll 7 Elemente anzeigen.
icony('set', requestId, 'show', 7);
Scrolling-Geschwindigkeit
Integer speed
Gültig für:
activities
Zeit (in ms) die eine Scrolling-Animation benötigen soll.
Variablenname | Werttyp | Standardwert |
---|---|---|
speed |
Integer | 1000 |
Beispiel-Werte
-
0
- kein Scrolling, direkter Wechsel der Darstellung -
2000
- Scrolling benötigt 2 Sekunden
Beispiel-Verwendung
Für alle Aktivitäten-Widgets soll die Scrolling-Geschwindigkeit 1000ms betragen, ...
icony('set', 'activities', 'speed', 1000);
... mit Ausnahme des Widgets mit der ID requestId
, das seine Darstellung ohne Animation sofort
ändern soll.
icony('set', requestId, 'speed', 0);
Fehlermeldungen
Bei einem Problem mit der Konfiguration, erhalten Sie in der Antwort auf eine get
-Anfrage
standardmäßig keine Fehlermeldungen. Stattdessen wird das data
-Feld der Antwort
den Wert null
enthalten. Wenn Sie in einer produktiven Umgebung die Antworten auf einen API-Fehler
hin überprüfen wollen, testen Sie bitte auf diesen null
-Wert.
zurück.
Wenn Fehlermeldungen zurück gegeben werden sollen (z.B. beim Testen), können Sie den Debugging-Modus aktivieren. Fehler werden dann normalerweise an die
JavaScript-Konsole Ihres Browsers gesendet. Wurde jedoch als Format json
angegeben, ist die
Fehlermeldung im data
-Feld der Antwort enthalten.
Unbekanntes Modul
Fehler / Übersetzung
API type "api_module" not found.
API-Modul "api_module" nicht gefunden.
Der Fehler tritt auf, wenn eine Anfrage für ein nicht vorhandenes Modul gestellt wird. Stellen Sie sicher, dass nur gültige Module angefragt werden.
Nicht unterstütztes Format
Fehler / Übersetzung
Format "api_format" not supported for API Type "api_module".
Format "api_format" nicht unterstützt für Modul "api_module".
Dieser Fehler tritt auf, wenn ein Format angefragt wird, dass nicht gültig ist oder von dem angefragten Modul nicht unterstützt wird. Stellen Sie sicher, dass das angefragte Modul auch das gewählte Format unterstützt.
Pflichtfeld fehlt
Fehler / Übersetzung
Required field "field_name" for API Type "api_module" with format "api_format" is
missing.
Pflichtfeld "field_name" für Modul "api_module" im Format "api_format" fehlt.
Ein für diese Modul/Format-Kombination verpflichtend anzugebendes Feld wurde nicht gefunden. Überprüfen Sie, ob alle Pflichtfelder in der Anfrage enthalten sind.
Unbekannte Plattform
Fehler / Übersetzung
Unknown Platform Identifier.
Unbekannte Plattform-ID.
Sie haben keine oder eine fehlerhafte Plattform-ID in der create
-Methode übergeben. Bitte
korrigieren Sie diese Angabe. Falls Sie nicht wissen, wie Ihre Plattform-ID lautet, wenden Sie sich gerne an
uns.
JSONP fehlerhaft
Fehler / Übersetzung
JSONP function not set.
JSONP-Funktion nicht gesetzt.
Diese Meldung kann auftreten, wenn es ein (nicht unbedingt näher einzugrenzendes) Problem mit der Callback-Funktion gibt. Stellen Sie zuerst sicher, dass ein Callback existiert und dieser fehlerfrei ist. Überprüfen Sie anschließend die grundlegende Einrichtung der API.