From 1e80136d29ce0283123cc5fbda25fc2b324eceb9 Mon Sep 17 00:00:00 2001 From: featherless Date: Tue, 1 May 2018 22:17:16 -0400 Subject: [PATCH] [AppBar] Split the documentation into separate articles and run the readme generator. (#3634) --- components/AppBar/.vars | 1 + components/AppBar/README.md | 239 +++++++++++------- components/AppBar/docs/README.md | 94 +++++++ components/AppBar/docs/color-theming.md | 13 +- .../AppBar/docs/tracking-a-scroll-view.md | 5 + .../docs/typical-use-adding-an-app-bar.md | 81 ++++++ components/AppBar/docs/typography-theming.md | 11 +- 7 files changed, 334 insertions(+), 110 deletions(-) create mode 100644 components/AppBar/docs/README.md create mode 100644 components/AppBar/docs/tracking-a-scroll-view.md create mode 100644 components/AppBar/docs/typical-use-adding-an-app-bar.md diff --git a/components/AppBar/.vars b/components/AppBar/.vars index e48aad53e83..f0b1ec2678b 100644 --- a/components/AppBar/.vars +++ b/components/AppBar/.vars @@ -6,3 +6,4 @@ icon_id=toolbar color_themer_api=MDCAppBarColorThemer typography_themer_api=MDCAppBarTypographyThemer themer_parameter_name=AppBar +short_description=The Material Design top app bar displays information and actions relating to the current view. diff --git a/components/AppBar/README.md b/components/AppBar/README.md index 18f948168d5..2874aa07789 100644 --- a/components/AppBar/README.md +++ b/components/AppBar/README.md @@ -1,61 +1,52 @@ -# App Bars + + +# App Bar
App Bar
-The App Bar is a flexible navigation bar designed to provide a typical Material Design -navigation experience. +The Material Design top app bar displays information and actions relating to the current view. -## 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`: - -```bash -pod 'MaterialComponents/AppBar' -``` - - -To add this component along with its themer and other related extensions, please add the following instead: -```bash -pod 'MaterialComponents/AppBar+Extensions' -``` - -Then, run the following command: - -```bash -pod install -``` +## Table of contents + +- [Overview](#overview) + - [UINavigationItem and the App Bar](#uinavigationitem-and-the-app-bar) + - [Interacting with background views](#interacting-with-background-views) +- [Installation](#installation) + - [Installation with CocoaPods](#installation-with-cocoapods) + - [Importing](#importing) +- [Usage](#usage) + - [Typical use: Adding an app bar to your app](#typical-use-adding-an-app-bar-to-your-app) +- [Extensions](#extensions) + - [Color Theming](#color-theming) + - [Typography Theming](#typography-theming) +- [Example code](#example-code) - - - @@ -64,9 +55,11 @@ pod install The App Bar is a composite component that initializes and provides access to instances of the following components: -- [Flexible Header](../FlexibleHeader/) -- [Header Stack View](../HeaderStackView/) -- [Navigation Bar](../NavigationBar/) + The provided view hierarchy looks like so: @@ -85,20 +78,64 @@ doing so if the App Bar is limiting your ability to build something. In such a c also [filing an issue](https://github.com/material-components/material-components-ios/issues/new) so that we can identify whether your use case is something we can directly support. +### UINavigationItem and the App Bar +The App Bar begins mirroring the state of your view controller's `navigationItem` in the provided +`navigationBar` once you call `addSubviewsToParent`. -- - - +Learn more by reading the Navigation Bar section on +[Observing UINavigationItem instances](../NavigationBar/#observing-uinavigationitem-instances). +Notably: read the section on "Exceptions" to understand which UINavigationItem are **not** +supported. -## Usage +### Interacting with background views + +Scenario: you've added a background image to your App Bar and you'd now like to be able to tap the +background image. + +This is not trivial to do with the App Bar APIs due to considerations being discussed in +[Issue #184](https://github.com/material-components/material-components-ios/issues/184). + +The heart of the limitation is that we're using a view (`headerStackView`) to lay out the Navigation +Bar. If you add a background view behind the `headerStackView` instance then `headerStackView` will +end up eating all of your touch events. + +Until [Issue #184](https://github.com/material-components/material-components-ios/issues/184) is resolved, our +recommendation for building interactive background views is the following: + +1. Do not use the App Bar component. +2. Create your own Flexible Header. Learn more by reading the Flexible Header + [Usage](../FlexibleHeader/#usage) docs. +3. Add your views to this flexible header instance. +4. Create a Navigation Bar if you need one. Treat it like any other custom view. + +## Installation + + + +### Installation with CocoaPods + +Add the following to your `Podfile`: + +```bash +pod 'MaterialComponents/AppBar' +``` + + +Then, run the following command: + +```bash +pod install +``` ### Importing -Before using App Bar, you'll need to import it: +To import the component: #### Swift ```swift -import MaterialComponents +import MaterialComponents.MaterialAppBar ``` #### Objective-C @@ -108,7 +145,12 @@ import MaterialComponents ``` -### Add the App Bar to a view controller + +## Usage + + + +### Typical use: Adding an app bar to your app Each view controller in your app that intends to use an App Bar will follow these instructions. You'll typically add the App Bar to the same view controllers that you'd push onto a @@ -190,69 +232,90 @@ override func viewDidLoad() { ``` -### Tracking a scroll view -The App Bar's flexible nature is made possible due to the Flexible Header's ability to respond to -interactions with a scroll view. Learn how to set up this scroll view tracking by reading the -Flexible Header section on [Tracking a scroll view](../FlexibleHeader/#tracking-a-scroll-view). +See the [FlexibleHeader](../FlexibleHeader) documentation for additional usage guides. -### App Bar & UINavigationController +## Extensions -A view controller with an App Bar pushed onto a UINavigationController will look odd due to the -presence of two navigation bars: one provided by App Bar and another provided by -UINavigationController. The Flexible Header section on -[interacting with UINavigationController](../FlexibleHeader/#interacting-with-uinavigationcontroller) -provides recommendations for hiding the navigation bar appropriately in this situation. + -### Status bar style +### Color Theming -The Flexible Header component provides facilities for inferring the status bar style based on the -Flexible Header view's background color. Learn more by reading the section on -[Status bar style](../FlexibleHeader/#status-bar-style). +You can theme an app bar with your app's color scheme using the ColorThemer extension. -### UINavigationItem and the App Bar +You must first add the Color Themer extension to your project: -The App Bar begins mirroring the state of your view controller's `navigationItem` in the provided -`navigationBar` once you call `addSubviewsToParent`. +```bash +pod 'MaterialComponents/AppBar+Extensions/ColorThemer' +``` -Learn more by reading the Navigation Bar section on -[Observing UINavigationItem instances](../NavigationBar/#observing-uinavigationitem-instances). -Notably: read the section on "Exceptions" to understand which UINavigationItem are **not** -supported. + +#### Swift +```swift +// Step 1: Import the ColorThemer extension +import MaterialComponents.MaterialAppBar_ColorThemer -### Background images +// Step 2: Create or get a color scheme +let colorScheme = MDCSemanticColorScheme() -Showcase photography and imagery in your App Bar by adding image views to the App Bar's Flexible -Header. +// Step 3: Apply the color scheme to your component +MDCAppBarColorThemer.applySemanticColorScheme(colorScheme, to: component) +``` -Learn more by reading the Flexible Header section on -[Background images](../FlexibleHeader/#background-images). +#### Objective-C -### Touch forwarding +```objc +// Step 1: Import the ColorThemer extension +#import "MaterialAppBar+ColorThemer.h" -The App Bar enables touch forwarding for the headerStackView and the navigationBar instances. Touch -events made to those views (not their subviews) will be forwarded to the tracking scroll view. +// Step 2: Create or get a color scheme +id colorScheme = [[MDCSemanticColorScheme alloc] init]; -Learn more by reading the Flexible Header section on -[Touch forwarding](../FlexibleHeader/#touch-forwarding). +// Step 3: Apply the color scheme to your component +[MDCAppBarColorThemer applySemanticColorScheme:colorScheme + toAppBar:component]; +``` + -### Interacting with background views + -Scenario: you've added a background image to your App Bar and you'd now like to be able to tap the -background image. +### Typography Theming -This is not trivial to do with the App Bar APIs due to considerations being discussed in -[Issue #184](https://github.com/material-components/material-components-ios/issues/184). +You can theme an app bar with your app's typography scheme using the TypographyThemer extension. -The heart of the limitation is that we're using a view (`headerStackView`) to lay out the Navigation -Bar. If you add a background view behind the `headerStackView` instance then `headerStackView` will -end up eating all of your touch events. +You must first add the Typography Themer extension to your project: -Until [Issue #184](https://github.com/material-components/material-components-ios/issues/184) is resolved, our -recommendation for building interactive background views is the following: +```bash +pod 'MaterialComponents/AppBar+Extensions/TypographyThemer' +``` + +## Example code + + +#### Swift +```swift +// Step 1: Import the TypographyThemer extension +import MaterialComponents.MaterialAppBar_TypographyThemer + +// Step 2: Create or get a typography scheme +let typographyScheme = MDCTypographyScheme() + +// Step 3: Apply the typography scheme to your component +MDCAppBarTypographyThemer.applyTypographyScheme(typographyScheme, to: component) +``` + +#### Objective-C + +```objc +// Step 1: Import the TypographyThemer extension +#import "MaterialAppBar+TypographyThemer.h" + +// Step 2: Create or get a typography scheme +id typographyScheme = [[MDCTypographyScheme alloc] init]; + +// Step 3: Apply the typography scheme to your component +[MDCAppBarTypographyThemer applyTypographyScheme:colorScheme + toAppBar:component]; +``` + -1. Do not use the App Bar component. -2. Create your own Flexible Header. Learn more by reading the Flexible Header - [Usage](../FlexibleHeader/#usage) docs. -3. Add your views to this flexible header instance. -4. Create a Navigation Bar if you need one. Treat it like any other custom view. diff --git a/components/AppBar/docs/README.md b/components/AppBar/docs/README.md new file mode 100644 index 00000000000..04b2418dcb3 --- /dev/null +++ b/components/AppBar/docs/README.md @@ -0,0 +1,94 @@ +# App Bar + +
+ App Bar +
+ +The Material Design top app bar displays information and actions relating to the current view. + +## Design & API documentation + +* [Material Design guidelines: App Bar](https://material.io/guidelines/layout/structure.html#structure-app-bar) +* [Material Design guidelines: Scrolling Techniques](https://material.io/guidelines/patterns/scrolling-techniques.html) +* [API: MDCAppBar](https://material.io/components/ios/catalog/app-bars/api-docs/Classes/MDCAppBar.html) +* [API: MDCAppBarContainerViewController](https://material.io/components/ios/catalog/app-bars/api-docs/Classes/MDCAppBarContainerViewController.html) + +## Related components + +* [FlexibleHeader](../../FlexibleHeader) + + + +- - - + +## Overview + +The App Bar is a composite component that initializes and provides access to instances of the +following components: + +* [Flexible Header](../../FlexibleHeader) +* [Header Stack View](../../HeaderStackView) +* [Navigation Bar](../../NavigationBar) + +The provided view hierarchy looks like so: + + + | + | | + | <- headerView.contentView + | | + | | | + +This view hierarchy will be added to your view controller hierarchy using the convenience methods +outlined in the Usage docs below. + +Note that it is possible to create each of the above components yourself, though we only encourage +doing so if the App Bar is limiting your ability to build something. In such a case we recommend +also [filing an issue](https://github.com/material-components/material-components-ios/issues/new) so that we can +identify whether your use case is something we can directly support. + +### UINavigationItem and the App Bar + +The App Bar begins mirroring the state of your view controller's `navigationItem` in the provided +`navigationBar` once you call `addSubviewsToParent`. + +Learn more by reading the Navigation Bar section on +[Observing UINavigationItem instances](../../NavigationBar/#observing-uinavigationitem-instances). +Notably: read the section on "Exceptions" to understand which UINavigationItem are **not** +supported. + +### Interacting with background views + +Scenario: you've added a background image to your App Bar and you'd now like to be able to tap the +background image. + +This is not trivial to do with the App Bar APIs due to considerations being discussed in +[Issue #184](https://github.com/material-components/material-components-ios/issues/184). + +The heart of the limitation is that we're using a view (`headerStackView`) to lay out the Navigation +Bar. If you add a background view behind the `headerStackView` instance then `headerStackView` will +end up eating all of your touch events. + +Until [Issue #184](https://github.com/material-components/material-components-ios/issues/184) is resolved, our +recommendation for building interactive background views is the following: + +1. Do not use the App Bar component. +2. Create your own Flexible Header. Learn more by reading the Flexible Header + [Usage](../../FlexibleHeader/#usage) docs. +3. Add your views to this flexible header instance. +4. Create a Navigation Bar if you need one. Treat it like any other custom view. + +## Installation + +- [Typical installation](../../../docs/component-installation.md) + +## Usage + +- [Typical use: Adding an app bar to your app](typical-use-adding-an-app-bar.md) + +See the [FlexibleHeader](../../FlexibleHeader) documentation for additional usage guides. + +## Extensions + +- [Color Theming](color-theming.md) +- [Typography Theming](typography-theming.md) diff --git a/components/AppBar/docs/color-theming.md b/components/AppBar/docs/color-theming.md index 00ac7b8079c..d8e67e76ae3 100644 --- a/components/AppBar/docs/color-theming.md +++ b/components/AppBar/docs/color-theming.md @@ -1,13 +1,4 @@ - - -# App Bar Color Theming +### Color Theming You can theme an app bar 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/AppBar+Extensions/ColorThemer' ``` -## Example code - #### Swift ```swift diff --git a/components/AppBar/docs/tracking-a-scroll-view.md b/components/AppBar/docs/tracking-a-scroll-view.md new file mode 100644 index 00000000000..6c58611db15 --- /dev/null +++ b/components/AppBar/docs/tracking-a-scroll-view.md @@ -0,0 +1,5 @@ +### Tracking a scroll view + +The App Bar's flexible nature is made possible due to the Flexible Header's ability to respond to +interactions with a scroll view. Learn how to set up this scroll view tracking by reading the +Flexible Header section on [Tracking a scroll view](../../FlexibleHeader/#tracking-a-scroll-view). diff --git a/components/AppBar/docs/typical-use-adding-an-app-bar.md b/components/AppBar/docs/typical-use-adding-an-app-bar.md new file mode 100644 index 00000000000..8e282d3606b --- /dev/null +++ b/components/AppBar/docs/typical-use-adding-an-app-bar.md @@ -0,0 +1,81 @@ +### Typical use: Adding an app bar to your app + +Each view controller in your app that intends to use an App Bar will follow these instructions. +You'll typically add the App Bar to the same view controllers that you'd push onto a +UINavigationController, hiding the UINavigationController's `navigationBar` accordingly. + +The result of following these steps will be that: + +1. an App Bar is registered as a child view controller of your view controller, +2. you have access to the App Bar's Flexible Header view via the headerViewController property, and + that +3. you have access to the Navigation Bar and Header Stack View views via the corresponding + properties. + +Step 1: **Create an instance of MDCAppBar**. + +You must also add the `headerViewController` as a child view controller. + + +#### Swift +```swift +let appBar = MDCAppBar() + +override init(nibName nibNameOrNil: String?, bundle nibBundleOrNil: Bundle?) { + super.init(nibName: nibNameOrNil, bundle: nibBundleOrNil) + + self.addChildViewController(appBar.headerViewController) +} +``` + +#### Objective-C + +```objc +@interface ObjcViewController () +@property(nonatomic, strong, nonnull) MDCAppBar *appBar; +@end + +@implementation ObjcViewController + +- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil { + self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil]; + if (self) { + _appBar = [[MDCAppBar alloc] init]; + + [self addChildViewController:_appBar.headerViewController]; + } + return self; +} + +@end +``` + + +Step 2: **Inform the App Bar that your view controller's view has loaded**. + +Ideally you will do this after all views have been added to your controller's view in order to +ensure that the App Bar's Flexible Header is in front of all other views. + + +#### Swift +```swift +override func viewDidLoad() { + super.viewDidLoad() + + // After all other views have been registered. + appBar.addSubviewsToParent() +} +``` + +#### Objective-C +```objc +- (void)viewDidLoad { + [super viewDidLoad]; + + ... + + // After all other views have been registered. + [self.appBar addSubviewsToParent]; +} +``` + diff --git a/components/AppBar/docs/typography-theming.md b/components/AppBar/docs/typography-theming.md index 3d6ee438b88..07897bde6cb 100644 --- a/components/AppBar/docs/typography-theming.md +++ b/components/AppBar/docs/typography-theming.md @@ -1,13 +1,4 @@ - - -# App Bar Typography Theming +### Typography Theming You can theme an app bar with your app's typography scheme using the TypographyThemer extension.