From c1fc4e728b26b75df2bb04d30a3f0ffb011fbd70 Mon Sep 17 00:00:00 2001 From: featherless Date: Tue, 1 May 2018 16:44:30 -0400 Subject: [PATCH] [FeatureHighlight] Split the documentation into separate articles and run the readme generator. (#3620) --- components/FeatureHighlight/.vars | 1 + components/FeatureHighlight/README.md | 156 +++++++++++++++--- components/FeatureHighlight/docs/README.md | 28 ++++ .../docs/typical-use-highlight-a-view.md | 63 +++++++ 4 files changed, 227 insertions(+), 21 deletions(-) create mode 100644 components/FeatureHighlight/docs/README.md create mode 100644 components/FeatureHighlight/docs/typical-use-highlight-a-view.md diff --git a/components/FeatureHighlight/.vars b/components/FeatureHighlight/.vars index e1101a8d19e..15b198eb55c 100644 --- a/components/FeatureHighlight/.vars +++ b/components/FeatureHighlight/.vars @@ -6,3 +6,4 @@ icon_id=feature_highlight color_themer_api=MDCFeatureHighlightColorThemer typography_themer_api=MDCFeatureHighlightTypographyThemer themer_parameter_name=FeatureHighlightViewController +short_description=Feature Highlight highlights a part of the screen in order to introduce users to new features and functionality. diff --git a/components/FeatureHighlight/README.md b/components/FeatureHighlight/README.md index 9894d60fa8b..b9757de31af 100644 --- a/components/FeatureHighlight/README.md +++ b/components/FeatureHighlight/README.md @@ -1,12 +1,15 @@ + + # Feature Highlight
@@ -15,50 +18,49 @@ path: /catalog/feature-highlights/ The Feature Highlight component is a way to visually highlight a part of the screen in order to introduce users to new features and functionality. -## Design & API Documentation +## Design & API documentation -## Extensions +## Table of contents - +- [Installation](#installation) + - [Installation with CocoaPods](#installation-with-cocoapods) + - [Importing](#importing) +- [Usage](#usage) + - [Typical use: highlight a view](#typical-use-highlight-a-view) +- [Extensions](#extensions) +# [Feature Highlight Color Theming](#feature-highlight-color-theming) +- [Example code](#example-code) +# [Feature Highlight Typography Theming](#feature-highlight-typography-theming) +- [Example code](#example-code) - - - ## Installation + + ### Installation with CocoaPods -To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`: +Add the following to your `Podfile`: -``` +```bash pod 'MaterialComponents/FeatureHighlight' ``` -To add this component along with its themer and other related extensions, please add the following instead: -```bash -pod 'MaterialComponents/FeatureHighlight+Extensions' -``` - Then, run the following command: ```bash pod install ``` -- - - - -## Usage - ### Importing -Before using Feature Highlight, you'll need to import it: +To import the component: #### Swift @@ -67,12 +69,18 @@ import MaterialComponents.MaterialFeatureHighlight ``` #### Objective-C + ```objc #import "MaterialFeatureHighlight.h" ``` -### Highlighting a view + +## Usage + + + +### Typical use: highlight a view #### Swift @@ -135,3 +143,109 @@ MDCFeatureHighlightViewController *highlightController = completion:completion]; ``` + + +## Extensions + + + + + +# Feature Highlight Color Theming + +You can theme feature highlight with your app's color scheme using the ColorThemer extension. + +You must first add the Color Themer extension to your project: + +```bash +pod 'MaterialComponents/FeatureHighlight+Extensions/ColorThemer' +``` + +## Example code + + +#### Swift +```swift +// Step 1: Import the ColorThemer extension +import MaterialComponents.MaterialFeatureHighlight_ColorThemer + +// Step 2: Create or get a color scheme +let colorScheme = MDCSemanticColorScheme() + +// Step 3: Apply the color scheme to your component +MDCFeatureHighlightColorThemer.applySemanticColorScheme(colorScheme, to: component) +``` + +#### Objective-C + +```objc +// Step 1: Import the ColorThemer extension +#import "MaterialFeatureHighlight+ColorThemer.h" + +// Step 2: Create or get a color scheme +id colorScheme = [[MDCSemanticColorScheme alloc] init]; + +// Step 3: Apply the color scheme to your component +[MDCFeatureHighlightColorThemer applySemanticColorScheme:colorScheme + toFeatureHighlightViewController:component]; +``` + + + + + + +# Feature Highlight Typography Theming + +You can theme feature highlight with your app's typography scheme using the TypographyThemer extension. + +You must first add the Typography Themer extension to your project: + +```bash +pod 'MaterialComponents/FeatureHighlight+Extensions/TypographyThemer' +``` + +## Example code + + +#### Swift +```swift +// Step 1: Import the TypographyThemer extension +import MaterialComponents.MaterialFeatureHighlight_TypographyThemer + +// Step 2: Create or get a typography scheme +let typographyScheme = MDCTypographyScheme() + +// Step 3: Apply the typography scheme to your component +MDCFeatureHighlightTypographyThemer.applyTypographyScheme(typographyScheme, to: component) +``` + +#### Objective-C + +```objc +// Step 1: Import the TypographyThemer extension +#import "MaterialFeatureHighlight+TypographyThemer.h" + +// Step 2: Create or get a typography scheme +id typographyScheme = [[MDCTypographyScheme alloc] init]; + +// Step 3: Apply the typography scheme to your component +[MDCFeatureHighlightTypographyThemer applyTypographyScheme:colorScheme + toFeatureHighlightViewController:component]; +``` + + diff --git a/components/FeatureHighlight/docs/README.md b/components/FeatureHighlight/docs/README.md new file mode 100644 index 00000000000..c7ff4845ac1 --- /dev/null +++ b/components/FeatureHighlight/docs/README.md @@ -0,0 +1,28 @@ +# Feature Highlight + +
+ Feature Highlight +
+ +The Feature Highlight component is a way to visually highlight a part of the screen in order to introduce users to new features and functionality. + +## Design & API documentation + +* [Material Design guidelines: Feature Discovery](https://material.io/guidelines/growth-communications/feature-discovery.html) + + + +- - - + +## Installation + +- [Typical installation](../../../docs/component-installation.md) + +## Usage + +- [Typical use: highlight a view](typical-use-highlight-a-view.md) + +## Extensions + +- [Color Theming](color-theming.md) +- [Typography Theming](typography-theming.md) diff --git a/components/FeatureHighlight/docs/typical-use-highlight-a-view.md b/components/FeatureHighlight/docs/typical-use-highlight-a-view.md new file mode 100644 index 00000000000..ea2c4563482 --- /dev/null +++ b/components/FeatureHighlight/docs/typical-use-highlight-a-view.md @@ -0,0 +1,63 @@ +### Typical use: highlight a view + + +#### Swift +```swift +let completion = {(accepted: Bool) in + // perform analytics here + // and record whether the highlight was accepted +} + +let highlightController = MDCFeatureHighlightViewController(highlightedView: viewToHighlight, + completion: completion) +highlightController.titleText = "Just how you want it" +highlightController.bodyText = "Tap the menu button to switch accounts, change settings & more." +highlightController.outerHighlightColor = + UIColor.blue.withAlphaComponent(kMDCFeatureHighlightOuterHighlightAlpha) +present(highlightController, animated: true, completion:nil) +``` + +#### Objective-C +```objc +MDCFeatureHighlightCompletion completion = ^(BOOL accepted) { + // perform analytics here + // and record whether the highlight was accepted +}; + +MDCFeatureHighlightViewController *highlightController = +[[MDCFeatureHighlightViewController alloc] initWithHighlightedView:viewToHighlight + completion:completion]; +highlightController.titleText = @"Just how you want it"; +highlightController.bodyText = @"Tap the menu button to switch accounts, change settings & more."; +highlightController.outerHighlightColor = + [[UIColor blueColor] colorWithAlphaComponent:kMDCFeatureHighlightOuterHighlightAlpha]; +[self presentViewController:highlightController animated:YES completion:nil]; +``` + + +Often when highlighting a view you will want to display a different view to the one you are highlighting. For example, flipping the primary and secondary colors in the presented version. + + +#### Swift +```swift +let displayedButton = UIButton(type: .system) +displayedButton.setTitle(highlightedButton.title(for: .normal), for: .normal) +displayedButton.setTitleColor(highlightedButton.backgroundColor, for: .normal) +displayedButton.backgroundColor = highlightedButton.titleColor(for: .normal) + +let highlightController = MDCFeatureHighlightViewController(highlightedView: highlightedButton, andShow: displayedButton, completion: completion) +``` + +#### Objective-C +```objc +UIButton *displayedButton = [UIButton buttonWithType:UIButtonTypeSystem]; +[displayedButton setTitle:[highlightedButton titleForState:UIControlStateNormal] + forState:UIControlStateNormal]; +[displayedButton setTitleColor:highlightedButton.backgroundColor forState:UIControlStateNormal]; +displayedButton.backgroundColor = [highlightedButton titleColorForState:UIControlStateNormal]; +MDCFeatureHighlightViewController *highlightController = +[[MDCFeatureHighlightViewController alloc] initWithHighlightedView:highlightedButton + andShowView:displayedButton + completion:completion]; +``` +