@cloud-creatures/cc-angular-ui v17.1.2

CC Angular UI

UI Library for use with Angular 2. With this library you can create highly customisable page quickly.

Instalation

This UI Library has Angular Material Dependencies and also Angular Server Data Dependency. First install Angular Server Data:

npm i @cloud-creatures/angular-server-data

and then install CC Angular UI:

npm i @cloud-creatures/cc-angular-ui

Components

This library is composed of 4 main components:

• CC Material Layout
• CC Material Page Header
• CC Material Datatable
• CC Form UI

CC Material Layout

Set Up

Import CcMaterialLayoutModule and add it into your module imports:

import { CcMaterialLayoutModule } from '@cloud-creatures/cc-angular-ui/cc-material-layout';

Usage

<cc-main-layout sideTitle="Angular UI">
  <div *ccSidenav>
    <!-- ...Side Navigation Contents Here -->
  </div>

  <div ccLayoutHeaderButton>
    <!-- ...Header Buttons Here -->
  </div>

  <router-outlet></router-outlet>

  <div ccLayoutFooter>
    <!-- ...Footer Contents Here -->
  </div>
</cc-main-layout>

cc-sidenav-item is expected to be inside the *ccSidenav directive:

...

  <div *ccSidenav>
    <cc-sidenav-item header expanded>
      Menu Header
      <cc-sidenav-item link="/menu_1" icon="data_object" pageTitle="Menu 1 Page Title"> Menu 1 </cc-sidenav-item>
      <cc-sidenav-item link="/menu_2" icon="data_object" pageTitle="Menu 2 Page Title"> Menu 2 </cc-sidenav-item>
      <cc-sidenav-item icon="data_object"> 
        Nested 1
        <cc-sidenav-item icon="data_object"> Menu 1 </cc-sidenav-item>
        <cc-sidenav-item icon="data_object"> 
          Nested 2
          <cc-sidenav-item icon="data_object"> Menu 1 </cc-sidenav-item>
          <cc-sidenav-item icon="data_object"> Menu 2 </cc-sidenav-item>
        </cc-sidenav-item>
      </cc-sidenav-item>
    </cc-sidenav-item>
  </div>

...

Parameters

cc-main-layout

cc-sidenav-item

CC Material Page Header

Set Up

Import CcMaterialPageHeaderModule and add it into your module imports:

import { CcMaterialPageHeaderModule } from '@cloud-creatures/cc-angular-ui/cc-material-page-header';

Usage

<cc-page-header title="Example Page" subTitle="Welcome to demo" backgroundUrl="/assets/images/mountains.png">
  <cc-breadcrumb>
    <cc-breadcrumb-item link="/" usePreviousParams>Home</cc-breadcrumb-item>
    <cc-breadcrumb-item>Examples</cc-breadcrumb-item>
  </cc-breadcrumb>

  <button mat-flat-button color="primary" routerLink="detail" ccPageHeaderButton>See Detail</button>
</cc-page-header>

Parameters

cc-page-header

cc-breadcrumb-item

CC Material Datatable

The Datatable is made to work with data that is fetched and paginated from the server. All you have to do is to pass the serverData function that fetches the data from the server based on the queries, and return the data as observable.

Set Up

Import CcMaterialDatatableModule and add it into your module imports:

import { CcMaterialDatatableModule } from '@cloud-creatures/cc-angular-ui/cc-material-datatable';

Usage

<cc-datatable [serverData]="serverDataFn" >
  
  <!-- datatable plugins here -->

  <!-- datatable column definitions here -->
</cc-datatable>

ServerData function

It is important to note that the server data function MUST be defined with the fat arrow syntax for correct "this" scope () => { ... }

serverDataFn = (query: any) => {
  // query passed in is the search text, paginations and also all the query data from the plugins

  return of({
    data: [ ... ] , // this is the actual data array that will be passed in as the datasource
    extra: {
      length: 10 // extra.length is the total item for the query that is important for the pagination to work
    }
  })
}

the query object passed into the server data function contains the search text, paginations, sort, and all other data from datatable plugins.

query.search // search text
query.pagination = {
  page: 0, // current page number, starting from 0,
  size: 10, // item per-page
}

Column Definitions

The datatable uses Angular Material table component internally. The column definitions also follow the exact same way (described here) with a few extra attributes and directives added.

<ng-container matColumnDef="name">
  <th mat-header-cell *matHeaderCellDef cc-datatable-sortable> Name </th>
  <td mat-cell *matCellDef="let element"> {{element.name}} </td>
</ng-container>

<ng-container matColumnDef="description" hideable colvisLabel="Description">
  <th mat-header-cell *matHeaderCellDef> Description </th>
  <td mat-cell *matCellDef="let element"> {{element.description}} </td>
</ng-container>

<ng-container matColumnDef="address" hideable hidden colvisLabel="Address">
  <th mat-header-cell *matHeaderCellDef> Address </th>
  <td mat-cell *matCellDef="let element"> {{element.address}} </td>
</ng-container>

Plugins

cc-datatable-sortable

add cc-datatable-sortable directive to *matHeaderCellDef as per Column Definitions to enable header click sorting.

  ...
    <th mat-header-cell *matHeaderCellDef cc-datatable-sortable> Name </th>
  ...

When sorting is active it will be passed into the Server Data Function via the query parameter:

query.sort = {
  sort: string, // the sorted column name
  direction: 'asc' | 'desc' // the direction of the sort
}

Column visibility (Colvis)

Colvis plugin will add a colvis button on the table toolbar that enable user to hide and show the columns.
add hideable and colvisLabel attribute to matColumnDef definition as per Column Definitions:

<ng-container matColumnDef="address" hideable colvisLabel="Address">
  ... column definition
</ng-container>

add ccDatatableColvis plugin to the datatable:

  <cc-datatable>
    ...
    <div ccDatatableColvis></div>
    ...
    
    <!-- datatable column definitions here -->
    ...
  </cc-datatable>

Search By

Search By plugin will add a dropdown of searchable items beside the search bar.

add ccDatatableSearchBy plugin to the datatable:

  <cc-datatable>
    ...
    <div ccDatatableSearchBy>
      <ng-container *ccDatatableSearchByItem="'name'">Name</ng-container>
      <ng-container *ccDatatableSearchByItem="'address'">Address</ng-container>
      <ng-container *ccDatatableSearchByItem="'email'">Email</ng-container>
    </div>
    ...
    
    <!-- datatable column definitions here -->
    ...
  </cc-datatable>

ccDatatableSearchBy parameter:

• multiple: boolean
  add this attribute to ccDatatableSearchBy directive to set whether the selection is multiple or single selection

   <div ccDatatableSearchBy [multiple]="false" > // single selection

this plugin when active will add following data to the query object passed into server data function:

query.searchBy

the value will be an array of the searchByItem defined name e.g. "name", "email". for single selection it will still be array but contain only 1 item.

Filter

Filter plugin will add a filter dropdown on datatable toolbar. You can then add any filter you want and use the passed in handleChange function to update the datatable

  <div *ccDatatableFilter="let query = query; let handleChange = handleChange" class="dense-component">
    
    <input type="text" (ngModelChange)="handleChange($event, 'testFilterItem')" [ngModel]="query?.['testFilterItem']">
  </div>

everytime the handleChange function is called with the passed in filter params, it will update the datatable and passed in the filter data in the query data parameter in server data function

query.filter

// e.g: 
query.filter.testFilterItem // this will be passed if the testFilterItem example above input ngModel value is changed

Filter Chips

This plugin is to be used in conjuction with the filter plugin above.

  <cc-datatable>
    ...
    <div ccDatatableFilterChips>
      <div *ccDatatableFilterChipsItem="let key = key; let value = value">
        <b>{{key}}</b> : {{value}}
      </div>
    </div>
    ...
    
    <!-- datatable column definitions here -->
    ...
  </cc-datatable>
  

whenever a filter value is added to datatable it will show up on the toolbar as a chip that user can un-apply one by one. if no *ccDatatableFilterChipsItem component is added, it will generate with default value and look.

  <div ccDatatableFilterChips> </div> // this also works, it will be default with the text: <filterKey> : <filterValue>

Sort By

This plugin will add a "Sort By" button on the datatable toolbar that contains listed sortable items. if the item in the list also exists in the column definition, it will also update the header click sort and vice versa.

  <cc-datatable>
    ...
      <div ccDatatableSortBy>
        <div *ccDatatableSortByItem="'name'">Name</div>
        <div *ccDatatableSortByItem="'address'">Address</div>
        <div *ccDatatableSortByItem="'email'">Email</div>
      </div>
    ...
    
    <!-- datatable column definitions here -->
    ...
  </cc-datatable>

this plugin when active will add following data to the query object passed into server data function:

query.sort = {
  sort: string, // the sorted column name
  direction: 'asc' | 'desc' // the direction of the sort
}

Tab

This plugin will add tabs to the datatable

  <cc-datatable>
    ...
      <div ccDatatableTab>
        <div *ccDatatableTabItem="'tab1'">Tab 1</div>
        <div *ccDatatableTabItem="'tab2'">Tab 2</div>
        <div *ccDatatableTabItem="'tab3'">Tab 3</div>
      </div>
    ...
    
    <!-- datatable column definitions here -->
    ...
  </cc-datatable>

ccDatatableTab parameter:

• position: 'top' | 'above-table' | 'left' | 'right'
  default to above-table, this parameter will determine where the tab will be displayed

   <div ccDatatableTab position="left" >

  top will display the tabs above the toolbar, left & right will be left or right inside the toolbar, while above-table will be under the toolbar above the actual table.

this plugin when active will add following data to the query object passed into server data function:

query.tab 

the value will be the selected tab name defined in the *ccDatatableTabItem. e.g "tab2".

Parameters

CC Form UI

Set Up

Import CcFormUIModule and add it into your module imports:

import { CcFormUIModule } from '@cloud-creatures/cc-angular-ui/cc-form-ui';

Usage

 Work In Progress