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

| Name | Type | Description | |--------------|-----------------------|------------------------------------------------------------------------------------| | sideTitle | string or TemplateRef | Title for header section of the SideNav | | title | string or TemplateRef | Title for the main Top Navigation Bar | | menuIcon | string | Icon for the Hamburger Button that opens the Sidenav, pass in material icon values | | sidenavWidth | number | Width of the SideNav menu. |

cc-sidenav-item

| Name | Type | Description | |----------------|-----------------------|---------------------------------------------------------------------------------| | isExternalLink | boolean | Set to true if the link points to external pages. | | icon | string or TemplateRef | Material Icon value or custom template ref | | link | string | Internal router link | | target | string | pass in target _blank to open in new tab | | exact | boolean | set to true for Route exact link | | pageTitle | string | This value is going to be displayed on top bar if this item is currently active | | header | | add this attribute to set the item as a header item | | expanded | | add this attribute to by default expand header items or items with child navs |

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

| Name | Type | Description | |---------------|-----------------------|---------------------------------------------| | title | string or TemplateRef | Title section of the header | | subTitle | string or TemplateRef | Subtitle section of the header | | backgroundUrl | string | URL for background image of the page header |

cc-breadcrumb-item

| Name | Type | Description | |-------------------|---------|-------------------------------------------------------------------| | link | string | Router link | | usePreviousParams | boolean | set this attribute to preserve previous page's params to the link |

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

| Name | Type | Description | |---------------------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | serverData | function | The main function that will be called whenever the datatable need to reload and fetch new data. | | search | boolean | set to false if you want to hide search bar. true by default. | | autoSearch | boolean | true by default. if set to false it will not auto search, a search button will be display instead | | searchDelay | number | if autosearch is on, this attribute determine time in milliseconds before start searching after user typed in search bar. | | searchWidth | number | string | if number: width of search bar in pixel, otherwise passed in as string e.g. '250px' | | searchButtonLabel | string | Set the label of the search button if autoSearch is false | | searchInputStyle | 'default' | 'outlined' | if value is outlined, it will show border around search input. | | searchPlaceholder | string | Set the placeholder of the search bar input. | | searchPosition | 'left' | 'right' | Set the position of the search bar on the toolbar. | | pageSizeOptions | [number] | array of number determining the value of the number of item per-page drop-down selection. | | defaultPageSize | [number] | set the default page size of the pagination | | type | "full-page" | "contained" | full page is default, contained if the datatable will be displayed e.g. inside a popup or another component. | | stickyToolbar | boolean | default to true, set false to disable sticky | | toolbarStickyOffset | number | set the value of the sticky offset from the top of the screen for the sticky toolbar | | displayColumn | [string] | array of column names that determine which column will be displayed regardless of the colvis setting. use this to control column display. | | paginationPosition | 'left' | 'right' | set the position of the pagination control on the table footer | | pagination | 'none' | 'server' | 'client' | either disable pagination, or user either server or client pagination. Client side pagination will not call serverDataFn to refresh. (default to server) | | (rowClicked) | Output | Event emitted when a row is clicked, passed in the row data as $event | | hoverable | boolean | add this attribute in conjuction with rowClicked attr above for clickable row. | | useRouteParams | boolean | if set to true, the datatable will modify the url parameters to persist the query object between refresh. useful for bookmarking. | | pluginPosition | 'left' | 'right' | Set the position of the plugins button on the toolbar. |

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