Skip to content

Commit

Permalink
Merge pull request #247 from mobi/select_box_documentation
Browse files Browse the repository at this point in the history 
Add go-select documentation
  • Loading branch information
@grahamhency
grahamhency authored Oct 7, 2019
2 parents 5ec2d5b + ffb0101 commit 94da5b7
Show file tree
Hide file tree
Showing 5 changed files with 377 additions and 0 deletions.
249 changes: 249 additions & 0 deletions ...pp/features/ui-kit/components/form-docs/components/select-docs/select-docs.component.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,249 @@
<section class="go-container">
<app-form-control-docs
class="go-column go-column--100"
></app-form-control-docs>
<go-card id="form-select-control" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Control</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
As with most of the form components, the only <code class="code-block--inline">@Input</code>
required of the text area component is a <code class="code-block--inline">FormControl</code>.
The FormControl can be passed in via the <code class="code-block--inline">[control]</code>
attribute on the &lt;go-text-area&gt; component.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select [control]="select1"></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select1Code"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
<go-card id="form-select-label" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Label</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
All form components include an <code class="code-block--inline">@Input() label: string;</code>
that can be used to add a label to the textarea components.
In addition to displaying an HTML label, the text passed
in via the <code class="code-block--inline">[label]</code>
attribute is used to generate a unique ID to associate the
label with the textarea. If no label is passed in, a generic,
but still unique ID will be generated.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select
[control]="select2"
label="Candy"
></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select2Code"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
<go-card id="form-select-key" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Key</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
As stated above the label attribute is used to generate a
unique ID to associate the label with the select. As this might
not be desired, the <code class="code-block--inline">@Input() key: string;</code>
can be used to configure the ID attribute of the textarea directly.
Anything passed into the component via the <code class="code-block--inline">[key]</code>
attribute will be used to both assign the ID to the select and
associate the label with the textarea.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select
[control]="select3"
label="Favorite Candy"
key="your-favorite-candy"
></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select3Code"
class="code-block--no-bottom-margin"
></code>
</div>
<div class="go-column go-column--100">
<h2 class="go-heading-6 go-heading--underlined">Example Output</h2>
<p class="go-body-copy">
Notice in the below example output that the <code class="code-block--inline">key</code> has been assigned
to both the <code class="code-block--inline">id</code> attribute on
the textarea and the <code class="code-block--inline">for</code> attribute
on the label.
</p>
<code
[highlight]="select3KeyCode"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
<go-card id="form-select-hints" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Hints</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
Form hints exist to help give more information about the
selects they are attached to. The <code class="code-block--inline">@Input() key: Array&lt;string&gt;</code>
can be used to pass in an array of hints to the select component.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select
[control]="select4"
label="Favorite Candy"
[hints]="hints"
></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select4HintsCode"
class="code-block--no-bottom-margin"
></code>
<code
[highlight]="select4Code"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
<go-card id="form-select-errors" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Errors</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
FormControls all have a <a class="go-link" href="https://angular.io/api/forms/AbstractControl#setErrors">consistent way of setting errors</a>
via the <code class="code-block--inline">setErrors()</code> function.
All goponents use this API to display errors on our components, but the
data needs to be displayed in a specific structure.
</p>
<p class="go-body-copy">
By default the error type is set to "Error", however this can be
overridden as shown below.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select
[control]="select5"
label="Favorite Candy"
></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select5Code"
class="code-block--no-bottom-margin"
></code>
<code
[highlight]="select5ErrorsCode"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
<go-card id="form-select-errors" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Items</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
Selects are pretty useless without options to choose from. The <code class="code-block--inline">@Input() items: any[];</code>
binding allows an array of options to be passed in. This array can either be an array of strings or objects. If it's
an array of objects you will also need to pass both a <code class="code-block--inline">@Input() bindLabel: string</code> and a
<code class="code-block--inline">@Input() bindValue: string</code> attribute. The <code class="code-block--inline">bindLabel</code> attribute
is used to tell the select what we should show for each option while the <code class="code-block--inline">bindValue</code> attribute
is used to tell teh select what value we want to save for each option. Both should reference a key on each object in the item array.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select
bindLabel="name"
bindValue="value"
[control]="select6"
[items]="items"
label="Favorite Candy"
></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select6Code"
class="code-block--no-bottom-margin"
></code>
<code
[highlight]="select6ItemCode"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
<go-card id="form-select-hints" class="go-column go-column--100">
<ng-container go-card-header>
<h1 class="go-heading-5">Component Multiple</h1>
</ng-container>
<ng-container go-card-content>
<p class="go-body-copy">
Sometimes we may want to be able to select multiple things. We can achieve this throught the
<code class="code-block--inline">@Input() multiple: boolean = false;</code> binding. Setting <code class="code-block--inline">multiple</code>
to true will turn the select into a multi select and will save an array of values instead of a single value.
</p>
<div class="go-container">
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">View</h2>
<go-select
bindLabel="name"
bindValue="value"
[control]="select7"
[items]="items"
[multiple]="true"
label="Favorite Candy"
></go-select>
</div>
<div class="go-column go-column--50">
<h2 class="go-heading-6 go-heading--underlined">Code</h2>
<code
[highlight]="select7Code"
class="code-block--no-bottom-margin"
></code>
</div>
</div>
</ng-container>
</go-card>
</section>
121 changes: 121 additions & 0 deletions .../app/features/ui-kit/components/form-docs/components/select-docs/select-docs.component.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
import { Component, OnInit } from '@angular/core';
import { FormControl } from '@angular/forms';

@Component({
templateUrl: './select-docs.component.html'
})
export class SelectDocsComponent implements OnInit {
items: any = [
{ value: 1, name: 'Reeses' },
{ value: 2, name: 'Mints' }
];
select1: FormControl = new FormControl('');
select2: FormControl = new FormControl('');
select3: FormControl = new FormControl('');
select4: FormControl = new FormControl('');
select5: FormControl = new FormControl('');
select6: FormControl = new FormControl('');
select7: FormControl = new FormControl('');

hints: Array<string> = ['please select you favorite candy'];

select1Code: string = `
<go-select
[control]="select"
></go-select>
`;

select2Code: string = `
<go-select
[control]="select"
label="Favorite Candy"
></go-select>
`;

select3Code: string = `
<go-select
[control]="select"
label="Favorite Candy"
key="your-favorite-candy"
></go-select>
`;

select3KeyCode: string = `
<label for="your-favorite-candy">Favorite Candy</label>
<ng-select ng-reflect-label-for-id="your-favorite-candy"></ng-select>
`;

select4Code: string = `
<go-select
[control]="select"
label="Favorite Candy"
></go-select>
`;

select4HintsCode: string = `
hints: Array<string> = [
'please select you favorite candy'
];
`;

select5Code: string = `
<go-select
[control]="select"
label="Favorite Candy"
></go-select>
`;

select5ErrorsCode: string = `
this.select5.setErrors([
{
message: 'An error occurred.'
},
{
type: 'Required',
message: 'This is a required input.'
}
]);
`;

select6Code: string = `
<go-select
bindLabel="name"
bindValue="value"
[control]="select"
[items]="items"
label="Favorite Candy"
></go-select>
`;

select6ItemCode: string = `
items = [
{ value: 1, name: 'Reeses' },
{ value: 2, name: 'Mints' }
];
`;

select7Code: string = `
<go-select
bindLabel="name"
bindValue="value"
[control]="select"
[items]="items"
[multiple]="true"
label="Favorite Candy"
></go-select>
`;

ngOnInit(): void {
setTimeout((): void => {
this.select5.setErrors([
{
message: 'An error occurred.'
},
{
type: 'Required',
message: 'This is a required input.'
}
]);
});
}
}
1 change: 1 addition & 0 deletions projects/go-style-guide/src/app/features/ui-kit/components/form-docs/form-docs.component.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ export class FormDocsComponent {
{ route: './', routeTitle: 'Overview' },
{ route: './datepicker', routeTitle: 'Datepicker' },
{ route: './input', routeTitle: 'Input' },
{ route: './select', routeTitle: 'Select' },
{ route: './textarea', routeTitle: 'Text Area' }
]
}
Expand Down
2 changes: 2 additions & 0 deletions projects/go-style-guide/src/app/features/ui-kit/routes/ui-kit-routing.module.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import { LayoutNavComponent } from '../components/layout-docs/components/layout-
import { LayoutHeaderComponent } from '../components/layout-docs/components/layout-header/layout-header.component';
import { LayoutSearchComponent } from '../components/layout-docs/components/layout-search/layout-search.component';
import { LayoutExampleComponent } from '../components/layout-docs/components/layout-example/layout-example.component';
import { SelectDocsComponent } from '../components/form-docs/components/select-docs/select-docs.component';
import { TextAreaDocsComponent } from '../components/form-docs/components/text-area-docs/text-area-docs.component';
import { TableSelectionComponent } from '../components/table-docs/components/table-selection/table-selection.component';
import { TableActionsDocsComponent } from '../components/table-docs/components/table-actions-docs/table-actions-docs.component';
Expand All @@ -45,6 +46,7 @@ const routes: Routes = [
{ path: '', component: FormsOverviewComponent },
{ path: 'datepicker', component: DatepickerDocsComponent },
{ path: 'input', component: InputDocsComponent },
{ path: 'select', component: SelectDocsComponent },
{ path: 'textarea', component: TextAreaDocsComponent }
]},
{ path: 'ui-kit/layout', component: LayoutDocsComponent, children: [
Expand Down
Loading

0 comments on commit 94da5b7

Please sign in to comment.