@softheon/ng-workshop v5.0.1

NG-Workshop

NG-Workshop is a suite of modern Angular Components built on the Softheon Workshop Design System.

Quick Links

• Getting Started
• Components
• • SideNav
  • Scroll-Progress
  • Vertical-Multi-Stepper
  • Card-Grid
  • Header
  • Breadcrumbs
  • Footer
  • Multi-Stepper
• NPM Repository

Getting Started

Step 1: Install NG-Workshop

Install the package.

npm install --save @softheon/ng-workshop@latest

Include a link to Softheon Workshop UI in your index.html

<link rel="stylesheet" href="https://softheonworkshop.azureedge.net/beta-5/workshop.blue.min.css">

Include a link to Font Awesome 5 SVG with JS Library in your index.html

Example:

<script defer src="https://use.fontawesome.com/releases/v5.2.0/js/all.js" integrity="sha384-4oV5EgaV02iISL2ban6c/RmotsABqE4yZxZLcYMAdG7FAPsyHYAPpywE9PJo+Khy" crossorigin="anonymous"></script>

Add your components

import { MultiStepperModule } from '@softheon/ng-workshop';
@NgModule({
    ...
    imports: [MultiStepperModule]
    ...
})
export class MyAppModule { }

Components

SideNav

<sws-sidenav> is a component used to render left side navigation

API reference for NG-Workshop SideNav Component

Module.ts:

import { SideNavModule } from '@softheon/ng-workshop';

Add component to your html

EXAMPLE 1: Basic Template Skeleton

<sws-sidenav>
  <ng-container sidenav>
    <!-- Content Goes Here -->
  </ng-container>
</sws-sidenav>

EXAMPLE 2: SideNav with Content

<sws-sidenav>
  <ng-container sidenav>
    <!-- Content Goes Here -->
    <ul>
      <li><a routerLinkActive="active-link" routerLink="/welcome"><span sws-navigation_icon><i class="fas fa-home"></i></span>Home</a></li>
      <li><a routerLinkActive="active-link" routerLink="/contact"><span sws-navigation_icon><i class="fas fa-book"></i></span>Contact</a></li>
      <li><a routerLinkActive="active-link" routerLink="/about"><span sws-navigation_icon><i class="fas fa-address-card"></i></span>About Us </a></li>
    </ul>
  </ng-container>
</sws-sidenav>

EXAMPLE 3: SideNav with Content, Customizations, & Event Emitter

These settings will render the sidenav in the 'open' state by default (on desktop). And when the Menu button is clicked on the sidenav button, it will emit its boolean state.

<sws-sidenav [isNavCollapsed]="false" (isSideNavCollapsed)="log($event)">
  <ng-container sidenav>
    <!-- Content Goes Here -->
    <ul>
      <li><a routerLinkActive="active-link" routerLink="/welcome"><span sws-navigation_icon><i class="fas fa-home"></i></span>Home</a></li>
      <li><a routerLinkActive="active-link" routerLink="/contact"><span sws-navigation_icon><i class="fas fa-book"></i></span>Contact</a></li>
      <li><a routerLinkActive="active-link" routerLink="/about"><span sws-navigation_icon><i class="fas fa-address-card"></i></span>About Us </a></li>
    </ul>
  </ng-container>
</sws-sidenav>

Example Event Emitter Method

  public log(event) {
    console.log('e: ', event);
  }

EXAMPLE 4: SideNav with Content & Customizations

These settings will render the sidenav with a custom css class, a custom menu icon, and enable the overlay to appear when the sidenav is in the 'open' state, and to give the overlay a custom class (to only display on tablet and under screen sizes)

TIP: See the Workshop UI Documentation on customizing the side nav style.

<sws-sidenav [sideNavCustomClass]="'custom-header'" [menuIcon]="'fas fa-stream'" [enableOverlay]="true" [overlayCustomClass]="'visible-tablet'">
  <ng-container sidenav>
    <!-- Content Goes Here -->
    <ul>
      <li><a routerLinkActive="active-link" routerLink="/welcome"><span sws-navigation_icon><i class="fas fa-home"></i></span>Home</a></li>
      <li><a routerLinkActive="active-link" routerLink="/contact"><span sws-navigation_icon><i class="fas fa-book"></i></span>Contact</a></li>
      <li><a routerLinkActive="active-link" routerLink="/about"><span sws-navigation_icon><i class="fas fa-address-card"></i></span>About Us </a></li>
    </ul>
  </ng-container>
</sws-sidenav>

.custom-header {
  --nav-pos: fixed;
}

SideNav Input Configurations

SideNav Output Configurations

Scroll Progress

<sws-scroll-progress> is a component used to render a scroll progress indicator donut visualization

API reference for NG-Workshop Scroll Progress Component

Module.ts:

import { ScrollProgressModule } from '@softheon/ng-workshop';

Add component to your html

  <div style="position: fixed; bottom: 0; padding: 20px;">
      <sws-scroll-progress (scroll)="log($event)" (top)="log($event)" (bottom)="log($event)" (btnClick)="log($event)"></sws-scroll-progress>
  </div>

Example Event Emitter Method

  public log(event) {
    console.log('e: ', event);
  }

Example HTML with custom scroll event emitter:

<div id="test-container" (scroll)="watchScroll($event)" style="width: 400px; height: 800px; overflow: auto;">
  ...
</div>
<div style="position: fixed; bottom: 0" p-a-20>
  <sws-scroll-progress [useCustomElement]="true" [customScrollEvent]="customScrollEvent"></sws-scroll-progress>
</div>

  public watchScroll(event) {
    this.customScrollEvent = event;
  }

Scroll Progress Event Emitters (emits on Scroll)

Scroll Progress Event Emitters (emits on Scroll)

The Scroll Progress Indicator can be themed in the styles.css file as such:

:root {
  --sws-progress-arrow-color: #4b4e56;
  --sws-progress-indicator-color: #4b4e56; /* the progress ring color */
  --sws-progress-glow-color-start: 0 0 0 0 rgba(175, 175, 175, 0.9);
  --sws-progress-glow-color-end: 0 0 0 0 rgba(175, 175, 175, 0);
  --sws-progress-init-color: rgba(75, 78, 86, .18);  /* the progress ring's init color */
  --sws-progress-hover-color: rgba(75, 78, 86, .5);
  --sws-progress-focus-color: rgba(75, 78, 86, 1);
}

Note which variables are using rgba vs hex colors, and their alpha value.

Vertical-Multi-Stepper

Version 1 :

Version 2 :

<sws-multi-stepper-v> is a component used to render a progressive vertical multistepper.

API reference for NG-Workshop Vertical-Multi-Stepper Component

Module.ts:

import { MultiStepperVModule } from '@softheon/ng-workshop';

Component.ts:

import { IMultiStepper } from '@softheon/ng-workshop';

  public stepData: IMultiStepper = {
    menuText: 'MENU',
    steps: [
      {
        stepTitle: 'Checkout',
        stepUrl: './checkout',
        isSubStep: false,
        isCollapsible: true,
        stepGroupIndex: 0,
      },
      {
        stepTitle: 'Shipping',
        stepUrl: './checkout/shipping',
        isSubStep: true,
        stepGroupIndex: 0,
      },
      {
        stepTitle: 'Billing',
        stepUrl: './checkout/billing',
        isSubStep: true,
        stepGroupIndex: 0,
      },
      {
        stepTitle: 'Review',
        stepUrl: './checkout/review',
        isSubStep: true,
        stepGroupIndex: 0,
      },
      {
        stepTitle: 'Finish',
        stepUrl: './finished',
        isSubStep: false
      },
      {
        stepTitle: 'Thank you',
        stepExternalUrl: 'https://github.com/Softheon/NG-Workshop',
        isSubStep: false
      }
    ]
  };

Add component to your html

<sws-multi-stepper-v [stepData]="stepData"></sws-multi-stepper-v>

Example 2-column HTML with flexbox positioning:

<div flex-container-responsive>
   <div m-t-15>
     <sws-multi-stepper-v [stepData]="stepData"></sws-multi-stepper-v>
   </div>
   <div full-width m-a-10>
      <!-- Content Goes here -->
    </div>
</div>

Vertical Multistepper Input Configurations

Vertical Multistepper 'IStep' Properties

Vertical Multistepper 'IMultiStepper' Properties

Card-Grid

<sws-card-grid> is a component used to render a grid of cards styled content. Links are keyboard tab-able.

API reference for NG-Workshop Card-Grid Component

import { CardGridModule } from '@softheon/ng-workshop';

Add component to your html

<sws-card-grid [data]="cardContent" [cardSize]="cardSize"></sws-card-grid>

Pass the Card-Grid Data

  public cardContent = [
    {
      title: 'The Great Gatsby',
      subtitle: 'F. Scott Fitzgerald',
      desc: 'The Great Gatsby is a 1925 novel written by American author F. Scott Fitzgerald.',
      imgUrl: 'https://i.imgur.com/PBaOIbC.gif', // comment out if using fontIcon
      // fontIcon: 'fas fa-anchor', // uncomment if using imgUrl
      linkTitle: 'Learn More',
      link: './home'
    }
  ];

Configurations

The input configuration cardSize adjusts the card size and style.

Example Configuration (Optional):

  public cardSize = 'md';

Configuration Properties

Card Content Properties

Examples

Left to Right: 'lg', 'md', 'sm' (default)

Header

<sws-header> is a component used to render a navigation header. Entirely highly configurable, highly customizable, and keyboard tab-able.

API reference for NG-Workshop Header Component

Module.TS:

import { HeaderModule } from '@softheon/ng-workshop';

Component.ts:

import { IHeader, HeaderConfig } from '@softheon/ng-workshop';

Add component to your html

<sws-header [navData]="navigation" [config]="headerConfig"></sws-header>

Example with Search Event Emmitter :

<sws-header [navData]="navigation" [config]="headerConfig" (searchCriteria)="searchSomething($event)"></sws-header>

Example with ng-content (calling a function instead of changing router link):

  <sws-header [navData]="navigation" [config]="headerConfig" (searchCriteria)="searchSomething($event)">
    <!-- put your dynamic content here -->
    <div header full-height flex-container align-items-v m-l-15>
        <sws-breadcrumb [breadcrumbData]="breadcrumbData" [darkTheme]="true" [headerBreadcrumbs]="true"></sws-breadcrumb>
    </div>

    <div usermenu>
      <ul m-a-0 p-l-0>
        <li flex-container sws-nav-menu__list-item>
          <a
            href="javascript:void(0);"
            full-width
            sws-link
            p-a-15
            (click)="switchLanguage()">
            <span m-r-10> <i class="fas fa-chess"></i> </span> Switch
          </a>
        </li>
      </ul>
      <div p-a-10><i>This is custom html!</i></div>
    </div>

    <div leftmenu>
      <div p-a-10>This is also custom html!</div>
    </div>
    <!-- end dynamic content -->
  </sws-header>

The header can include 3 areas for custom content. Add the attribute header to the div for it to go in the header bar (to the right of the logo, and left of quicklinks). Add the attribute usermenu to the div for it to go in the user menu dropdown. Add the attribute leftmenu to the div for it to go in the left menu.

TIP: If you don't provide any navData it will display an empty header

Pass the Header Data

This will render the header in your workshop theme color with only the logo text "Navigation"

  public navigation: IHeader = {
    logoText: 'Navigation',
  };

  public headerConfig: HeaderConfig = new HeaderConfig();

  ngOnInit() {
    this.headerConfig.theme = 'theme';
  }

This will render the light colored header with only a logo image and quick links

  public navigation: IHeader = {
    logoImageUrl: 'https://softheonworkshopstorage.blob.core.windows.net/workshopcontainer/workshop-logo-anvil.svg',
    quickLinks: [
      {
        linkUrl: './about',
        linkText: 'About Us',
        fontAwesomeIcon: 'fas fa-chess'
      },
      {
        linkUrl: './solutions',
        linkText: 'Our Solutions',
        fontAwesomeIcon: 'fas fa-anchor'
      },
      {
        linkUrl: './contact',
        linkText: 'Contact Us',
        fontAwesomeIcon: 'fas fa-coffee'
      },
      {
        linkUrl: './blog',
        linkText: 'Blog'
      },
    ],
  };

  public headerConfig: HeaderConfig = new HeaderConfig();

  ngOnInit() {
    this.headerConfig.theme = 'light';
  }

This will render the dark colored header with only a text logo, searchbar, left menu navigation, and user menu

  public navigation: IHeader = {
    logoText: 'The Great Gatsby',
    userName: 'Jay Gatsby',
    userEmail: 'jay@thegreatgatsby.com',
    userMenuLinks: [
      {
        linkUrl: './home',
        linkText: 'Settings',
        fontAwesomeIcon: 'fas fa-anchor'
      },
      {
        linkUrl: './contact',
        linkText: 'Languages',
        fontAwesomeIcon: 'fas fa-chess'
      },
      {
        linkUrl: './about/ourstory',
        linkText: 'Logout'
      }
    ],
    headingText : 'External Links',
    menuLinks: [
      {
        linkUrl: './app1',
        linkText: 'Left Menu Link A',
      },
      {
        linkUrl: './app2',
        linkText: 'Left Menu Link B',

      },
      {
        linkUrl: './app3',
        linkText: 'Left Menu Link C'
      }
    ],
  };

  public headerConfig: HeaderConfig = new HeaderConfig();

  ngOnInit() {
    this.headerConfig.displayAppMenu = true;
    this.headerConfig.displaySearch = true;
    this.headerConfig.theme = 'theme';
  }

This will render the light theme header with only an svg image logo and left menu navigation (with custom section heading text)

  public navigation: IHeader = {
    logoImageUrl: 'http://tiny.cc/4oe4uy',
    logoLink: './customhomepage',
    appHeadingText: 'Additional Apps',
    headingText: 'External Links',
    applicationLinks: [
      {
        linkUrl: './home',
        linkText: 'Clarity',
        fontAwesomeIcon: 'fas fa-chess'
      },
      {
        linkUrl: './contact',
        linkText: 'Equity',
        fontAwesomeIcon: 'fas fa-chess'
      },
      {
        linkUrl: './about/ourstory',
        linkText: 'Remedy',
        fontAwesomeIcon: 'fas fa-chess'
      }
    ],
    menuLinks: [
      {
        externalLinkUrl: 'https://www.w3.org/TR/wai-aria-practices-1.1/examples/menu-button/menu-button-links.html',
        linkText: 'Left Menu Link A',
      },
      {
        linkUrl: './app2',
        linkText: 'Left Menu Link B',

      },
      {
        linkUrl: './contact',
        linkText: 'Left Menu Link C'
      }
    ],
  };

  public headerConfig: HeaderConfig = new HeaderConfig();

  ngOnInit() {
    this.headerConfig.displayAppMenu = true;
    this.headerConfig.theme = 'light';
  }

This will render the theme colored header with an external logo url, an external link in the header quick links, and subheader menu

  public navigation: IHeader = {
    logoImageUrl: 'http://tiny.cc/i5e4uy',
    externalLogoLink: 'https://www.softheon.com/Site/home',
    quickLinks: [
      {
        externalLinkUrl: 'https://www.softheon.com/Site/home',
        linkText: 'Contact',
      },
      {
        linkUrl: './blog',
        linkText: 'Blog'
      },
    ],
    subHeaderLinks: [
      {
        linkUrl: './page1',
        linkText: 'About Us',

      },
      {
        linkUrl: './page2',
        linkText: 'Careers'
      },
      {
        linkUrl: './page3',
        linkText: 'Learn More'
      },
      {
        linkUrl: './page4',
        linkText: 'Our Solutions'
      },
      {
        linkUrl: './page5',
        linkText: 'Media'
      },
      {
        linkUrl: './page6',
        linkText: 'News'
      },
    ],
  };

  public headerConfig: HeaderConfig = new HeaderConfig();

  ngOnInit() {
    this.headerConfig.displaySubNavMenu = true;
    this.headerConfig.theme = 'theme';
  }

When there are more than 4 quick links, the ui renders them under the header.

  public navigation: IHeader = {
    userName: 'Jay Gatsby',
    userEmail: 'jay@thegreatgatsby.com',
    logoImageUrl: 'http://tiny.cc/i5e4uy',
    quickLinks: [
      {
        externalLinkUrl: 'https://www.softheon.com/Site/home',
        linkText: 'Contact',
      },
      {
        linkUrl: './blog',
        linkText: 'Blog'
      },
      {
        linkUrl: './page1',
        linkText: 'About Us',

      },
      {
        linkUrl: './page2',
        linkText: 'Careers'
      },
      {
        linkUrl: './page3',
        linkText: 'Learn More'
      },
      {
        linkUrl: './page4',
        linkText: 'Our Solutions'
      },
      {
        linkUrl: './page5',
        linkText: 'Media'
      },
      {
        linkUrl: './page6',
        linkText: 'News'
      },
    ],
  };

  public headerConfig: HeaderConfig = new HeaderConfig();

  ngOnInit() {
    this.headerConfig.displaySearch = true;
    this.headerConfig.displayUserMenu = true;
  }

Configuration Properties

Header Content 'IHeader' Properties

TIP: All properties are optional TIP: All external links open in new tab as target="_blank"

Header Link 'ILink' Properties

TIP: *Either linkUrl or externalLinkUrl must be provided in an ILink object

Breadcrumbs

<sws-breadcrumbs> is a component used to render breadcrumbs from an object array

API reference for NG-Workshop Breadcrumb Component

Module.ts:

import { BreadcrumbModule } from '@softheon/ng-workshop';

Component.ts:

import { IBreadcrumb } from '@softheon/ng-workshop';

  public breadcrumbData: IBreadcrumb = {
    breadcrumb: [
      {
        linkText: 'Softheon',
        linkUrl: './home'
      },
      {
        linkText: 'Careers',
        linkUrl: './home/careers'
      },
      {
        linkText: 'Internships',
        linkUrl: './home/careers/internship'
      },
      {
        linkText: 'Software Engineering',
        linkUrl: './home/careers/internship/engineers'
      }
    ]
  };

Add component to your html

<sws-breadcrumb [breadcrumbData]="breadcrumbData"></sws-breadcrumb>

Example of breadcrumbs using dark theme

<sws-breadcrumb [breadcrumbData]="breadcrumbData" [darkTheme]="true" [maxBreadcrumbs]="4"></sws-breadcrumb>

Example of breadcrumbs in Header component

<sws-header [navData]="navigation" [config]="headerConfig">
  <!-- put your dynamic content here -->
  <div header full-height flex-container align-items-v m-l-15>
      <sws-breadcrumb [breadcrumbData]="breadcrumbData" [darkTheme]="true" [headerBreadcrumbs]="true"></sws-breadcrumb>
  </div>
</sws-header>

Breadcrumbs 'IBreadcrumb' Properties

Additional Breadcrumb Properties (Added to html as inputs)

Breadcrumbs Link 'ILink' Properties

TIP: *Either linkUrl or externalLinkUrl must be provided in an ILink object

Examples:

Footer

<sws-footer> is a component used to render a footer.

API reference for NG-Workshop Footer Component

Module.ts:

import { FooterModule } from '@softheon/ng-workshop';

Component.ts:

import { IFooter, FooterConfig } from '@softheon/ng-workshop';

public footer: IFooter = {
    contactPhoneNumber: '5555555555',
    copyrightText: '2018 Workshop, All Rights Reserved',
};

public footerConfig: FooterConfig = new FooterConfig();

ngOnInit() {
  this.footerConfig.theme = 'light';
  this.footerConfig.size = 'md';
}

Styles.css (or global CSS file):

  html, body {
      height: 100%;
  }

Add component to your html

<sws-footer [footerData]="footer" [config]="footerConfig"></sws-footer>

Example HTML with flexbox positioning:

<div flex-container-column flex-space-between full-height>
  <div>
    <!-- Content Goes here -->
   </div>
   <sws-footer [footerData]="footer" [config]="footerConfig"></sws-footer>
</div>

Footer Content 'IFooter' Properties

TIP: All properties are optional TIP: All external links open in new tab as target="_blank"

Navigation Header Link 'ILink' Properties

TIP: *Either linkUrl or externalLinkUrl must be provided in an ILink object

Configuration Properties

Examples:

Multi-Stepper

<sws-multi-stepper> is a component used to render a two-dimentional multi-step navbar, so developers can quickly create progress indicator and navigation wizards based on router outlet urls. The navigation is also accessibility-minded and keyboard tab-able.

API reference for NG-Workshop Multi-Stepper Component

import { MultiStepperModule } from '@softheon/ng-workshop';

Add component to your html

<sws-multi-stepper [config]=”configVar” [data]=”dataVar” (stepData)="customMethod($event)"></sws-multi-stepper>

The multistepper component receives two @inputs: one required data and one optional config.

On route change, the multistepper component also emits data. Below are the possible event emmiters to watch:

• currentStep - the current step (Root Page) object
• currentSubStep - the current sub-step (Page) object
• currentIndex - the current index (ie. for progress completion)
• stepData - includes all the above

Pass the Multi-Step Data

Example with Plain Text:

TIP: A minimum of two steps are REQUIRED for the navigation to display. Essentially a start and end node.

 public data = [
   { page: 'Welcome', url: './welcome' },
   {
     page: 'About Us',
     url: './about',
     subPages: [
      { page: 'Our Story', url: './about/ourstory' },
      { page: 'Frequently Asked Questions', url: './about/faq' },
      { page: 'Meet the Team', url: './about/team' }
    ]
   },
    {
     page: 'Projects',
     url: './project',
     subPages: [
      { page: 'Project A', url: './project/projecta' },
      { page: 'Project B', url: './project/projectb' },
      { page: 'Project C', url: './project/projectc' }
    ]
   },
   { page: 'Contact Us', url: './contact' }
 ];

Example with Translation Keys Text (using ngx-translate):

  this.translateService.onLangChange.subscribe((event: LangChangeEvent) => {
    return this.data = [
      { page: this.translateService.instant('nav.step1'), url: './step1' },
      {
        page: this.translateService.instant('nav.step2'),
        url: './step2',
        subPages: [
          { page: this.translateService.instant('nav.part1'), url: './step2/page1' },
          { page: this.translateService.instant('nav.part2'), url: './step2/page2' },
          { page: this.translateService.instant('nav.part3'), url: './step2/page3' }
        ]
      },
      { page: this.translateService.instant('nav.step3'), url: './step3' }
    ];
  });

TIP 1: If you are using ngx-translate, wrap the component in an ngIf

TIP 2: We recommend putting the multistepper above your <router-outlet></router-outlet> html.

<div *ngIf="data">
    <sws-multi-stepper [data]="data" [config]="config" (stepData)="currentStep($event)"></sws-multi-stepper>
</div>

Configurations

Example Configuration (Optional):

  public config = {
    dir: 'v',
    markStepsCompleted: false,
    navTxt: 'Check Out This Sweet Nav!'
  };

Configuration Properties

Examples