platform-API-template.md

[API name]

example Android Buttons title:

Material Buttons

Add a concise (1-2 sentence) description of the API here.

Describe in 1-2 paragraphs how the API is used. If possible, reference any relevant material.io articles.

Add a link to the corresponding developer pages that the component (helps) implement.

Example: Android Material Buttons

Material Button is a a child object clqww of Buttons, which allow users to take action and make choices with a single tap.

The Material Button class displays Material default styles without the use of a style flag.

Relevant Links

Material Buttons guidance [Android Material Button Examples](page that includes code samples to implement the examples shown on the m.io guidance page) Android MaterialButton developer page

If the API implements multiple component variants described in material.io, list them here and link to the local anchor link for its section.

Example from Android Material Button

Material Button implements the following of the Buttons components from Material.io: ß

• Text button
• Outlined button
• Contained button

Insert any related graphics: show instead of say.

example images from Buttons:

Installing [Component Name ]

If there are any instructions on installing the API, include them here.

For example, for the iOS buttons component:

Install mcd-button

You must install MCDButtons before you can use it in your application. In your source files import the component, and then apply your theme:

1. Install MDCButtons

   • Use CocoaPods to install MDCButtons
     1. Add the following to your Podfile:

     pod MaterialComponents/Buttons

     1. Run the installer:

     pod install

2. Import MDCButtons and MDC buttons theming and initialize MDCButtons using alloc/init. Initialize your theme before applying it to your button.

   Note For more information about themes, go to the Theming page for iOS.

   Swift

   import MaterialComponents.MaterialButtons
   import MaterialComponents.MaterialButtons_Theming
   /*...*/
   let <local theme name> = <theme name>
   let button = MDCButton()

   Objective-C

   #import "MaterialButtons.h"
   #import <MaterialComponentsBeta/MaterialButtons+Theming.h>
   /*...*/
   <theme name> *<local theme name> = [[<theme name> alloc] init];
   MDCButton *button = [[MDCButton alloc] init];

3. Apply accessibility settings To help make your buttons usable to as many users as possible:

   • Set an appropriate accessibilityLabel value if your button does not have a title or only has an icon. Objective-C

     button.accessibilityLabel = @"Create";

     Swift

     button.accessibilityLabel = "Create"

[API] prototype

Insert the API prototype here.

Include tables for any of the prototype's properties, such as child classes, constants, variables, etc.

Example from iOS: MCDRaisedButton

MCDRaisedButton prototype

Interface Class

@interface MDCButton : UIButton <MDCElevatable, MDCElevationOverriding>

Properties

inkStyle

This is a description of the inkStyle property for iOS.

inkColor

This is a description of the inkColor property for iOS.

If relevant, insert all related component code and a table for related properties. If the prototype references other APIs, list them and include the relevant links.

[Component section]

Divide the component API into its variants, preferably as described in the [material.io/components] pages.

For example buttons is divided into the following 3rd tier (### header) sections based on its variants:

• Text button
• Outlined button
• Contained button
• Toggle button

Whereas cards is divided into:

• Behavior
• Actions
• Card collections

Each section should have a 3rd tier header. Add 1-2 sentences from the material.io website that describes when and how to use the component. Within each section, there should be a table that contains:

• an image of the section topic
• a general description
• classes, parameters, enums related to the section
• links to the applicable API(s) if there are any specific to the section.

If possible, each section should have its own example(s) with code snippets/settings relevant to the section and an image showing what the code could generate. All code samples should be self-contained easy to cut and paste into a user's existing code and be expected to work.

Example: Android Button

Android text button

Text buttons are typically used for less-pronounced actions, including those located: * In dialogs * In cards In cards, text buttons help maintain an emphasis on card content.

Attribute	Attribute value	Element description
android:id	"@+id/material_text_button"
style	"@style/Widget.MaterialComponents.Button.TextButton"
android:layout_width	"wrap_content"
android: layout_height	"wrap_content"
android:text	"@string/text_button_label_enabled"

Android text button example

 <com.google.android.material.button.MaterialButton
   android:id="@+id/material_text_button"
   style="@style/Widget.MaterialComponents.Button.TextButton"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:text="@string/text_button_label_enabled"/>

...

Example: [Describe a way to use the Component]

• Provide an example scenario of how the component might be used. Preferably, chose an example that implements something that resembles one of the design examples for the related [material.io/components] page, such as an extended floating action button
  • What functions/objects/methods does it use?
  • How does the example use the objects/functions?
  • Are there any special settings/options used in this example, and why?
• Provide an image of what the example could produce. Mention any themes/settings used. Ideally each example will have an image or video showing a render of code example.

Click to View Examples without Steps

Describe the example and its components, including specific settings and instructions.

Example: Add a contained (filled) and elevated button

The following code adds a contained and elevated button to your app. Your theme's colorPrimary is the default background color and your theme's colorOnPrimary is the default text color.

 <com.google.android.material.button.MaterialButton
   android:id="@+id/material_button"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:text="@string/button_label_enabled"/>

Example: Add a contained (filled) and unelevated button

The following code adds a contained and unelevated button. Your theme's colorPrimary is the default background color and your theme's colorOnPrimary is the default text color.

  <com.google.android.material.button.MaterialButton
    android:id="@+id/disabled_material_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:enabled="false"
    android:text="@string/button_label_disabled"/>

Click to View Examples with Steps

If the example entails multiple steps, use a numbered list for each step. Break out any installation/importation steps into its own list.

List the steps to use the component. Include any installation/importation instructions in a separate list.

Add a themed text button

Follow the steps below to add a text button in your iOS application:

1. Add the following to your Podfile:

pod 'MaterialComponents/Buttons'

2. Run the install command:

 pod install

3. In your source file, you will need to:
   • import MaterialButtons

       import MaterialComponents.MaterialButtons

   • import MaterialButtons_Theming

     import MaterialComponents.MaterialButtons_Theming

   • initialize the button

     let button = MDCButton()

   • apply a theme to the text button

     button.applyTextTheme(withScheme: containerScheme)