npm package: @mediacologne/angular-data-module
Latest version: 5.3.0

# @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

```bash
$ npm install @mediacologne/angular-data-module
```

## Using the Library

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

```typescript
// 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 `DataStore`s bzw. um die Verwaltung der `DataStore` Instanzen. Alle über den `StoreManager` erzeugten `DataStore`s 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 `DataStore`s 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 `DataStoreView`s werden die Daten eines `DataStore`s 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 `storeFilter`s können die Daten eines `DataStore`s 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 `StoreFilter`s 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


```typescript
// 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);
});
```

```html
<!-- 
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.