npm package: @frontendart/smdb-widgets
Description: SMDB UI components and widgets
Latest version: 0.1.1

# SmdbWidgets

This library groups the numerous UI widgets that visualize data that comes from SMDB.
You can use it independently, providing data of your own, or use together with **smdb-api** to simplify retrieving data.

## Using the library

As the library is constructed that every component has its own module, you should import every individual component's module you would like to use in your app.
The currently available components are the following:

* `branch-info-box`
* `project-info-box`
* `project-search-box`

To make use of a component, you have to import its module wherever you want:

```javascript
import {ProjectSearchBoxModule} from '@frontendart/smdb-widgets';

@NgModule({
  declarations: [AppComponent],
  imports:      [
    ...
    ProjectSearchBoxModule,
    ...    
  ]
})
export class WidgetModule {
}
```

**NOTE:** there is also a module called `SmdbWidgetsModule` that looks like it exports all available widget modules, but that's a false assumption! It is used to provide a custom service to the API. See the details in the next section.

Also, you have to include the stylesheet file provided with the widgets as usual:

 1. In a global `styles.css` file:
 
 ```css
 @import '~@frontendart/smdb-widgets/style/styles';
 ```
 
 2. In angular.json: 
 
 ```javascript
 "styles": [
   "node_modules/@frontendart/smdb-widgets/style/styles.scss",
   "styles.scss"
 ]
 ```
 
 3. In index.html
 
 ```html
 <link rel="stylesheet" href="node_modules/@frontendart/smdb-widgets/style/styles.scss">
 ```

#### Providing the service layer

These components are 'dumb' in the way they can not retrieve data by their own. They just present input data to the users. 

By default, you are encouraged to use this library together with the friendly **smdb-api** library, so you will have the appropriate service layer to retrieve the data from the SMDB server.
This can be done by adding the `@frontendart/smdb-api` dependency to your `package.json` file as usual.

However, if you would like to supply your own service implementation, you are free to.

To supply a custom service layer, import the `SmdbWidgetsModule` through its `.forRoot()` method **AFTER** every component module imports like below:

```javascript
import {SmdbApiModule} from '@frontendart/smdb-api';

@NgModule({
  declarations: [AppComponent],
  imports:      [
    ...
    ProjectSearchBoxModule,
    SmdbWidgetsModule.forRoot(MockSmdbApiService),
  ],
  providers:    [],
  bootstrap:    [SmdbAppComponent]
})
export class AppModule {
}
```

Here, `MockSmdbApiService` refers to an arbitrary class type that has the same methods as the original `SmdbApiService`.

## Development

### Code scaffolding

Run `ng generate component component-name --project smdb-widgets` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project smdb-widgets`.
> Note: Don't forget to add `--project smdb-widgets` or else it will be added to the default project in your `angular.json` file.

When you add a new component, you have to add a separate module to help modularize the architecture.
This concept is called [SCAM : Single Component Angular Module][1]. 
That module should 
* declare only the single component that it is tied to 
* import only the module that the given component needs
* export only the single component that it is tied to  

After that, you have to add your new module and component to `public_api.ts`

```javascript   
export * from './lib/[component-path]/[component-module]';

...

export * from './lib/[component-path]/[component-file]';
```

## Build

Run `ng build smdb-widgets` to build the project. The build artifacts will be stored in the `dist/` directory.


## Running unit tests

Run `ng test smdb-widgets` to execute the unit tests via [Karma](https://karma-runner.github.io).

[1]: https://blog.angularindepth.com/angular-revisited-tree-shakable-components-and-optional-ngmodules-329a4629276d