@mediacologne/angular-data-module

{:toc}

News

• Achtung! Die neue Version 4.0.0 beinhaltet einige Breaking Changes dahier die DataStoreView eingeführt wurde. Die letzte kompatible Version ohne DataStoreView ist die 3.4.0!

Installation

Install the NPM Module

$ npm install @mediacologne/angular-data-module

Using the Library

Nach der Installation muss die Library durch das Importieren des DataModule verfügbar gemacht werden.

// Import your library
import { DataModule } from '@mediacologne/angular-data-module';

@NgModule({
  imports: [
    DataModule
  ]
})
export class AppModule { }

Documentation

Concepts

Es folgt eine kurze Erklärung über die Konzepte der einzelnen Komponenten dieser Library.

StoreManager

Der StoreManager kümmert sich um die Instanziierung eines DataStores bzw. um die Verwaltung der DataStore Instanzen. Alle über den StoreManager erzeugten DataStores werden von diesem in einem Service Container vorgehalten.

---

DataStore

Der DataStore ist das zentrale Element der Library. Innerhalb des DataStores werden alle Daten gehalten. Jeder DataStore verfügt über Methoden zum Hinzufügen, Löschen, Updaten von Daten.

Queries

Queries bieten eine Möglichkeit, innerhalb der Daten eines DataStores zu Suchen. Eine Besonderheit der Suchmöglichkeiten sind die StoredQueries, welche einerseits zum Zeitpunkt der Suche ausgeführt werden, als auch ein weiteres Mal ausgeführt werden sobald sich das Suchergebnis verändert haben könnte. Wird beispielsweise über eine Queries ein bestimmtes Objekt gesucht welches sich nicht im DataStore befindet, wird die Queries automatisch ein weiteres Mal ausgeführt sobald sich neue Daten im Store befinden.

---

DataStoreView

Mit Hilfe der DataStoreViews werden die Daten eines DataStores auf verschiedene Weisen/Sichten representiert. Der DataStoreView wird eine DataStore Instanz zugewiesen, auf welcher die DataStoreView anschließend operiert. Die DataStoreView bietet sogenannte storeFilter an.

StoreFilter

Mit Hilfe von storeFilters können die Daten eines DataStores auf verschiedene Sichten representiert werden. Eine storeFilter wird wie ein Filter über die Daten gelegt und steht anschließend innerhalb von Typescript als auch den Templates über eine spezielle StoreFilterPipe zur Verfügung. Der Unterschied zwischen StoreFilters und Queries ist im wesentlichen, dass Queries einmalig ausgeführt werden um ein bestimmtes Ergebnis zu erhalten während ein StoreFilter vorzugsweise innerhalb eines Templates verwendet wird

---

Code

// Get a DataStore Instance
this.customerStore = StoreManager.get("customer");

this.customerStore.fromObservable(getDataFromObservable()).then(() => {
  // DataStore is filled with data from the given source
});

// Create a DataStoreView from customerStore
this.customerView = new DataStoreView(this.customerStore);
this.customerView.addSelection("fromKoeln", {city: "Köln"});

// Query an object
this.customerView.query({city: "Köln"}).subscribe(result => {
    console.log("Result", result);
});

// Query an object as a StoredQuery
this.customerView.queryAsObservable({city: "Köln"}).subscribe(result => {
    console.log("Result", result);
});

<!-- 
Access an Presentation from a DataStoreView Synchronously (as an Array) 
-->
{{((ustomerView | selection:'fromKoeln':false)[0].zipcode}}

<!-- 
Access an Presentation from a DataStoreView Asynchronously (as an Observable)
This Asynchronously method is preferred if the DataStoreView could contain a large DataStore
-->
{{((customerView | selection:'fromKoeln') | async)[0].zipcode}}

Developing the Library

Während der Entwicklung an der Library muss diese getestet werden, gebuilded werden sowie gepublished werden können. Hier steht wie's geht:

---

Testing

Um die Library zu testen muss im ./demo Ordner ein ng serve ausgeführt werden. Änderungen an der Library werden dann sofort in dem Example verfügbar. Gegebenfalls muss hin und wieder ng serve neugestartet werden.

Aus irgendeinem Grund kommt nach dem Start von ng serve manchmal sofort ein Fehler

ERROR in Error: Error encountered resolving symbol values statically. Function calls are not supported. Consider replacing the function or lambda with a reference to an exported function

Dieser Fehler kann ignoriert werden, denn er verschwindet bei der nächsten Quellcode Änderung. Grund des Fehlers ist unklar => https://github.com/angular/angular-cli/issues/3707

---

Building

Um die Library zu builden wird im ./ Verzeichnis ein npm run build ausgeführt. Dadurch wird die kompilierte Version im ./dist Verzeichnis erzeugt. Die Library wurde erstellt mittels yo a2lib libname von https://github.com/johannesjo/generator-angular2-lib

---

Publishing

Um eine neue Version der Library zu publishen wird im ./ Verzeichnis ein npm publish ausgeführt. Es ist zu beachten, dass vor dem publishen einer neuen Version unbedingt die Versionsnummer angehoben werden muss.

Generell empfiehlt es sich, zuerst die Versionsnummer anzuheben und anschließend ein build anzustoßen. Ist dies erfolgreich kann die Library gepublished und anschließend die Code Änderung commited werden.