Create doc for common attributes to most/all AMP components#276
Conversation
|
|
||
| ## fallback | ||
|
|
||
| The `fallback` attribute can be set on any HTML element, not just AMP elements. A fallback is a convention that allows the element to communicate to the reader that the browser does not support the element. If specified, a fallback element must be a direct child of the AMP element. The exact behavior with respect to the fallback is up to the element's implementation. |
There was a problem hiding this comment.
… does not support the element or that loading the underlying resource failed.
There was a problem hiding this comment.
to the end:, but typically the fallback element would be shown in place of the regular element.
|
|
||
| For more information, see [Placeholders & fallbacks](https://www.ampproject.org/docs/guides/responsive/placeholders). | ||
|
|
||
| ## height |
There was a problem hiding this comment.
Maybe make width and height one paragraph? It is a bit weird to have them far apart.
|
|
||
| ## noloading | ||
|
|
||
| The `noloading` attribute indicates whether the "loading indicator" should be turned **off** for this element. Many AMP elements are white-listed to show a "loading indicator", which is a basic animation that shows that the element has not yet fully loaded. |
|
|
||
| ## placeholder | ||
|
|
||
| The `placeholder` attribute can be set on any HTML element, not just AMP elements. The placeholder attribute indicates that the element marked with this attribute acts as a placeholder for the parent AMP element. If specified, a placeholder element must be a direct child of the AMP element. |
There was a problem hiding this comment.
The first sentence here and for fallback is a bit misleading.
Maybe lead with what they are for and then say "The attribute can be placed on any HTML element that is a direct child of an amp element that supports placeholders."
pbakaus
left a comment
There was a problem hiding this comment.
Looks good, just a few nits!
|
|
||
| ## heights | ||
|
|
||
| All AMP elements that support the `responsive` layout, also support the `heights` attribute. The value of this attribute is a sizes expression based on media expressions, similar to the [img sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) but with two key differences: |
There was a problem hiding this comment.
I'd reword as: "Similar to the sizes attribute on <img> tags"
| 1. The value applies to the height, not the width of the element. | ||
| 2. Percent values are allowed. A percent value indicates the percent of the element's width. For example, a value of `80%` indicates that the height of the element will be 80% of the element's width. | ||
|
|
||
| When the `heights` attribute is specified along with `width` and `height`, the `layout` is defaulted to `responsive`. |
| </amp-img> | ||
| [/sourcecode] | ||
|
|
||
| For more information, see [Art direction with srcset, sizes & heights](https://www.ampproject.org/docs/guides/responsive/art_direction). |
There was a problem hiding this comment.
I usually styled these as callouts (see styling guides), but up to you :) I'm torn, would like a better, more distinct way of telling people there's a continuation.
There was a problem hiding this comment.
In this case, I'm going to avoid callouts as there's many FYIs will make the doc too busy.
| height="193" layout="responsive"></amp-img> | ||
| [/sourcecode] | ||
|
|
||
| For more information, see [Layout & Media queries](https://www.ampproject.org/docs/guides/responsive/control_layout). |
There was a problem hiding this comment.
Link to the actual section, e.g. add #element-media-queries to the link.
| </amp-lightbox> | ||
| [/sourcecode] | ||
|
|
||
| For more information, see [Actions and Events in AMP](https://github.com/ampproject/amphtml/blob/master/spec/amp-actions-and-events.md). |
There was a problem hiding this comment.
Would be good to migrate this doc into a guide, e.g. "Adding interactions" or something. Just a reminder, no blocker for this PR.
|
|
||
| The `placeholder` attribute can be set on any HTML element, not just AMP elements. The placeholder attribute indicates that the element marked with this attribute acts as a placeholder for the parent AMP element. If specified, a placeholder element must be a direct child of the AMP element. | ||
|
|
||
| By default, the placeholder is immediately shown for the AMP element, even if the AMP element's resources have not been downloaded or initialized. Once ready, the AMP element typically hides its placeholder and shows the content. The exact behavior with respect to the placeholder is up to the element's implementation. |
There was a problem hiding this comment.
We usually use the term "component" instead of "element". I'm torn, I prefer elements but components reminds of web components, which is the underlying technology. WDYT @cramforce?
There's also the word tag, tag often gets used to describe the abstract, e.g. the -tag. Element often gets used to describe actual instances of tags on a page, e.g. "These 5
elements should not be here" (you wouldn't use tag in that scenario).
|
|
||
| ## sizes | ||
|
|
||
| All AMP elements that support the `responsive` layout, also support the `sizes` attribute. The value of the `sizes` attribute is a sizes expression as described in [img sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img), but extended to all elements, not just images. |
There was a problem hiding this comment.
Same as above, would reword "img sizes" to something like the -tag's sizes attribute.
Cramforce is on holidays; changes implemented.
A doc that will be linked/referred from amp component docs that describe the common attributes for AMP components.
to: @pbakaus
cc: @cramforce
In a different PR, I'll show how an amp component's doc "attributes" section will refer to this doc. Example - ampproject/amphtml#6772