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.

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');

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});

Lädt asynchron ein Script vom Icony JS-API Server zur Ausführung von Widgets.

icony('script', moduleType, jsLibrary);

Parameter

  • String moduleType - Der moduleType 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');

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 die requestId eines gets oder ein moduleType (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);

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.

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'});

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});

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});

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.

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.

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});

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});

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});

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_'});

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});

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});

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});

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'});

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'});

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.

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.)

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);
      }
    };

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);
      };
    });

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.

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.

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.

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.

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.

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.

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.

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 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);

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);

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', '+');

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);

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);

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);

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.

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.

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.

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.

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.

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.