us-cbp / ngx-cbp-theme

Angular 5/6/7 library based on the CBP Theme

ngx-cbp-theme

Deprecated

This package is deprecated and no long maintained since Angular 7.

Angular native artifacts for consuming CBP Theme for Angular 5/6/7/next applications.

---

---

Goals

• Provides abstraction for CBP Theme so that other Angular CBP applications do not have to repeat this gap-bridging between CBP Theme and Angular Material.
• Deliver styling from CBP Theme to other CBP Angular applications so that CBP Theme can evolve and styling changes are delivered with simple upgrade in most cases.
• Provides for progression from Bootstrap to Material specifications as CBP Theme evolves. (This should cause shrinking of this library.)

Target Applications

• Apps that must comply with US CBP Style Guide
• Apps that are using latest Angular
• Apps that will use Angular Material Angular/Material
• Apps that use SCSS.

Library Development Goals and Guidelines

• Consumption of this library should require minimal setup i.e. most complexity and difficulties must be fought and absorbed in here keeping angular-cli spirit.
• Must inherit certain (see styles below) styles from US-CBP/cbp-theme
• Must not mix any other UI libraries than Angular/Material
• Expose SCSS artifacts.
• Provide angular native components only when styling overriding is not an option OR consuming a material component requires more effort to comply with CBP Style Guide.
• Provide angular native component ony when Angular/Material does not have equivalent component.
• Styles
  • Styles should be prefixed with cbp and mat when overriding.
  • Markups should not use any other namespaces than the ones specified.
  • Must expose individual styles for further customization.

Getting Started - How To Use

Note: For Windows users we recommend git-bash shell. Also check the node engine version.

Use @angular/cli global install version matching the version inside package.json

• Install angular-cli globally making sure we use same version as we have in @angular/cli inside package.json.

Quick Start

• For Quick Start up you could just clone my-app and npm install however we recommend you to understand what is happening in here and follow the following steps.

Start From Scratch

• For new apps follow angular-cli and create your application with styles = SCSS. Minimal e.g.

  ng new my-app --style scss --skip-install

• Ensure polyfills.ts is correct by following instructions in your src/polyfills.ts to enable all IE11 and web-animations-js polyfills.

• Ensure that you have exact version matches as per package.json. This is because angular-cli has more relaxed versioning scheme which promotes early adoption which can be problematic with Material/RxJS/angular-flex combination.

• Install Material, CDK, FlexLayout

  $ npm install @angular/material@~6  @angular/cdk@^6 --save

• Ensure that it builds and runs correctly i.e. ng start runs fine.

• Stop any of running processes/scripts against your project and then run:

  $ npm install ngx-cbp-theme --save

• In your styles.scss add

  @import '~ngx-cbp-theme/styles/ngx-cbp-theme';

• In your angular.json add to your build options for @angular-devkit/build-angular:browser

  "stylePreprocessorOptions": {
    "includePaths": ["./node_modules"]
  },
  

• Implement required services:

  ngx-cbp-theme requires implementation of some services provided by the consuming application since those services are beyond the scope of theme.

  Ideally these will be provided by other projects hosted in the enterprise. Please check common framework team or other Angular teams withing CBP.

  However for the sake of this exercise we will provide implementation of some of these services (CBPUserService, CBPApplicationsService) before we start our application.

  Since this is just a guide we will create my-user.service (to fake User) and my-applications.service (to fake basic set of applications for header menu).

  Lets go ahead and create those using angular-cli.

  ng g s my-user
  ng g s my-applications

  Modify MyUserService to implement CBPUserService from ngx-cbp-theme. Make sure we implement all the abstract methods.

  Similarly MyApplicationsService must implement CBPApplicationsService and its methods.

  Both class declaration signature looks as below (implementation omitted for brevity).

  // inside my-user-service.ts
  import {CBPUserService, CBPUser} from 'ngx-cbp-theme';
  @Injectable()
  export class MyUserService extends CBPUserService { 
  ...
  }
  // inside my-applications-service.ts
  
  import {CBPApplicationsService} from 'ngx-cbp-theme';
  @Injectable()
  export class MyApplicationsService extends CBPApplicationsService { 
  ...

• Import following minimal modules in your AppModule (app.module.ts):

  import {
      CBPRootModule, 
      CBPHeaderModule, 
      CBPAppHeaderModule,     // this is optional 
      CBP_USER_SERVICE,           // must be provided to fetch CBP user logged in to display user name on CBP Header
      CBP_APPLICATIONS_SERVICE    // must be provided to get CBP applications (recent) for Applications menu on the CBP Header
  } from 'ngx-cbp-theme' ;

  Import in @NgModule

    imports: [
        BrowserModule,
        CBPRootModule,
        CBPAppHeaderModule
      ],

  Provide implementation for these services like USER_SERVICE and APPLICATIONS_SERVICE by implementing respective interfaces and declare providers in AppModule's @NgModule as follows:-

    providers: [
      { provide: CBP_USER_SERVICE,          useClass: MyUserService },
      { provide: CBP_APPLICATIONS_SERVICE,  useClass: MyApplicationsService }
    ]

Full code is available here in another github repo my-app. Checkout the progression by loking at the commit history as these steps.

• Markup Requirement

Your app.component.html should be changed to following minimal structure:-

<cbp-root layout="'fluid'">
  <cbp-header></cbp-header>
  <cbp-app-header>
    <cbp-app-title>
      <h1 class="app-title"> Product<small> create</small></h1>
    </cbp-app-title>
  </cbp-app-header>
  <div class="app-content">
    <p>My markup here...</p>
  </div>
</cbp-root>

Customizing

Customizable cbp-header:- e.g. shows cbpAppsMenuExclude is excluded, cbp-feedback-link has custom action, cbp-user-menu has additional menu item Preference.

     <cbp-header [cbpAppsMenuExclude]="true">
         <cbp-feedback-link (click)="myFeedbackAction()"></cbp-feedback-link>
         <cbp-user-menu>
             <div class="mat-menu-item" (click)="myPreferences()" cbp-user-menu-item>Preferences</div>
         </cbp-user-menu>
     </cbp-header>

Contributing

We welcome contributions, please see our Contribution Policy

To get started developing, see contributing readme here.

License

Please refer to CBP Open Source License

ngx-cbp-theme's Issues

Upgrade & Lock versions

marble-mustache released a few days ago containing md-select changes and angular upgrade to > 4.4.3. This is a breaking change.

CBP Notification isOpen should return true for default new notifications

isClosedInitially should default to false

options.isClosedInitially = options.isClosedInitially === true ? true : false;

bootstrap vs material

Has any thought been given to using bootstrap as the base vs material? Essentially, instead of using material2, use ngx-bootstrap? While I think the material stuff is probably nicer, it seems like cbp-theme is a bootstrap theme with changes for material. By using Material as the base, it's hard to reuse much of the cbp-theme at all. You have to redo it to make it work for material. I wonder if we used bootsrap as the base, if we'd be able to use more of the base cbp-theme.

Once cbp-theme moved to a material theme, we could then make the same change, and hopefully again be able to reuse most of the cbp-theme. Thoughts?

Consuming Applications to set the current application

Applications Menu on cbp-header displays the current application.

This can be registered with the service at boot or module initialization.

Ability to subscribe to currentApp when the current app is detected

Provide observable property in CBPApplicationsServices to get currentApp setting events rather than subscribing to the whole applicationsData.

Make CBP Header click action configurable

When you click on CBP Header the click action should be configurable.

Upgrade to Angular and Material to latest RC version 5

Need to catch up to version 5 to avoid being behind and difficulty catching up.

App Search input box flushed with the menu panel on left.

Input is flushed on the left menu. The entire field can be inside a mat-menu-item with left/right margins.

Reuse .switch classes from cbp-theme

Currently we copied the switch class as shown below.

ngx-cbp-theme/src/app/buttons/cbp-toggle-switch/cbp-toggle-switch.component.scss

Lines 2 to 9 in 1e488c2

	// copied from https://raw.githubusercontent.com/US-CBP/cbp-theme/master/app/styles/custom/_forms.scss
	.switch {
	padding-left: 64px;
	overflow: hidden;
	position: relative;
	> input {

We need to reuse it from cbp-theme which requires a PR for cbp-theme to extract that class out of forms.

page left & right padding

cbp-theme v1.8.x onwards started putting gutter which need to be inherited

Disabled Form Controls - Label to match with cbp-style-guide

As shown below

cbp-notifications not emitting isOpen() when closed

No longer works with Angular CLI

I'm getting a ton of "Cannot find module '@angular/core'" messages. Is it possible that this is caused by the library being built on a release candidate version? Tried cloning my-app and got similar errors.

App Menu, User Menu remains open when CBP Header shrinks

When header shrinks the menus should close.

Toggle Buttons too light - seems like disabled

Make the text darker.

mat-button-toggle class global override.

material tabindex imported incorrectly causing build failures downstream

Incorrect import @angular/material/core/typings/common-behaviors/tabindex' causing issues on downstream applications.

Module not found: Error: Can't resolve '@angular/material/core/typings/common-behaviors/tabindex' in 'C:\Users\yyy\projs\ief\ief-mobile\node_modules\ngx-cbp-theme'chunk {
inlineresolve '@angular/material/core/typings/common-behaviors/tabindex' in 'C:\Users\yy\projs\ief\ief-mobile\node_modules\ngx-cbp-theme'
} inline.bundle.js, inline.bundle.js.map  Parsed request is a module (inline) 5.83 kB 
[entry] [rendered]  using description file: C:\Users\yy\projs\ief\ief-mobile\node_modules\ngx-cbp-theme\package.json (relative path: .)

Use <header> for cbp-header

Can cbp-header be changed from an md-toolbar to a simple header tag? Seems like it would be more semantic as well as accessible to use the standard html5 tag. Is md-toolbar providing some sort of functionality?

Simplify header

Should some of the component features of the header be abstracted out so that users can include only the ones necessary? For instance, If I don't want the Feedback link, then I simply don't include it. Some like the following?

<cbp-header>
    <cbp-apps-menu></cbp-apps-menu>
    <cbp-feedback-link></cbp-feedback-link>
    <cbp-user-menu></cbp-user-menu>
</cbp-header>

The header itself would only provide the branding and the toggle button.

CBPNotificationsService flat barrel broken

Not able to do this:

import {CBPNotificationsService} from 'ngx-cbp-theme';

cbp-header scrollshrink should only at 50 offset instead of any scrollups

Is accordian necessary?

Do we need an accordion component, or would it be better to rely on the HTML5 details/summary tags? Polyfills exist for IE support. Seems like simplicity and accessibility, using the HTML5 tags would be preferable.

Develop CBP Theme Notifications

Need a service to display notifications as per systems notifications https://us-cbp.github.io/cbp-style-guide/docs/components/alerts.html

The service should be able to project a custom notification template into a notifications area.

Refactor common functionality between cbp-header and app-header into common component `cbp-toolbar`

Both headers has few styles that are common.
We can extract this out into a single cbp-toolbar component.
If we do we should inherit from md-toolbar. See #8

Adding Applications Menu Link - link "See All Available Apps..."

As shown below

Need e2e tests for each component

e2e tests are barely testing much. We need the following at the minimum:-

• e2e for Applications Menu
• e2e test for cbp-header - high level - responsiveness.

AOT broken for consuming apps

AOT broken for consuming applications.

In example my-app

ng build --aot  

failed with bunch of errors complaining about 'undefined' value in the imports.

Toggle Switches component as per cbp-theme

Material Toggle Switches look way off when look at a form. We need a new simple toggle switch where we can customize the label.. The ON and OFF contents and that provides easier model changes while providing the same styling.

Make <cbp-header> header accessible wherever necessary

Make header accessible.

Handle SSO or User Already logged in

Currently we expect user to click on Login on the Header however as a step towards getting SSO ready we need some provisions.

applications menu items overflow issue

Recent/Favorites Application names as menu items are children of mat-menu-item and not benefiting from overflow handlers.

e.g.

Something like below should work. Other option is ensure these contents are inside with icon.
See https://plnkr.co/edit/WLpgR3LVZNDq1MFBktaq?p=preview

.cbp-applications-link {
   overflow: inherit;
   text-overflow: inherit;
}

System Notification - Auto Close progress

Progress bar as below