@my-ul/porcelain
v1.0.2
Published
Porcelain for Angular is a library of durable, beautiful components for building Angular 2+ applications with the UL style guide in mind.
Downloads
5
Readme
Welcome to Porcelain for Angular
Porcelain for Angular is a library of durable, beautiful components for building Angular 2+ applications with the UL style guide in mind.
Getting Started
Installation
One Line
npm install @my-ul/porcelain moment @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/angular-fontawesome
One at a time
npm install --save moment
npm install --save @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/angular-fontawesome
npm install --save @my-ul/porcelain
Simple Refiner
Import the module
import { SimpleRefinerModule } from '@my-ul/porcelain';
@NgModule({
declarations: [
AppComponent
],
imports: [
SimpleRefinerModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
Set up your refiner with simple Option definitions
The easiest way to initialize a Simple Refiner is with an object of [value: string] => label
definitions...
import { Component } from '@angular/core';
import { SimpleRefiner } from '@my-ul/porcelain';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss']
})
export class AppComponent {
title = 'porcelain-examples';
stateRefiner = new SimpleRefiner({
slug: 'stateRefiner',
title: 'Simple Refiner Demo',
options: {
'AL': "Alabama",
'AK': "Alaska",
'WY': "Wyoming"
}
});
handleStateChange(refinerSlug, value) {
// this function will be called when the refiner
// value changes.
}
}
Set up your refiner with Full Option definitions
Full options are easy to generate in a loop, and make it easy to have full control over the function and presentation of your Simple Refiner.
This example shows the use of a SimpleOption
dictionary that uses state populations as the badge
value.
stateRefiner = new SimpleRefiner({
slug: 'stateRefiner',
title: 'Simple Refiner Demo',
options: {
options: {
'AL': new SimpleOption({ badge: 4888949, label: 'Alabama', slug: 'AL' }),
'AK': new SimpleOption({ badge: 738068, label: 'Alaska', slug: 'AK' }),
'AZ': new SimpleOption({ badge: 7123898, label: 'Arizona', slug: 'AZ' }),
// ...
'WY': new SimpleOption({ badge: 573720, label: 'Wyoming', slug: 'WY' })
}
}
});
Use in your template
<!-- component.html -->
<porcelain-simple-refiner
[refiner]="stateRefiner"
(onRefinerChange)="handleStateChange($event)"
></porcelain-simple-refiner>
Outputs
onRefinerChange($event)
Provide a function that will be called when the refiner's value changes. The function is called once on initialization.
Inputs
showCount: number
By default, the Simple Refiner will show the first five options. You can increase or decrease this value as necessary.
<porcelain-simple-refiner
[refiner]="stateRefiner"
(onRefinerChange)="handleStateChange($event)"
[showCount]="10"
></porcelain-simple-refiner>
isOpen: boolean
You can control the default presentation of the refiner. Set to true
to show the refiner open with the first showCount
number of options displayed.
Set to false
to show the refiner in the collapsed state.
Defaults to true
<porcelain-simple-refiner
[refiner]="stateRefiner"
(onRefinerChange)="handleStateChange($event)"
[showCount]="10"
[isOpen]="false"
></porcelain-simple-refiner>
isExpanded: boolean
Controls the expanded state of the refiner. Set to true
to show all options on initial render.
Defaults to false
<porcelain-simple-refiner
[refiner]="stateRefiner"
(onRefinerChange)="handleStateChange($event)"
[showCount]="10"
[isExpanded]="false"
></porcelain-simple-refiner>
Date Refiner
Date refiners let users interactively refine a date range.
To use the Date Refiner component, import its module, DateRefinerModule
...
import { DateRefinerModule } from '@my-ul/porcelain';
@NgModule({
declarations: [
AppComponent
],
imports: [
DateRefinerModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
Simple
This uses a pre-built definition of date ranges that can be easily used and reused.
let dateRefiner = new DateRefiner({
slug: 'simpleDateRefiner',
title: 'Simple Date Refiner'
});
Full
The IDateRefiner
interface requires slug
, label
, getFrom
and getTo
to be defined.
The Custom Range
If you define a DateOption
for the custom
slug, a date range picker will be shown automatically. If you need to use the custom
slug for something else, but do not want the range picker to appear, you must use a different slug, such as _custom
.
The getTo
/getFrom
functions will be provided with YYYY-MM-DD
formatted strings. Use these strings to generate the date values.
The Date-Generating Functions getFrom
and getTo
The getFrom(fromString)
and getTo(toString)
functions should return a JavaScript Date
or null. Each function takes a string, which is set to the current YYYY-MM-DD
value of the corresponding date value.
If you use moment
to create dates (recommended, but not required), don't forget to call momentInstance.toDate()
.
The functions should return null
if the range described lacks an upper or lower bound. For example an option for "Before 2000" will have a getFrom
returning null
and a getTo
returning a date for January 1, 2000.
import moment from 'moment';
let fullDateRefiner = new DateRefiner({
slug: 'modified',
title: 'Modified...',
options: {
pre2000: new DateOption({
slug: 'pre2000',
label: 'Before 2000',
getFrom: (fromString: string) => null,
// To midnight Jan 1, 2000
getTo: (toString: string) => new Date(2000, 1, 1, 0, 0, 0, 0)
}),
custom: new DateOption({
slug: 'custom',
label: 'Custom Range',
getFrom: (fromString: string) => moment(fromString, "YYYY-MM-DD").toDate(),
getTo: (toString: string) => moment(toString, "YYYY-MM-DD").toDate()
})
}
});