[FlexibleHeader] Add the component with a simple example.

Reviewers: #material_components_ios_owners, junius, randallli

Reviewed By: #material_components_ios_owners, junius, randallli

Projects: #material_components_ios

Differential Revision: http://codereview.cc/D120

Author: Jeff Verkoeyen

catalog/Podfile.lock

@@ -1,5 +1,6 @@
 PODS:
   - material-components-ios (0.1.0):
+    - material-components-ios/FlexibleHeader (= 0.1.0)
     - material-components-ios/Ink (= 0.1.0)
     - material-components-ios/PageControl (= 0.1.0)
     - material-components-ios/private (= 0.1.0)
@@ -11,6 +12,7 @@ PODS:
     - material-components-ios/Switch (= 0.1.0)
     - material-components-ios/Typography (= 0.1.0)
   - material-components-ios-catalog (0.1.0)
+  - material-components-ios/FlexibleHeader (0.1.0)
   - material-components-ios/Ink (0.1.0)
   - material-components-ios/PageControl (0.1.0)
   - material-components-ios/private (0.1.0):
@@ -42,7 +44,7 @@ EXTERNAL SOURCES:
     :path: ../
 
 SPEC CHECKSUMS:
-  material-components-ios: b1e1bc101fe89ed301cdfeb479597d90b1fcf911
+  material-components-ios: 463b80af2a7388584df19727b09f00f9ec43e4b1
   material-components-ios-catalog: 9e0e0b97321c38c0335293b8355d838071614f78
 
 COCOAPODS: 0.39.0

components/FlexibleHeader/README.md

@@ -0,0 +1,166 @@
+# Flexible header
+
+The flexible header component is a container view whose height and vertical offset react to
+UIScrollViewDelegate events.
+
+## Installation with CocoaPods
+
+To add the Flexible Header to your Xcode project using CocoaPods, add the following to your
+`Podfile`:
+
+    pod 'material-components-ios-catalog/FlexibleHeader'
+
+Then, run the following command:
+
+    $ pod install
+
+## Design considerations
+
+Most view controllers own their own header in a material app. These headers are flexible, provide
+navigation information and actions, and often display high quality photography that complements the
+underlying content. Flexible Header was designed with the these expectations in mind.
+
+This deviates from the typical UIKit convention of having a UINavigationController that owns and
+manages a single UINavigationBar. The benefits of this deviation are:
+
+- It is easier to build custom transitions from one view controller.
+- Questions such as "what happens whe the header is 50pt tall and we push a view controller wanting
+  a 20pt tall header?" are no longer part of the discussion. With UINavigationBar — or any shared
+  navigation bar for that matter — resolving this leads to difficult architectural trade offs.
+
+### What's inside
+
+TODO(featherless): Discuss the three classes in this component, their relationship to one another,
+and lead from this to the "Integration" section.
+
+## Integration
+
+TODO(featherless): Go over this section with an editing comb.
+
+TODO(featherless): Discuss injection. Compare this to UITableViewController and how it federates
+access to UITableView.
+
+    @interface MyViewController () <MDCFlexibleHeaderParentViewController>
+
+This protocol defines a flexible header view property which you will need to synthesize.
+
+    @implementation MyViewController
+
+    @synthesize headerViewController;
+
+In order to populate the property, call the `addToParent:` method.
+
+    - (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
+      self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
+      if (self) {
+        [MDCFlexibleHeaderViewController addToParent:self];
+        ...
+
+Within your viewDidLoad you can now create and initialize any subviews that you'd like to add to
+your header view.
+
+    - (void)viewDidLoad {
+      [super viewDidLoad];
+      ...
+
+      // Create custom views here.
+      UIView *myCustomView = [UIView new];
+      myCustomView.frame = self.headerViewController.headerView.bounds;
+      myCustomView.autoresizingMask = (UIViewAutoresizingFlexibleWidth
+                                       | UIViewAutoresizingFlexibleHeight);
+      [self.headerViewController.headerView addSubview:myCustomView];
+
+      [self.headerViewController addFlexibleHeaderViewToParentViewControllerView];
+    }
+
+Note that any views added to the flexible header view should set their autoresizing masks to
+flexible width and height so that they expand/contract along with the header view.
+
+TODO(featherless): Include "manual" example of using the standard UIKit APIs to add the
+view/controller.
+
+### A note on subclasses
+
+A subclass of your view controller may add additional views in their viewDidLoad, potentially
+resulting in the header being covered by the new views. It is the responsibility of the subclass to
+take the z-index into account:
+
+[self.view insertSubview:myCustomView belowSubview:self.headerViewController.headerView];
+
+### Usage with UINavigationController**
+
+You may use an instance of UINavigationController to push and pop view controllers that are managing
+their own header view controller. UINavigationController does have its own navigation bar, so be
+sure to set `navigationBarHidden` to YES either all the time (if all of your view controllers have
+headers, or on the `viewWillAppear:` method).
+
+Do **not** forget to do this if you support app state restoration, or your app will launch with
+double navigation bars.
+
+## Tracking a scroll view
+
+In most situations you will want the header to track a UIScrollView's scrolling behavior. This
+allows the header to expand, collapse, and shift off-screen.
+
+To track a scroll view please follow these steps:
+
+### Step 1: Set the tracking scroll view
+
+In your viewDidLoad, set the `trackingScrollView` property on the header view:
+
+    self.headerViewController.headerView.trackingScrollView = scrollView;
+
+`scrollView` might be a table view, collection view, or a plain UIScrollView.
+
+### Step 2: Forward scroll view delegate events to the header view
+
+There are two ways to forward scroll events.
+
+**Set headerViewController as the delegate**
+
+You may use this approach if you do not need to implement any of the delegate's methods yourself
+**and your scroll view is not a collection view**.
+
+    scrollView.delegate = self.headerViewController;
+
+**Forward the UIScrollViewDelegate methods to the header view**
+
+If you need to implement any of the UIScrollViewDelegate methods yourself then you will need to
+manually forward the following methods to the flexible header view.
+
+    #pragma mark - UIScrollViewDelegate
+
+    - (void)scrollViewDidScroll:(UIScrollView *)scrollView {
+      if (scrollView == self.headerViewController.headerView.trackingScrollView) {
+        [self.headerViewController.headerView trackingScrollViewDidScroll];
+      }
+    }
+
+    - (void)scrollViewDidEndDecelerating:(UIScrollView *)scrollView {
+      if (scrollView == self.headerViewController.headerView.trackingScrollView) {
+        [self.headerViewController.headerView trackingScrollViewDidEndDecelerating];
+      }
+    }
+
+    - (void)scrollViewDidEndDragging:(UIScrollView *)scrollView willDecelerate:(BOOL)decelerate {
+      if (scrollView == self.headerViewController.headerView.trackingScrollView) {
+        [self.headerViewController.headerView trackingScrollViewDidEndDraggingWillDecelerate:decelerate];
+      }
+    }
+
+    - (void)scrollViewWillEndDragging:(UIScrollView *)scrollView
+                         withVelocity:(CGPoint)velocity
+                  targetContentOffset:(inout CGPoint *)targetContentOffset {
+      if (scrollView == self.headerViewController.headerView.trackingScrollView) {
+        [self.headerViewController.headerView trackingScrollViewWillEndDraggingWithVelocity:velocity
+                                                                        targetContentOffset:targetContentOffset];
+      }
+    }
+
+### Step 3: Implement prefersStatusBarHidden and query the flexible header view controller
+
+In order to affect the status bar's visiblity you must query the header view controller.
+
+    - (BOOL)prefersStatusBarHidden {
+      return self.headerViewController.prefersStatusBarHidden;
+    }

components/FlexibleHeader/examples/FlexibleHeaderTypicalUseViewController.m

@@ -0,0 +1,84 @@
+/*
+ Copyright 2015-present Google Inc. All Rights Reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+
+#import <UIKit/UIKit.h>
+
+#import "MaterialFlexibleHeader.h"
+
+@interface FlexibleHeaderTypicalUseViewController : UITableViewController <MDCFlexibleHeaderParentViewController>
+@end
+
+@implementation FlexibleHeaderTypicalUseViewController
+
+@synthesize headerViewController;
+
+// TODO: Support other categorizational methods.
++ (NSArray *)catalogHierarchy {
+  return @[ @"Flexible Header", @"Typical use" ];
+}
+
+- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
+  self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
+  if (self) {
+    [MDCFlexibleHeaderViewController addToParent:self];
+  }
+  return self;
+}
+
+- (void)viewDidLoad {
+  [super viewDidLoad];
+
+  UIToolbar *bar = [UIToolbar new];
+  bar.items = @[ [[UIBarButtonItem alloc] initWithTitle:@"Back"
+                                                  style:UIBarButtonItemStyleDone
+                                                 target:self
+                                                 action:@selector(didTapButton:)] ];
+  bar.frame = self.headerViewController.headerView.bounds;
+  bar.autoresizingMask = (UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight);
+  [self.headerViewController.headerView addSubview:bar];
+
+  self.headerViewController.headerView.trackingScrollView = self.tableView;
+  self.tableView.delegate = self.headerViewController;
+
+  [self.headerViewController addFlexibleHeaderViewToParentViewControllerView];
+}
+
+- (void)viewWillAppear:(BOOL)animated {
+  [super viewWillAppear:animated];
+
+  [self.navigationController setNavigationBarHidden:YES animated:animated];
+}
+
+- (void)didTapButton:(id)button {
+  [self.navigationController popViewControllerAnimated:YES];
+}
+
+#pragma mark - UITableViewDataSource
+
+- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
+  return 50;
+}
+
+- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
+  UITableViewCell *cell = [self.tableView dequeueReusableCellWithIdentifier:@"cell"];
+  if (!cell) {
+    cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:@"cell"];
+  }
+  cell.textLabel.text = [NSString stringWithFormat:@"%ld", indexPath.row];
+  return cell;
+}
+
+@end

components/FlexibleHeader/src/MDCFlexibleHeaderContainerViewController.h

@@ -0,0 +1,37 @@
+#import <UIKit/UIKit.h>
+
+@class MDCFlexibleHeaderViewController;
+
+/**
+ The MDCFlexibleHeaderContainerViewController controller is a straightforward container of a
+ content view controller and a MDCFlexibleHeaderViewController.
+
+ This view controller may be used in situations where the content view controller can't have a
+ header injected into its view hierarchy. UIPageViewController is one such view controller.
+ */
+@interface MDCFlexibleHeaderContainerViewController : UIViewController
+
+- (nonnull instancetype)initWithContentViewController:(nullable UIViewController *)contentViewController
+    NS_DESIGNATED_INITIALIZER;
+
+/**
+ The header view controller owned by this container view controller.
+
+ Created during initialization.
+ */
+@property(nonatomic, strong, nonnull, readonly) MDCFlexibleHeaderViewController *headerViewController;
+
+/** The content view controller to be displayed behind the header. */
+@property(nonatomic, strong, nullable) UIViewController *contentViewController;
+
+/**
+ Returns a Boolean indicating whether the status bar should be hidden or not.
+
+ Must be called by the parent view controller's -prefersStatusBarHidden implementation.
+ */
+- (BOOL)prefersStatusBarHidden;
+
+/** Calculates the status bar style based on the header view's background color. */
+- (UIStatusBarStyle)preferredStatusBarStyle;
+
+@end

components/FlexibleHeader/src/MDCFlexibleHeaderContainerViewController.m

@@ -0,0 +1,81 @@
+#if !defined(__has_feature) || !__has_feature(objc_arc)
+#error "This file requires ARC support."
+#endif
+
+#import "MDCFlexibleHeaderContainerViewController.h"
+
+#import "MDCFlexibleHeaderView.h"
+#import "MDCFlexibleHeaderViewController.h"
+
+@interface MDCFlexibleHeaderContainerViewController () <MDCFlexibleHeaderParentViewController>
+@end
+
+@implementation MDCFlexibleHeaderContainerViewController
+
+- (instancetype)initWithContentViewController:(UIViewController *)contentViewController {
+  self = [super initWithNibName:nil bundle:nil];
+  if (self) {
+    [MDCFlexibleHeaderViewController addToParent:self];
+
+    self.contentViewController = contentViewController;
+  }
+  return self;
+}
+
+- (instancetype)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
+  return [self initWithContentViewController:nil];
+}
+
+- (instancetype)initWithCoder:(NSCoder *)aDecoder {
+  return [self initWithContentViewController:nil];
+}
+
+- (void)viewDidLoad {
+  [super viewDidLoad];
+
+  [self.view addSubview:self.contentViewController.view];
+  [self.contentViewController didMoveToParentViewController:self];
+
+  [self.headerViewController addFlexibleHeaderViewToParentViewControllerView];
+}
+
+- (BOOL)prefersStatusBarHidden {
+  return _headerViewController.prefersStatusBarHidden;
+}
+
+- (UIStatusBarStyle)preferredStatusBarStyle {
+  return _headerViewController.preferredStatusBarStyle;
+}
+
+#pragma mark - Public
+
+- (void)setHeaderViewController:(MDCFlexibleHeaderViewController *)headerViewController {
+  _headerViewController = headerViewController;
+}
+
+- (void)setContentViewController:(UIViewController *)contentViewController {
+  if (_contentViewController == contentViewController) {
+    return;
+  }
+
+  // Teardown of the old controller
+
+  [_contentViewController willMoveToParentViewController:nil];
+  if ([_contentViewController isViewLoaded]) {
+    [_contentViewController.view removeFromSuperview];
+  }
+  [_contentViewController removeFromParentViewController];
+
+  // Setup of the new controller
+
+  _contentViewController = contentViewController;
+
+  [self addChildViewController:contentViewController];
+  if ([self isViewLoaded]) {
+    [self.view insertSubview:contentViewController.view
+                belowSubview:self.headerViewController.headerView];
+    [contentViewController didMoveToParentViewController:self];
+  }
+}
+
+@end