Catalog by convention

This app is dynamically generated by taking advantage of CocoaPods wildcards. The Podfile for the catalog adds all Material components. It also adds any example source that matches a wildcard like components/*/examples/*.{h,m,swift}. Check out material-components-ios-catalog.podspec for the most up-to-date paths.

At runtime, the app enumerates all instances of UIViewController that respond to the +catalogBreadcrumbs class method. This method is expected to return an array of strings that define the "breadcrumbs" for how to navigate from the root view controller to that view controller in the catalog app. Other view controllers could define matching strings if they by convention should be grouped together.

Building the app

We use CocoaPods to manage the dependencies of this app. To generate the dependent projects, run the following within the catalog/ directory of this repo:

pod install

This will update the MDCCatalog.xcworkspace.

Open the workspace and ensure that the "MDCCatalog" target is selected.

Build and run the app.

Adding examples

Let's build a hypothetical example for the "Ink" component.

The first step is to create a source file. This can be either a .m or a .swift; whichever you prefer. Place this source file in the component's examples/ directory, like so:

View controller names must be globally unique across every component's example set. An easy way to ensure this is to prefix the controller with the name of the component.

components/Ink/examples/InkDemoViewController.m

Note that, like unit tests, you likely won't need to create a .h file for your example.

You can now create the view controller class.

#import <UIKit/UIKit.h>

@interface InkDemoViewController : UIViewController
@end

@implementation InkDemoViewController

// TODO: Support other categorizational methods.
+ (NSArray *)catalogBreadcrumbs {
  return @[ @"Ink", @"README demo" ];
}

@end

The catalogBreadcrumbs method is the mechanism by which you define where the example lives in the catalog app. It is easiest to think of the values as a list of breadcrumbs.

To add the example to the Catalog app, simply run pod install in the catalog/ directory again:

catalog/ $ pod install

Build and run and you'll see your example listed in the app's hierarchy.

Using storyboards

If you want your example to use a storyboard you need the view controller class to specify that storyboard. You do this by implementing the CatalogStoryboardViewController protocol like so:

+ (NSString *)catalogStoryboardName {
  return @"SliderAutolayoutExample";
}

Place this source file in the component's examples/ directory, like so:

Storyboard names must be globally unique across every component's example set. An easy way to ensure this is to prefix the controller with the name of the component.

components/Slider/examples/SliderAutolayoutExample.storyboard