Note: this is a public version for the following file (which may be moved to master soon): https://github.com/trilogy-group/devfactory-coderamp/blob/milestone/CR-1048-Refactor-to-an-Angular-Component/projects/coderamp-lib/README.md

Integration Guide

Dependencies required

See the peerDependencies key in the package.json for coderamp-lib (i.e projects/coderamp-lib/package.json) to view all the dependencies needed in the parent project to be able to properly use coderamp-lib.

Installing the library

1. Run npm run pack:lib to generate a coderamp-lib-<version>.tgz file in the dist/coderamp-lib directory.
2. Copy this file to the root of any angular project you want to integrate it into.
3. In the root of that angular project, run npm install coderamp-lib-<version>.tgz (replacing <version> with the version of the file).

You may want to commit the tgz file into the code so that npm install always works, until we deploy this repository to nexus.

Using the library

1. Add the StoreModule to your app.module.ts file imports

Set strictStateImmutability and strictActionImmutability options to true (see example in the next point).

2. Add the EffectsModule import to your app.module.ts.

Your app.module.ts should now look something like this

@NgModule({
  declarations: [ ... ],
  imports: [
    //...
    StoreModule.forRoot(
      {},
      {
        runtimeChecks: {
          strictStateImmutability: true,
          strictActionImmutability: true
        }
      }),
    EffectsModule.forRoot([ <your ngrx effects file>]),
  ],
  bootstrap: [ ... ],
})
export class AppModule { }

See src/app/app.module.ts for sample implementation.

3. Handle the necessary ngrx actions

There are two actions for which the parent app must define effect handlers. See src/app/modules/repos/pages/repos-list-wrapper/repos-list-wrapper.effects.ts for a sample implementation on how to handle via effects.

Alternatively, see the next section to handle by listening to state variable change.

addPropsToRepos

Called whenever a batch of repositories is retrieved. You will be given an object of type RepositoryList and must modify and return a type of RepositoryListProcessed. Both these interfaces are defined and can be imported from coderamp-lib. The primary fields to be added/modified are the following and exist in the contents key

• disabled: boolean: Determines whether the checkbox is disabled/enabled
• disabledStatus: RepoStatus: Defines the reason for disabling the checkbox. This key can be left undefined. RepoStatus type can be exported from coderamp-lib.
• visible: boolean: Determines whether the row should be visible or not in the final output.

See src/app/modules/repos/pages/repos-list-wrapper/repos-list-wrapper.effects.ts for a sample implementation.

computeDisabledStatusForRepo

Given a single repo, it must return the disabled and disabledStatus for that repo. In most cases, the logic for this would be the same would already have been written in the effect which handles the addPropsToRepos action.

See src/app/modules/repos/pages/repos-list-wrapper/repos-list-wrapper.effects.ts for a sample implementation.

4. Handle the necessary variable change

coderampLibInternal.reposToOnboard

Note: This can alternatively be handled by handling the onboardRepos action.

Subscribe to the ngrx store coderampLibInternal.reposToOnboard variable and handle change accordingly. See src/app/modules/repos/pages/repos-list-wrapper/repos-list-wrapper.component.ts for sample implementation.

CoderampLib - Auto Generated Section

This library was generated with Angular CLI version 8.2.14.

Code scaffolding

Run ng generate component component-name --project coderamp-lib to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project coderamp-lib.

Note: Don't forget to add --project coderamp-lib or else it will be added to the default project in your angular.json file.

Build

Run ng build coderamp-lib to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library with ng build coderamp-lib, go to the dist folder cd dist/coderamp-lib and run npm publish.

Running unit tests

Run ng test coderamp-lib to execute the unit tests via Karma.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.