From af0fb05ae59480765040520c8aee7c7f4ad0d098 Mon Sep 17 00:00:00 2001 From: featherless Date: Tue, 1 May 2018 21:29:27 -0400 Subject: [PATCH] [Snackbar] Split the documentation into separate articles and run the readme generator. (#3627) --- components/Snackbar/.vars | 1 + components/Snackbar/README.md | 171 ++++++++++++++---- components/Snackbar/docs/README.md | 56 ++++++ components/Snackbar/docs/color-theming.md | 13 +- ...pical-use-display-a-message-with-action.md | 31 ++++ .../docs/typical-use-display-a-message.md | 19 ++ .../Snackbar/docs/typography-theming.md | 13 +- 7 files changed, 240 insertions(+), 64 deletions(-) create mode 100644 components/Snackbar/docs/README.md create mode 100644 components/Snackbar/docs/typical-use-display-a-message-with-action.md create mode 100644 components/Snackbar/docs/typical-use-display-a-message.md diff --git a/components/Snackbar/.vars b/components/Snackbar/.vars index 4cc60ad0a6c..761efc610fb 100644 --- a/components/Snackbar/.vars +++ b/components/Snackbar/.vars @@ -5,3 +5,4 @@ root_path=/catalog/snackbars icon_id=toast color_themer_api=MDCSnackbarColorThemer typography_themer_api=MDCSnackbarTypographyThemer +short_description=Snackbars provide brief feedback about an operation through a message at the bottom of the screen. diff --git a/components/Snackbar/README.md b/components/Snackbar/README.md index 4c39a9e7f6a..742eb643bef 100644 --- a/components/Snackbar/README.md +++ b/components/Snackbar/README.md @@ -1,12 +1,15 @@ + + # Snackbar
@@ -17,37 +20,32 @@ Snackbars provide brief feedback about an operation through a message at the bot Snackbars contain up to two lines of text directly related to the operation performed. They may contain a text action, but no icons. -## Design & API Documentation +## Design & API documentation -## Extensions +## Related components -- - - - -## Installation - -### Installation with CocoaPods - -To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`: - -``` -pod 'MaterialComponents/Snackbar' -``` - - -Then, run the following command: - -```bash -pod install -``` +## Table of contents + +- [Overview](#overview) + - [Snackbar Manager and Message](#snackbar-manager-and-message) + - [Suspending and Resuming Display of Messages](#suspending-and-resuming-display-of-messages) +- [Installation](#installation) + - [Installation with CocoaPods](#installation-with-cocoapods) + - [Importing](#importing) +- [Usage](#usage) + - [Typical use: display a message](#typical-use-display-a-message) + - [Typical use: display a message with an action](#typical-use-display-a-message-with-an-action) +- [Extensions](#extensions) + - [Color Theming](#color-theming) + - [Typography Theming](#typography-theming) - - - @@ -66,19 +64,28 @@ messages are suspended the manager provides a suspension token that the client m messages are suspended. When the client releases the suspension token or calls the manager's resume method with the suspension token, then messages will resume being displayed. -- - - +## Installation -## Usage + -Displaying a snackbar requires using two classes: MDCSnackbarManager and MDCSnackbarMessage. -First, create an instance of MDCSnackbarMessage and provide a string to display to the user. Next, -pass the MDCSnackbarMessage to the MDCSnackbarManager with the static showMessage method. This will -automatically construct an MDCSnackbarMessageView and appropriate overlay views so the snackbar is -visible to the user. +### Installation with CocoaPods + +Add the following to your `Podfile`: + +```bash +pod 'MaterialComponents/Snackbar' +``` + + +Then, run the following command: + +```bash +pod install +``` ### Importing -Before using Snackbar, you'll need to import it: +To import the component: #### Swift @@ -87,16 +94,24 @@ import MaterialComponents.MaterialSnackbar ``` #### Objective-C + ```objc #import "MaterialSnackbar.h" ``` -- - - -## Examples +## Usage + +Displaying a snackbar requires using two classes: MDCSnackbarManager and MDCSnackbarMessage. +First, create an instance of MDCSnackbarMessage and provide a string to display to the user. Next, +pass the MDCSnackbarMessage to the MDCSnackbarManager with the static showMessage method. This will +automatically construct an MDCSnackbarMessageView and appropriate overlay views so the snackbar is +visible to the user. + + -### Display a Snackbar Message +### Typical use: display a message #### Swift @@ -116,7 +131,9 @@ message.text = @"How much wood would a woodchuck chuck if a woodchuck could chuc ``` -### Display a Snackbar Message with an Action + + +### Typical use: display a message with an action #### Swift @@ -148,10 +165,84 @@ message.action = action; ``` -- - - -## Related Components +## Extensions + + + +### Color Theming + +You can theme an snackbar with your app's color scheme using the ColorThemer extension. + +You must first add the Color Themer extension to your project: + +```bash +pod 'MaterialComponents/Snackbar+Extensions/ColorThemer' +``` + + +#### Swift +```swift +// Step 1: Import the ColorThemer extension +import MaterialComponents.MaterialSnackbar_ColorThemer + +// Step 2: Create or get a color scheme +let colorScheme = MDCSemanticColorScheme() + +// Step 3: Apply the color scheme to your component +MDCSnackbarColorThemer.applySemanticColorScheme(colorScheme) +``` + +#### Objective-C + +```objc +// Step 1: Import the ColorThemer extension +#import "MaterialSnackbar+ColorThemer.h" + +// Step 2: Create or get a color scheme +id colorScheme = [[MDCSemanticColorScheme alloc] init]; + +// Step 3: Apply the color scheme to your component +[MDCSnackbarColorThemer applySemanticColorScheme:colorScheme]; +``` + + + + +### Typography Theming + +You can theme an snackbar with your app's typography scheme using the TypographyThemer extension. + +You must first add the Typography Themer extension to your project: + +```bash +pod 'MaterialComponents/Snackbar+Extensions/TypographyThemer' +``` + + +#### Swift +```swift +// Step 1: Import the TypographyThemer extension +import MaterialComponents.MaterialSnackbar_TypographyThemer + +// Step 2: Create or get a typography scheme +let typographyScheme = MDCTypographyScheme() + +// Step 3: Apply the typography scheme to your component +MDCSnackbarTypographyThemer.applyTypographyScheme(typographyScheme) +``` + +#### Objective-C + +```objc +// Step 1: Import the TypographyThemer extension +#import "MaterialSnackbar+TypographyThemer.h" + +// Step 2: Create or get a typography scheme +id typographyScheme = [[MDCTypographyScheme alloc] init]; + +// Step 3: Apply the typography scheme to your component +[MDCSnackbarTypographyThemer applyTypographyScheme:colorScheme]; +``` + - diff --git a/components/Snackbar/docs/README.md b/components/Snackbar/docs/README.md new file mode 100644 index 00000000000..8913bf2263a --- /dev/null +++ b/components/Snackbar/docs/README.md @@ -0,0 +1,56 @@ +# Snackbar + +
+ Snackbar +
+ +Snackbars provide brief feedback about an operation through a message at the bottom of the screen. +Snackbars contain up to two lines of text directly related to the operation performed. They may +contain a text action, but no icons. + +## Design & API documentation + +* [Material Design guidelines: Snackbars](https://material.io/go/design-snackbars) + +## Related components + +* [OverlayWindow](../../OverlayWindow) + + + +- - - + +## Overview + +### Snackbar Manager and Message + +Snackbar is comprised of two classes: MDCSnackbarManager and MDCSnackbarMessage. Snackbar messages +contain text to be displayed to a user. Messages are passed to the manager. The manager decides when +it is appropriate to show a message to the user. + +### Suspending and Resuming Display of Messages + +Snackbar manager can be instructed to suspend and resume displaying messages as needed. When +messages are suspended the manager provides a suspension token that the client must keep as long as +messages are suspended. When the client releases the suspension token or calls the manager's resume +method with the suspension token, then messages will resume being displayed. + +## Installation + +- [Typical installation](../../../docs/component-installation.md) + +## Usage + +Displaying a snackbar requires using two classes: MDCSnackbarManager and MDCSnackbarMessage. +First, create an instance of MDCSnackbarMessage and provide a string to display to the user. Next, +pass the MDCSnackbarMessage to the MDCSnackbarManager with the static showMessage method. This will +automatically construct an MDCSnackbarMessageView and appropriate overlay views so the snackbar is +visible to the user. + +- [Typical use: display a message](typical-use-display-a-message.md) +- [Typical use: display a message with an action](typical-use-display-a-message-with-action.md) + +## Extensions + +- [Color Theming](color-theming.md) +- [Typography Theming](typography-theming.md) diff --git a/components/Snackbar/docs/color-theming.md b/components/Snackbar/docs/color-theming.md index 00bbf9d6b65..7544360d94d 100644 --- a/components/Snackbar/docs/color-theming.md +++ b/components/Snackbar/docs/color-theming.md @@ -1,13 +1,4 @@ - - -# Snackbar Color Theming +### Color Theming You can theme an snackbar with your app's color scheme using the ColorThemer extension. @@ -17,8 +8,6 @@ You must first add the Color Themer extension to your project: pod 'MaterialComponents/Snackbar+Extensions/ColorThemer' ``` -## Example code - #### Swift ```swift diff --git a/components/Snackbar/docs/typical-use-display-a-message-with-action.md b/components/Snackbar/docs/typical-use-display-a-message-with-action.md new file mode 100644 index 00000000000..f08ff70f937 --- /dev/null +++ b/components/Snackbar/docs/typical-use-display-a-message-with-action.md @@ -0,0 +1,31 @@ +### Typical use: display a message with an action + + +#### Swift + +```swift +let action = MDCSnackbarMessageAction() +let actionHandler = {() in + let answerMessage = MDCSnackbarMessage() + answerMessage.text = "Fascinating" + MDCSnackbarManager.show(answerMessage) +} +action.handler = actionHandler +action.title = "OK" +message.action = action +``` + +#### Objective-C + +```objc +MDCSnackbarMessageAction *action = [[MDCSnackbarMessageAction alloc] init]; +void (^actionHandler)() = ^() { + MDCSnackbarMessage *answerMessage = [[MDCSnackbarMessage alloc] init]; + answerMessage.text = @"A lot"; + [MDCSnackbarManager showMessage:answerMessage]; +}; +action.handler = actionHandler; +action.title = @"Answer"; +message.action = action; +``` + diff --git a/components/Snackbar/docs/typical-use-display-a-message.md b/components/Snackbar/docs/typical-use-display-a-message.md new file mode 100644 index 00000000000..7264cf25e54 --- /dev/null +++ b/components/Snackbar/docs/typical-use-display-a-message.md @@ -0,0 +1,19 @@ +### Typical use: display a message + + +#### Swift + +```swift +let message = MDCSnackbarMessage() +message.text = "The groundhog (Marmota monax) is also known as a woodchuck or whistlepig." +MDCSnackbarManager.show(message) +``` + +#### Objective-C + +```objc +MDCSnackbarMessage *message = [[MDCSnackbarMessage alloc] init]; +message.text = @"How much wood would a woodchuck chuck if a woodchuck could chuck wood?"; +[MDCSnackbarManager showMessage:message]; +``` + diff --git a/components/Snackbar/docs/typography-theming.md b/components/Snackbar/docs/typography-theming.md index 9bee1932cf2..e868655720c 100644 --- a/components/Snackbar/docs/typography-theming.md +++ b/components/Snackbar/docs/typography-theming.md @@ -1,13 +1,4 @@ - - -# Snackbar Typography Theming +### Typography Theming You can theme an snackbar with your app's typography scheme using the TypographyThemer extension. @@ -17,8 +8,6 @@ You must first add the Typography Themer extension to your project: pod 'MaterialComponents/Snackbar+Extensions/TypographyThemer' ``` -## Example code - #### Swift ```swift