Skip to content
This repository was archived by the owner on Dec 18, 2024. It is now read-only.

Commit 7391448

Browse files
jelbournjelbourn
committed
Add updated overview docs
1 parent 2c8c973 commit 7391448

24 files changed

+1673
-0
lines changed

‎src/assets/documents/overview/autocomplete.html

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<h2 id="not-yet-implemented-">Not yet implemented!</h2>
2+
<p>The autocomplete is not yet implemented. This is only a scaffold to make
3+
subsequent PRs easier to read. Please do not try to use yet :)</p>

‎src/assets/documents/overview/button-toggle.html

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<p>Button-toggles are on/off toggles with the appearance of a button. These toggles can be configured
2+
to behave as either radio-buttons or checkboxes. While they can be standalone, they are typically
3+
part of a <code>md-button-toggle-group</code>.</p>
4+
<div material-docs-example="button-toggle-overview"></div>
5+
<h3 id="exclusive-selection-vs-multiple-selection">Exclusive selection vs. multiple selection</h3>
6+
<p>By default, <code>md-button-toggle-group</code> acts like a radio-button group- only one item can be selected.
7+
In this mode, the <code>value</code> of the <code>md-button-toggle-group</code> will reflect the value of the selected
8+
button and <code>ngModel</code> is supported. </p>
9+
<p>Adding the <code>multiple</code> attribute allows multiple items to be selected (checkbox behavior). In this
10+
mode the values of the the toggles are not used, the <code>md-button-toggle-group</code> does not have a value,
11+
and <code>ngModel</code> is not supported.</p>
12+
<h3 id="accessibility">Accessibility</h3>
13+
<p>The button-toggles will present themselves as either checkboxes or radio-buttons based on the
14+
presence of the <code>multiple</code> attribute. </p>
15+
<h3 id="orientation">Orientation</h3>
16+
<p>The button-toggles can be rendered in a vertical orientation by adding the <code>vertical</code> attribute.</p>

‎src/assets/documents/overview/button.html

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<p>Angular Material buttons are native <code>&lt;button&gt;</code> or <code>&lt;a&gt;</code> elements enhanced with Material Design
2+
styling and ink ripples.</p>
3+
<div material-docs-example="button-overview"></div>
4+
<p>Native <code>&lt;button&gt;</code> and <code>&lt;a&gt;</code> elements are always used in order to provide the most straightforward
5+
and accessible experience for users. A <code>&lt;button&gt;</code> element should be used whenever some <em>action</em>
6+
is performed. An <code>&lt;a&gt;</code> element should be used whenever the user will <em>navigate</em> to another view.</p>
7+
<p>There are five button variants, each applied as an attribute:</p>
8+
<table>
9+
<thead>
10+
<tr>
11+
<th>Attribute</th>
12+
<th>Description</th>
13+
</tr>
14+
</thead>
15+
<tbody>
16+
<tr>
17+
<td><code>md-button</code></td>
18+
<td>Rectangular button w/ no elevation.</td>
19+
</tr>
20+
<tr>
21+
<td><code>md-raised-button</code></td>
22+
<td>Rectangular button w/ elevation</td>
23+
</tr>
24+
<tr>
25+
<td><code>md-icon-button</code></td>
26+
<td>Circular button with a transparent background, meant to contain an icon</td>
27+
</tr>
28+
<tr>
29+
<td><code>md-fab</code></td>
30+
<td>Circular button w/ elevation, defaults to theme&#39;s accent color</td>
31+
</tr>
32+
<tr>
33+
<td><code>md-mini-fab</code></td>
34+
<td>Same as <code>md-fab</code> but smaller</td>
35+
</tr>
36+
</tbody>
37+
</table>
38+
<h3 id="theming">Theming</h3>
39+
<p>Buttons can be colored in terms of the current theme using the <code>color</code> property to set the
40+
background color to <code>primary</code>, <code>accent</code>, or <code>warn</code>. By default, only FABs are colored; the default
41+
background color for <code>md-button</code> and <code>md-raised-button</code> matches the theme&#39;s background color. </p>

‎src/assets/documents/overview/card.html

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
<p>Cards are content containers for text, photos, and actions. Cards are intended to provide
2+
information on a single subject.</p>
3+
<div material-docs-example="card-overview"></div>
4+
<h3 id="basic-card-sections">Basic card sections</h3>
5+
<p>The most basic card needs only an <code>&lt;md-card&gt;</code> element with some content. However, Angular Material
6+
provides a number of preset sections that you can use inside of an <code>&lt;md-card&gt;</code>:</p>
7+
<table>
8+
<thead>
9+
<tr>
10+
<th>Element</th>
11+
<th>Description</th>
12+
</tr>
13+
</thead>
14+
<tbody>
15+
<tr>
16+
<td><code>&lt;md-card-title&gt;</code></td>
17+
<td>Card title</td>
18+
</tr>
19+
<tr>
20+
<td><code>&lt;md-card-subtitle&gt;</code></td>
21+
<td>Card subtitle</td>
22+
</tr>
23+
<tr>
24+
<td><code>&lt;md-card-content&gt;</code></td>
25+
<td>Primary card content. Intended for blocks of text</td>
26+
</tr>
27+
<tr>
28+
<td><code>&lt;img md-card-image&gt;</code></td>
29+
<td>Card image. Stretches the image to the container width</td>
30+
</tr>
31+
<tr>
32+
<td><code>&lt;md-card-actions&gt;</code></td>
33+
<td>Container for buttons at the bottom of the card</td>
34+
</tr>
35+
<tr>
36+
<td><code>&lt;md-card-footer&gt;</code></td>
37+
<td>Section anchored to the bottom of the card</td>
38+
</tr>
39+
</tbody>
40+
</table>
41+
<p>These elements primary serve as pre-styled content containers without any additional APIs.
42+
However, the <code>align</code> property on <code>&lt;md-card-actions&gt;</code> can be used to position the actions at the
43+
<code>&#39;start&#39;</code> or <code>&#39;end</code> of the container. </p>
44+
<h3 id="card-headers">Card headers</h3>
45+
<p>In addition to the aforementioned sections, <code>&lt;md-card-header&gt;</code> gives the ability to add a rich
46+
header to a card. This header can contain:</p>
47+
<table>
48+
<thead>
49+
<tr>
50+
<th>Element</th>
51+
<th>Description</th>
52+
</tr>
53+
</thead>
54+
<tbody>
55+
<tr>
56+
<td><code>&lt;md-card-title&gt;</code></td>
57+
<td>A title within the header</td>
58+
</tr>
59+
<tr>
60+
<td><code>&lt;md-card-subtitle&gt;</code></td>
61+
<td>A subtitle within the header</td>
62+
</tr>
63+
<tr>
64+
<td><code>&lt;img md-card-avatar&gt;</code></td>
65+
<td>An image used as an avatar within the header</td>
66+
</tr>
67+
</tbody>
68+
</table>
69+
<h3 id="title-groups">Title groups</h3>
70+
<p>An <code>&lt;md-title-group&gt;</code> can be used to combine a title, subtitle, and image into a single section.
71+
This element can contain:</p>
72+
<ul>
73+
<li><code>&lt;md-card-title&gt;</code></li>
74+
<li><code>&lt;md-card-subtite&gt;</code></li>
75+
<li>One of:<ul>
76+
<li><code>&lt;img md-card-sm-image&gt;</code></li>
77+
<li><code>&lt;img md-card-md-image&gt;</code></li>
78+
<li><code>&lt;img md-card-lg-image&gt;</code></li>
79+
</ul>
80+
</li>
81+
</ul>

‎src/assets/documents/overview/checkbox.html

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<p><code>&lt;md-checkbox&gt;</code> provides the same functionality as a native <code>&lt;input type=&quot;checkbox&quot;&gt;</code>
2+
enhanced Material Design styling and animations.</p>
3+
<div material-docs-example="checkbox-overview"></div>
4+
<h3 id="checkbox-label">Checkbox label</h3>
5+
<p>The checkbox label is provided as the content to the <code>&lt;md-checkbox&gt;</code> element. The label can be
6+
positioned before or after the checkbox by setting the <code>labelPosition</code> property to <code>&#39;before&#39;</code> or
7+
<code>&#39;after&#39;</code>.</p>
8+
<p>If you don&#39;t want the label to appear next to the checkbox, you can use
9+
<a href="https://www.w3.org/TR/wai-aria/states_and_properties#aria-label"><code>aria-label</code></a> or
10+
<a href="https://www.w3.org/TR/wai-aria/states_and_properties#aria-labelledby"><code>aria-labelledby</code></a> to
11+
specify an appropriate label.</p>
12+
<h3 id="use-with-angular-forms-">Use with <code>@angular/forms</code></h3>
13+
<p><code>&lt;md-checkobx&gt;</code> is compatible with <code>@angular/forms</code> and supports both <code>FormsModule</code>
14+
and <code>ReactiveFormsModule</code>.</p>
15+
<h3 id="indeterminate-state">Indeterminate state</h3>
16+
<p><code>&lt;md-checkbox&gt;</code> supports an <code>indeterminate</code> state, similar to the native <code>&lt;input type=&quot;checkbox&quot;&gt;</code>.
17+
While the <code>indeterminate</code> property of the checkbox is true, it will render as indeterminate
18+
regardless of the <code>checked</code> value. Any interaction with the checkbox by a user (i.e., clicking) will
19+
remove the indeterminate state.</p>
20+
<h3 id="theming">Theming</h3>
21+
<p>The color of a <code>&lt;md-checkbox&gt;</code> can be changed by using the <code>color</code> property. By default, checkboxes
22+
use the theme&#39;s accent color. This can be changed to <code>&#39;primary&#39;</code> or <code>&#39;warn&#39;</code>. </p>

‎src/assets/documents/overview/chips.html

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<h1 id="md-chips">md-chips</h1>
2+
<p><code>md-chips</code> provides a horizontal display of (optionally) selectable, addable, and removable,
3+
items and an input to create additional ones (again; optional). You can read more about chips
4+
in the <a href="https://material.google.com/components/chips.html">Material Design spec</a>.</p>
5+
<p>This is a placeholder README for the eventual chips component.</p>

‎src/assets/documents/overview/core.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<p>Core library code for other <code>@angular/material</code> components.</p>

‎src/assets/documents/overview/dialog.html

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<p>The <code>MdDialog</code> service can be used to open modal dialogs with Material Design styling and
2+
animations.</p>
3+
<div material-docs-example="dialog-overview"></div>
4+
<p>A dialog is opened by calling the <code>open</code> method with a component to be loaded and an optional
5+
config object. The <code>open</code> method will return an instance of <code>MdDialogRef</code>:</p>
6+
<pre><code class="lang-ts">let dialogRef = dialog.open(UserProfileComponent, {
7+
height: &#39;400px&#39;,
8+
width: &#39;600px&#39;,
9+
});
10+
</code></pre>
11+
<p>The <code>MdDialogRef</code> provides a handle on the opened dialog. It can be used to close the dialog and to
12+
recieve notification when the dialog has been closed.</p>
13+
<pre><code class="lang-ts">dialogRef.afterClosed.then(result =&gt; {
14+
console.log(`Dialog result: ${result}`); // Pizza!
15+
});
16+
17+
dialogRef.close(&#39;Pizza!&#39;);
18+
</code></pre>
19+
<p>Components created via <code>MdDialog</code> can <em>inject</em> <code>MdDialogRef</code> and use it to close the dialog
20+
in which they are contained. When closing, an optional result value can be provided. This result
21+
value is forwarded as the result of the <code>afterClosed</code> promise. </p>
22+
<h3 id="dialog-content">Dialog content</h3>
23+
<p>Several directives are available to make it easier to structure your dialog content:</p>
24+
<table>
25+
<thead>
26+
<tr>
27+
<th>Name</th>
28+
<th>Description</th>
29+
</tr>
30+
</thead>
31+
<tbody>
32+
<tr>
33+
<td><code>md-dialog-title</code></td>
34+
<td>[Attr] Dialog title, applied to a heading element (e.g., <code>&lt;h1&gt;</code>, <code>&lt;h2&gt;</code>)</td>
35+
</tr>
36+
<tr>
37+
<td><code>&lt;md-dialog-content&gt;</code></td>
38+
<td>Primary scrollable content of the dialog</td>
39+
</tr>
40+
<tr>
41+
<td><code>&lt;md-dialog-actions&gt;</code></td>
42+
<td>Container for action buttons at the bottom of the dialog</td>
43+
</tr>
44+
<tr>
45+
<td><code>md-dialog-close</code></td>
46+
<td>[Attr] Added to a <code>&lt;button&gt;</code>, makes the button close the dialog on click</td>
47+
</tr>
48+
</tbody>
49+
</table>

‎src/assets/documents/overview/grid-list.html

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<h1 id="md-grid-list">md-grid-list</h1>
2+
<p><code>md-grid-list</code> is an alternative list view that arranges cells into grid-based layout.
3+
See Material Design spec <a href="https://www.google.com/design/spec/components/grid-lists.html">here</a>.</p>
4+
<div material-docs-example="grid-list-overview"></div>
5+
<h2 id="usage">Usage</h2>
6+
<h3 id="setting-the-number-of-columns">Setting the number of columns</h3>
7+
<p>An <code>md-grid-list</code> must specify a <code>cols</code> attribute which sets the number of columns in the gird. The
8+
number of rows will be automatically determined based on the number of columns and the number of
9+
items.</p>
10+
<h3 id="setting-the-row-height">Setting the row height</h3>
11+
<p>The height of the rows in a grid list can be set via the <code>rowHeight</code> attribute. Row height for the
12+
list can be calculated in three ways:</p>
13+
<ol>
14+
<li><p><strong>Fixed height</strong>: The height can be in <code>px</code>, <code>em</code>, or <code>rem</code>. If no units are specified, <code>px</code>
15+
units are assumed (e.g. <code>100px</code>, <code>5em</code>, <code>250</code>).</p>
16+
</li>
17+
<li><p><strong>Ratio</strong>: This ratio is column-width:row-height, and must be passed in with a colon, not a
18+
decimal (e.g. <code>4:3</code>).</p>
19+
</li>
20+
<li><p><strong>Fit</strong>: Setting <code>rowHeight</code> to <code>fit</code> This mode automatically divides the available height by
21+
the number of rows. Please note the height of the grid-list or its container must be set. </p>
22+
</li>
23+
</ol>
24+
<p>If <code>rowHeight</code> is not specified, it defaults to a <code>1:1</code> ratio of width:height. </p>
25+
<h3 id="setting-the-gutter-size">Setting the gutter size</h3>
26+
<p>The gutter size can be set to any <code>px</code>, <code>em</code>, or <code>rem</code> value with the <code>gutterSize</code> property. If no
27+
units are specified, <code>px</code> units are assumed. By default the gutter size is <code>1px</code>.</p>
28+
<h3 id="adding-tiles-that-span-multiple-rows-or-columns">Adding tiles that span multiple rows or columns</h3>
29+
<p>It is possible to set the rowspan and colspan of each <code>md-grid-tile</code> individually, using the
30+
<code>rowspan</code> and <code>colspan</code> properties. If not set, they both default to <code>1</code>. The <code>colspan</code> must not
31+
exceed the number of <code>cols</code> in the <code>md-grid-list</code>. There is no such restriction on the <code>rowspan</code>
32+
however, more rows will simply be added for it the tile to fill.</p>
33+
<h3 id="tile-headers-and-footers">Tile headers and footers</h3>
34+
<p>A header and footer can be added to an <code>md-grid-tile</code> using the <code>md-grid-tile-header</code> and
35+
<code>md-grid-tile-footer</code> elements respectively.</p>

‎src/assets/documents/overview/icon.html

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
<h1 id="md-icon">md-icon</h1>
2+
<p><code>md-icon</code> makes it easier to use <em>vector-based</em> icons in your app. This directive supports both
3+
icon fonts and SVG icons, but not bitmap-based formats (png, jpg, etc.).</p>
4+
<div material-docs-example="icon-example"></div>
5+
<h2 id="usage">Usage</h2>
6+
<h3 id="registering-new-icons">Registering new icons</h3>
7+
<p><code>MdIconRegistry</code> is an injectable service that allows you to associate icon names with SVG URLs and
8+
define aliases for CSS font classes. Its methods are discussed below and listed in the API summary.</p>
9+
<p>In order to prevent XSS vulnerabilities, any URLs passed to the <code>MdIconRegistry</code> must be marked as
10+
trusted resource URLs by using Angular&#39;s <code>DomSanitizer</code> service.</p>
11+
<h3 id="font-icons">Font icons</h3>
12+
<h4 id="ligatures">Ligatures</h4>
13+
<p>Some fonts are designed to show icons by using
14+
<a href="https://en.wikipedia.org/wiki/Typographic_ligature">ligatures</a>, for example by rendering the text
15+
&quot;home&quot; as a home image. To use a ligature icon, put its text in the content of the <code>md-icon</code>
16+
component.</p>
17+
<p>By default the
18+
<a href="http://google.github.io/material-design-icons/#icon-font-for-the-web">Material icons font</a> is used.
19+
(You will still need to include the HTML to load the font and its CSS, as described in the link).
20+
You can specify a different font by setting the <code>fontSet</code> input to either the CSS class to apply to
21+
use the desired font, or to an alias previously registered with
22+
<code>MdIconRegistry.registerFontClassAlias</code>.</p>
23+
<h4 id="font-icons-via-css">Font icons via CSS</h4>
24+
<p>Fonts can also display icons by defining a CSS class for each icon glyph, which typically uses a
25+
<code>:before</code> selector to cause the icon to appear.
26+
<a href="https://fortawesome.github.io/Font-Awesome/examples/">FontAwesome</a> uses this approach to display
27+
its icons. To use such a font, set the <code>fontSet</code> input to the font&#39;s CSS class (either the class
28+
itself or an alias registered with <code>MdIconRegistry.registerFontClassAlias</code>), and set the <code>fontIcon</code>
29+
input to the class for the specific icon to show.</p>
30+
<p>For both types of font icons, you can specify the default font class to use when <code>fontSet</code> is not
31+
explicitly set by calling <code>MdIconRegistry.setDefaultFontSetClass</code>.</p>
32+
<h3 id="svg-icons">SVG icons</h3>
33+
<p>When an <code>md-icon</code> component displays an SVG icon, it does so by directly inlining the SVG content
34+
into the page as a child of the component. (Rather than using an <img> tag or a div background
35+
image). This makes it easier to apply CSS styles to SVG icons. For example, the default color of the
36+
SVG content is the CSS <a href="http://www.quirksmode.org/css/color/currentcolor.html">currentColor</a> value.
37+
This makes SVG icons by default have the same color as surrounding text, and allows you to change
38+
the color by setting the &quot;color&quot; style on the <code>md-icon</code> element.</p>
39+
<h4 id="icons-from-urls">Icons from URLs</h4>
40+
<p>SVG icons can be used either by directly specifying the icon&#39;s URL, or by associating an icon name
41+
with a URL and then referring to the name. To use a URL directly, set the <code>svgSrc</code> input.</p>
42+
<h4 id="named-icons">Named icons</h4>
43+
<p>To associate a name with an icon URL, use the <code>addSvgIcon</code> or <code>addSvgIconInNamespace</code> methods of
44+
<code>MdIconRegistry</code>. After registering an icon, it can be displayed by setting the <code>svgIcon</code> input.
45+
For an icon in the default namespace, use the name directly. For a non-default namespace, use the
46+
format <code>[namespace]:[name]</code>.</p>
47+
<h4 id="icon-sets">Icon sets</h4>
48+
<p>Icon sets allow grouping multiple icons into a single SVG file. This is done by creating a single
49+
root <code>&lt;svg&gt;</code> tag that contains multiple nested <code>&lt;svg&gt;</code> tags in its <code>&lt;defs&gt;</code> section. Each of these
50+
nested tags is identified with an <code>id</code> attribute. This <code>id</code> is used as the name of the icon.</p>
51+
<p>Icon sets are registered using the <code>addSvgIconSet</code> or <code>addSvgIconSetInNamespace</code> methods of
52+
<code>MdIconRegistry</code>. After an icon set is registered, each of its embedded icons can be accessed by
53+
their <code>id</code> attributes. To display an icon from an icon set, use the <code>svgIcon</code> input in the same way
54+
as for individually registered icons.</p>
55+
<p>Multiple icon sets can be registered in the same namespace. Requesting an icon whose id appears in
56+
more than one icon set, the icon from the most recently registered set will be used.</p>
57+
<p>Note that all SVG icons are fetched via XmlHttpRequest, and due to the same-origin policy their URLs
58+
must be on the same domain as the containing page, or their servers must be configured to allow
59+
cross-domain access.</p>
60+
<h3 id="theming">Theming</h3>
61+
<p>Icons can be themed to match your &quot;primary&quot; palette, your &quot;accent&quot; palette, or your &quot;warn&quot; palette
62+
using the <code>color</code> attribute. Simply pass in the desired palette name.</p>
63+
<h3 id="accessibility">Accessibility</h3>
64+
<p>If an <code>aria-label</code> attribute is set on the <code>md-icon</code> element, its value will be used as-is. If not,
65+
the md-icon component will attempt to set the aria-label value from one of these sources:</p>
66+
<ul>
67+
<li>The <code>alt</code> attribute</li>
68+
<li>The <code>fontIcon</code> input</li>
69+
<li>The name of the icon from the <code>svgIcon</code> input (not including any namespace)</li>
70+
<li>The text content of the component (for ligature icons)</li>
71+
</ul>

0 commit comments

Comments
 (0)