From 5790fa5990594a778c02f2fbed562963376d61bf Mon Sep 17 00:00:00 2001 From: Jeremy Wilken Date: Fri, 15 Feb 2019 10:17:36 -0600 Subject: [PATCH] [docs] toggle switch documentation updates (#3103) Signed-off-by: Jeremy Wilken --- .../demos/checkboxes/checkboxes.demo.html | 4 +- .../documentation/demos/toggles/ng/basic.html | 1 + .../demos/toggles/ng/disabled.html | 12 + .../demos/toggles/ng/helpers.html | 13 + .../demos/toggles/ng/inline.html | 13 + .../documentation/demos/toggles/ng/label.html | 8 + .../demos/toggles/toggles-example.demo.html | 60 ---- .../demos/toggles/toggles-example.demo.ts | 70 ---- .../demos/toggles/toggles.demo.html | 333 ++++++++++++++++-- .../demos/toggles/toggles.demo.module.ts | 5 +- .../demos/toggles/toggles.demo.ts | 38 +- .../documentation/demos/toggles/ui/basic.html | 4 + .../demos/toggles/ui/disabled.html | 21 ++ .../documentation/demos/toggles/ui/error.html | 21 ++ .../documentation/demos/toggles/ui/full.html | 21 ++ .../demos/toggles/ui/inline.html | 21 ++ 16 files changed, 478 insertions(+), 167 deletions(-) create mode 100644 src/website/src/app/documentation/demos/toggles/ng/basic.html create mode 100644 src/website/src/app/documentation/demos/toggles/ng/disabled.html create mode 100644 src/website/src/app/documentation/demos/toggles/ng/helpers.html create mode 100644 src/website/src/app/documentation/demos/toggles/ng/inline.html create mode 100644 src/website/src/app/documentation/demos/toggles/ng/label.html delete mode 100644 src/website/src/app/documentation/demos/toggles/toggles-example.demo.html delete mode 100644 src/website/src/app/documentation/demos/toggles/toggles-example.demo.ts create mode 100644 src/website/src/app/documentation/demos/toggles/ui/basic.html create mode 100644 src/website/src/app/documentation/demos/toggles/ui/disabled.html create mode 100644 src/website/src/app/documentation/demos/toggles/ui/error.html create mode 100644 src/website/src/app/documentation/demos/toggles/ui/full.html create mode 100644 src/website/src/app/documentation/demos/toggles/ui/inline.html diff --git a/src/website/src/app/documentation/demos/checkboxes/checkboxes.demo.html b/src/website/src/app/documentation/demos/checkboxes/checkboxes.demo.html index 1a7eb5ae0c..701058c653 100644 --- a/src/website/src/app/documentation/demos/checkboxes/checkboxes.demo.html +++ b/src/website/src/app/documentation/demos/checkboxes/checkboxes.demo.html @@ -26,7 +26,7 @@

Basic checkbox button

Labels

-

For anything beyond a standalone checkbox button, you'll need to wrap your checkboxs with the ClrCheckboxWrapper +

For anything beyond a standalone checkbox button, you'll need to wrap your checkboxes with the ClrCheckboxWrapper component when you include a label. This manages the label and display of the checkbox button for you.

@@ -51,7 +51,7 @@

Helper and error messages

component. The checkbox button container tracks the the validations placed on a checkbox button, such as required or even custom built validators in Angular. Under the hood, it looks at the NgControl - values to determine the control validitity, and display the helper text or error message accordingly.

+ values to determine the control validity, and display the helper text or error message accordingly.

Note: the validation in this example only displays an error after you focus and leave focus without selecting a value. The easiest way to do this is to highlight the text in this paragraph, and hit tab a few diff --git a/src/website/src/app/documentation/demos/toggles/ng/basic.html b/src/website/src/app/documentation/demos/toggles/ng/basic.html new file mode 100644 index 0000000000..9b9fe57186 --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ng/basic.html @@ -0,0 +1 @@ + diff --git a/src/website/src/app/documentation/demos/toggles/ng/disabled.html b/src/website/src/app/documentation/demos/toggles/ng/disabled.html new file mode 100644 index 0000000000..a9c4d50eac --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ng/disabled.html @@ -0,0 +1,12 @@ + + + + + + + + + + + Helper text + diff --git a/src/website/src/app/documentation/demos/toggles/ng/helpers.html b/src/website/src/app/documentation/demos/toggles/ng/helpers.html new file mode 100644 index 0000000000..250f312f94 --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ng/helpers.html @@ -0,0 +1,13 @@ + + + + + + + + + + + Helper text + This field is required! + diff --git a/src/website/src/app/documentation/demos/toggles/ng/inline.html b/src/website/src/app/documentation/demos/toggles/ng/inline.html new file mode 100644 index 0000000000..a7fad82f2d --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ng/inline.html @@ -0,0 +1,13 @@ + + + + + + + + + + + Helper text + This field is required! + diff --git a/src/website/src/app/documentation/demos/toggles/ng/label.html b/src/website/src/app/documentation/demos/toggles/ng/label.html new file mode 100644 index 0000000000..a8209f546c --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ng/label.html @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/src/website/src/app/documentation/demos/toggles/toggles-example.demo.html b/src/website/src/app/documentation/demos/toggles/toggles-example.demo.html deleted file mode 100644 index 2998500ca1..0000000000 --- a/src/website/src/app/documentation/demos/toggles/toggles-example.demo.html +++ /dev/null @@ -1,60 +0,0 @@ - - -

-
-
- -
- - -
-
- - -
-
- - -
-
-
-
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
-
-
-
- -
- - -
-
- - -
-
-
-
- diff --git a/src/website/src/app/documentation/demos/toggles/toggles-example.demo.ts b/src/website/src/app/documentation/demos/toggles/toggles-example.demo.ts deleted file mode 100644 index 6b39328521..0000000000 --- a/src/website/src/app/documentation/demos/toggles/toggles-example.demo.ts +++ /dev/null @@ -1,70 +0,0 @@ -/* - * Copyright (c) 2016-2018 VMware, Inc. All Rights Reserved. - * This software is released under MIT license. - * The full license information can be found in LICENSE in the root directory of this project. - */ -import { Component } from '@angular/core'; - -const EXAMPLE = ` -
-
-
- -
- - -
-
- - -
-
- - -
-
-
-
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
-
-
-
- -
- - -
-
- - -
-
-
-
-`; - -@Component({ - selector: 'clr-toggles-example-demo', - templateUrl: './toggles-example.demo.html', -}) -export class TogglesExampleDemo { - example = EXAMPLE; -} diff --git a/src/website/src/app/documentation/demos/toggles/toggles.demo.html b/src/website/src/app/documentation/demos/toggles/toggles.demo.html index d26e63a1b2..46bc5f4fb8 100644 --- a/src/website/src/app/documentation/demos/toggles/toggles.demo.html +++ b/src/website/src/app/documentation/demos/toggles/toggles.demo.html @@ -4,51 +4,320 @@ ~ The full license information can be found in LICENSE in the root directory of this project. --> +
+
+ With toggle switches, users can select the one or off state of an option. +
-
-
A - toggle switch changes on and off states of a single setting.
+

Angular Toggle Switch Component

-
-

To create a toggle switch, wrap an input[type="checkbox"] - element and a label element in a block-level wrapper - (like a div) with the .toggle-switch - classname. To use a toggle without any label, keep the label - tag empty. The default toggle is gray in its “off” state and green in - its “on” state. The user can change states by clicking on either the toggle or its - accompanying label. You can move the label to the right side by adding the right-label class.

+

If you are using Angular, the recommended approach is to always use the ClrToggle + directive on your toggle switches to help manage the form control. By using ClrToggle, + you'll automatically be able to leverage built in validation, helper text, and layout features in forms.

-

Disabled Toggles

+

Basic checkbox button

-

To disable a toggle switch, add the disabled attribute to the - toggle’s checkbox input. When disabled, the toggle appears - gray. The user cannot change the state of the toggle. And the present state is reflected - in both the location of the toggle switch and by the “on” state being a slightly darker - gray.

+

While it is possible to create a toggle switch without a label, the cases are rare. However, it is possible + by just adding clrToggle to your checkbox button to wire up the + directive. Notice, it is necessary to add type="checkbox".

- +

+ + + +

+ + + +

Labels

+ +

For anything beyond a standalone checkbox button, you'll need to wrap your toggle switches with the ClrToggleWrapper + component when you include a label. This manages the label and display of the toggle switch for you. +

+ +

+ + + + + + + + + + +

+ + + +

Helper and error messages

+ +

To leverage helper and validation messages, you'll need to wrap all of the toggle switches inside of a ClrToggleContainer + component. The toggle switch container tracks the the validations placed on a toggle switch, such as required + or even custom built validators in Angular. Under the hood, it looks at the NgControl + values to determine the control validity, and display the helper text or error message accordingly.

+ +

Note: the validation in this example only displays an error after you focus and leave focus without + selecting a value. The easiest way to do this is to highlight the text in this paragraph, and hit tab a few + times to change the focus.

+ +

+ + + + + + + + + + + + Helper text + This field is required! + + +

+ + + +

Inline toggle switches

+ +

Toggle switches can be placed inline by default by adding the clrInline directive + to your toggle switch container elements. The toggle switches will wrap if there is not enough space.

+ +

+ + + + + + + + + + + + Helper text + This field is required! + + +

+ + + +

Disabled toggle switches

+ +

A toggle switch can be disabled by simply putting the disabled attribute on the + checkbox input. This does require the toggle switch to be inside of a toggle switch container. Also, for groups of + toggle switches you have to put the disabled attribute on the last checkbox input and cannot disable individual ones, + as Angular doesn't have support to disable individual checkboxes in a group.

+ +

+ + + + + + + + + + + + Helper text + + +

+ + + + + + +

CSS Toggle Switch Component

+ +

Toggle switches can be used without Angular, but without some of the automatic interactivity. If you intend to + create + your own components, here are the basic features you'll need to build out.

+ +

Basic toggle switch button

+ +

This is the minimal markup needed to style the checkbox button control by wrapping it with the an element with + the + clr-toggle-wrapper class. You must then put the input first, then the label + like you see below (the CSS selectors are specific about this ordering). You'll want to tie the input and + label together by providing an id for the label to connect. Ensure you add the clr-toggle + class to the checkbox input as well.

+ +

+ +
+ + +
+ +

+ + + +

Full input display

+ +

Each form control has a .clr-form-control wrapper, as well as a specific DOM + structure necessary to layout the form control as desired. This works with all layout options as well + without needing to change the DOM structure in any way.

+ +

+ +
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + Helper Text +
+
+
+ +

+ + + +

Error state

+ +

To signify an error state, you need to add the .clr-error class to the .clr-control-container element. This will show the .clr-validate-icon + and turn the .clr-subtext message to red. If you have helper text that needs + to change to error content, you'll have to handle the hiding and showing of that content inside of the + .clr-subtext element.

+ +

+ +
+ +
+
+ + +
+
+ + +
+
+ +
+
+ + Error message +
+
+
-
-

Usage

+

-

Use a toggle switch when you need the sole options of “on” and “off.”

+ -

Toggle switches take up less space than an “on/off” radio button group and communicate their intended - purpose better than a checkbox - that toggles functionality.

+

Inline toggle switches

-

Toggle States

+

Toggle switches can be placed inline by default by adding the clr-control-inline directive + to your checkbox container. The toggle switches will wrap if there is not enough space.

-

Toggle switches do not include “ON” and “OFF” text because these states are clearly implied.

+

The subtext content, the icon and subtext messages, also must be wrapped in a clr-subtext-wrapper + element so it can properly layout in all layout variations. If you omit this, the validation icon and text may appear in the wrong place.

-

Label

+

-

The label should clearly describe the setting. Although Clarity supports a toggle - switch without a label, use this approach only if the purpose of the control is made - clear elsewhere, for example, in a group label or section header.

+
+ +
+
+ + +
+
+ + +
+
+ +
-
+
+ + Helper text +
+ + + +

+ + +

Disabled toggle switches

+ +

In order to disable toggle switches, you'll add the disabled attribute on the checkbox input and + putting the clr-form-control-disabled class onto the form control wrapper. This + helps setup the correct styling for the labels and other aspects of the form control when it is disabled.

+ +

+ +
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + Helper text +
+
+
+ +

+ + + + +
+

Usage

+ +

Use a toggle switch when you need the sole options of “on” and “off.”

+ +

Toggle switches take up less space than an “on/off” radio button group and communicate their intended purpose better than a checkbox that toggles functionality.

+ +

Toggle States

+ +

Toggle switches do not include “ON” and “OFF” text because these states are clearly implied.

+ +

Label

+ +

The label should clearly describe the setting. Although Clarity supports a toggle switch without a label, use this approach only if the purpose of the control is made clear elsewhere, for example, in a group label or section header.

+
+
+ diff --git a/src/website/src/app/documentation/demos/toggles/toggles.demo.module.ts b/src/website/src/app/documentation/demos/toggles/toggles.demo.module.ts index 9a8df9cc13..0fbe45d41e 100644 --- a/src/website/src/app/documentation/demos/toggles/toggles.demo.module.ts +++ b/src/website/src/app/documentation/demos/toggles/toggles.demo.module.ts @@ -8,20 +8,21 @@ import { CommonModule } from '@angular/common'; import { ClarityModule } from '@clr/angular'; import { TogglesDemo } from './toggles.demo'; -import { TogglesExampleDemo } from './toggles-example.demo'; import { DocWrapperModule } from '../_doc-wrapper/doc-wrapper.module'; import { RouterModule } from '@angular/router'; import { UtilsModule } from '../../../utils/utils.module'; +import { FormsModule } from '@angular/forms'; @NgModule({ imports: [ CommonModule, ClarityModule, DocWrapperModule, + FormsModule, RouterModule.forChild([{ path: '', component: TogglesDemo }]), UtilsModule, ], - declarations: [TogglesExampleDemo, TogglesDemo], + declarations: [TogglesDemo], exports: [TogglesDemo], }) export class TogglesDemoModule {} diff --git a/src/website/src/app/documentation/demos/toggles/toggles.demo.ts b/src/website/src/app/documentation/demos/toggles/toggles.demo.ts index 3805be4582..280faa5af8 100644 --- a/src/website/src/app/documentation/demos/toggles/toggles.demo.ts +++ b/src/website/src/app/documentation/demos/toggles/toggles.demo.ts @@ -6,8 +6,19 @@ import { Component } from '@angular/core'; import { ClarityDocComponent } from '../clarity-doc'; +import * as UiBasic from './ui/basic.html'; +import * as UiFull from './ui/full.html'; +import * as UiError from './ui/error.html'; +import * as UiInline from './ui/inline.html'; +import * as UiDisabled from './ui/disabled.html'; + +import * as NgBasic from './ng/basic.html'; +import * as NgLabel from './ng/label.html'; +import * as NgHelpers from './ng/helpers.html'; +import * as NgInline from './ng/inline.html'; +import * as NgDisabled from './ng/disabled.html'; + @Component({ - selector: 'clr-toggles-demo', templateUrl: './toggles.demo.html', host: { '[class.content-area]': 'true', @@ -18,4 +29,29 @@ export class TogglesDemo extends ClarityDocComponent { constructor() { super('toggle-switches'); } + + exampleOne = { + one: false, + two: false, + }; + exampleTwo = { + one: false, + two: false, + }; + exampleThree = { + one: false, + two: false, + }; + + uiBasic: any = UiBasic; + uiFull: any = UiFull; + uiError: any = UiError; + uiInline: any = UiInline; + uiDisabled: any = UiDisabled; + + ngBasic: any = NgBasic; + ngLabel: any = NgLabel; + ngHelpers: any = NgHelpers; + ngInline: any = NgInline; + ngDisabled: any = NgDisabled; } diff --git a/src/website/src/app/documentation/demos/toggles/ui/basic.html b/src/website/src/app/documentation/demos/toggles/ui/basic.html new file mode 100644 index 0000000000..4c602aec41 --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ui/basic.html @@ -0,0 +1,4 @@ +
+ + +
diff --git a/src/website/src/app/documentation/demos/toggles/ui/disabled.html b/src/website/src/app/documentation/demos/toggles/ui/disabled.html new file mode 100644 index 0000000000..1fc50f99be --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ui/disabled.html @@ -0,0 +1,21 @@ +
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + Helper text +
+
+
diff --git a/src/website/src/app/documentation/demos/toggles/ui/error.html b/src/website/src/app/documentation/demos/toggles/ui/error.html new file mode 100644 index 0000000000..c92e0fee5c --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ui/error.html @@ -0,0 +1,21 @@ +
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + Error message +
+
+
diff --git a/src/website/src/app/documentation/demos/toggles/ui/full.html b/src/website/src/app/documentation/demos/toggles/ui/full.html new file mode 100644 index 0000000000..66a0ec013e --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ui/full.html @@ -0,0 +1,21 @@ +
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + Helper Text +
+
+
diff --git a/src/website/src/app/documentation/demos/toggles/ui/inline.html b/src/website/src/app/documentation/demos/toggles/ui/inline.html new file mode 100644 index 0000000000..77a27163b1 --- /dev/null +++ b/src/website/src/app/documentation/demos/toggles/ui/inline.html @@ -0,0 +1,21 @@ +
+ +
+
+ + +
+
+ + +
+
+ + +
+
+ + Helper Text +
+
+