Wiki

Wenn sich die Struktur deines Drops durch Änderungen an der config.json ändert, kann es notwendig sein, eine neue Version für dein Drop einzuführen um Daten zu migrieren. Hierdurch bist du in der Lage, bestehende Drop-Instanzen deines Drops in die neue Strutkur zu überführen. Dropper bietet dir hierfür einen Upgrade-Mechanismus an.

Die upgrade.js ist eine Javascript-Datei, die für Datenmigrationen deiner Drops zwischen neuen Versionen verantwortlich ist. Ein Upgrade auf eine neue Drop Version kann darin von dir definiert werden und du hast die Möglichkeit Code auf den Daten der betroffenen Drops auszuführen:

ACME_Demo/config.json

In der Konfigurationsdatei deines Drops hast du die Möglichkeit eine Versionsnummer deines Drops zu pflegen. Diese solltest du heraufsetzen um ein neues Upgrade anzulegen.

{
    "name": "Demo Drop",
    "description": "Ein kleines Demo Drop",

    "version": "1.0.2",

    ...
}

Für jeden Sprung in der Versionsnummer deines Drops solltest du jetzt eine Upgrade-Funktion anlegen, welche bestehende Daten deiner Drop-Instanzen migriert oder neue Eigenschaften hinzufügt, falls in deiner Konfiguration neue Einstellungen eingeführt wurden.

ACME_Demo/upgrade.js

angular.element(document).ready(function() {

    // register ACME_Demo upgrades
    angular.injector(['app']).invoke(['upgrade', function(upgrade) {

        /**
         * Upgrade from 1.0.0 to 1.0.1
         * Adds a new Property "demo" to each drop istance
         */
        upgrade.addDropUpgrade("ACME_Demo", "1.0.0", "1.0.1", function(drop, config) {

            drop.demo = true;
            return drop;

        });

        /**
         * Upgrade from 1.0.1 to 1.0.2
         * Removes the 'demo' property, introduced in version 1.0.1
         */
        upgrade.addDropUpgrade("ACME_Demo", "1.0.1", "1.0.2", function(drop, config) {

            delete(drop.demo);
            return drop;

        });

    }]);
});

Nach dem erneuten Laden des Dropper Backends werden alle Instanzen deines Drops automatisch in die entsprechenden Upgrade-Funktionen gegeben. Hierbei ist es auch möglich, dass diese mehrere Upgrade-Funktionen nacheinander durchlaufen. In den Upgrade-Funktionen kannst du die Daten der Instanzen modifizieren. Wichtig ist, dass die Upgrade-Funktion die modifizierte Drop-Instanz auch wieder zurückgibt (return drop;).

Um einen Fehler beim Upgrade zu erzeugen, gebe anstatt der drop Instanz einen String mit der Fehlernachricht zurück. Diese wird dem Nutzer dann im Dropper Backend angezeigt.