forked from ampproject/amphtml
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
📖
bento-twitter
documentation (ampproject#35847)
* Copy to 0.1 subdir * Edit existing documentation * Create readme
- Loading branch information
Showing
3 changed files
with
377 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,131 @@ | ||
--- | ||
$category@: social | ||
formats: | ||
- websites | ||
- stories | ||
teaser: | ||
text: Displays a Twitter Tweet or Moment. | ||
--- | ||
|
||
# amp-twitter | ||
|
||
## Behavior | ||
|
||
The `amp-twitter` component allows you to embed a Tweet or Moment for the specified Twitter ID. | ||
|
||
Here's an example of a basic embedded Tweet: | ||
|
||
[example preview="inline" playground="true" imports="amp-twitter" imports="amp-twitter"] | ||
|
||
```html | ||
<amp-twitter | ||
width="375" | ||
height="472" | ||
layout="responsive" | ||
data-tweetid="885634330868850689" | ||
> | ||
</amp-twitter> | ||
``` | ||
|
||
[/example] | ||
|
||
## Appearance | ||
|
||
Twitter does not currently provide an API that yields fixed aspect ratio for embedded Tweets or Moments. Currently, AMP automatically proportionally scales the Tweet or Moment to fit the provided size, but this may yield less than ideal appearance. You might need to manually tweak the provided width and height. Also, you can use the `media` attribute to select the aspect ratio based on the screen width. | ||
|
||
## Placeholders & fallbacks | ||
|
||
An element marked with a `placeholder` attribute displays while the content for the Tweet or Moment is loading or initializing. Placeholders are hidden once the AMP component's content displays. An element marked with a `fallback` attribute displays if `amp-twitter` isn't supported by the browser or if the Tweet or Moment doesn't exist or has been deleted. | ||
|
||
Visit the [Placeholders & fallbacks](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/placeholders) guide to learn more about how placeholders and fallbacks interact for the `amp-twitter` component. | ||
|
||
_Example: Specifying a placeholder_ | ||
|
||
[example preview="inline" playground="true" imports="amp-twitter" imports="amp-twitter"] | ||
|
||
```html | ||
<amp-twitter | ||
width="375" | ||
height="472" | ||
layout="responsive" | ||
data-tweetid="638793490521001985" | ||
> | ||
<blockquote placeholder> | ||
<p> | ||
I only needed to change some CSS. | ||
<a href="http://t.co/LvjLbjgY9F">pic.twitter.com/LvjLbjgY9F</a> | ||
</p> | ||
— Malte Ubl (@cramforce) | ||
<a href="https://twitter.com/cramforce/status/638793490521001985" | ||
>September 1, 2015</a | ||
> | ||
</blockquote> | ||
</amp-twitter> | ||
``` | ||
|
||
[/example] | ||
|
||
_Example: Specifying a placeholder and a fallback_ | ||
|
||
[example preview="inline" playground="true" imports="amp-twitter" imports="amp-twitter"] | ||
|
||
```html | ||
<amp-twitter | ||
width="390" | ||
height="330" | ||
layout="responsive" | ||
data-tweetid="855178606556856320" | ||
> | ||
<blockquote placeholder> | ||
<p> | ||
What are 5 common misconceptions people often have about AMP? Find out on | ||
today's installment of Amplify: | ||
<a href="https://t.co/kaSvV8SQtI">https://t.co/kaSvV8SQtI</a> | ||
<a href="https://t.co/Cu9VYOmiKV">pic.twitter.com/Cu9VYOmiKV</a> | ||
</p> | ||
— AMP Project (@AMPhtml) | ||
<a href="https://twitter.com/AMPhtml/status/855178606556856320" | ||
>April 20, 2017</a | ||
> | ||
</blockquote> | ||
<div fallback> | ||
An error occurred while retrieving the Tweet. It might have been deleted. | ||
</div> | ||
</amp-twitter> | ||
``` | ||
|
||
[/example] | ||
|
||
## Attributes | ||
|
||
<table> | ||
<tr> | ||
<td width="40%"><strong>data-tweetid / data-momentid / data-timeline-source-type (required)</strong></td> | ||
<td>The ID of the Tweet or Moment, or the source type if a Timeline should be displayed. | ||
In a URL like https://twitter.com/joemccann/status/640300967154597888, <code>640300967154597888</code> is the tweet id. | ||
In a URL like https://twitter.com/i/moments/1009149991452135424, <code>1009149991452135424</code> is the moment id. | ||
Valid timeline source types include <code>profile</code>, <code>likes</code>, <code>list</code>, <code>collection</code>, <code>url</code>, and <code>widget</code>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>data-timeline-* (optional)</strong></td> | ||
<td>When displaying a timeline, further arguments need to be provided in addition to <code>timeline-source-type</code>. For example, <code>data-timeline-screen-name="amphtml"</code> in combination with <code>data-timeline-source-type="profile"</code> will display a timeline of the AMP Twitter account. | ||
For details on the available arguments, see the "Timelines" section in <a href="https://developer.twitter.com/en/docs/twitter-for-websites/javascript-api/guides/scripting-factory-functions">Twitter's JavaScript Factory Functions Guide</a>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>data-* (optional)</strong></td> | ||
<td>You can specify options for the Tweet, Moment, or Timeline appearance by setting <code>data-</code> attributes. For example, <code>data-cards="hidden"</code> deactivates Twitter cards. | ||
For details on the available options, see Twitter's docs <a href="https://developer.twitter.com/en/docs/twitter-for-websites/embedded-tweets/guides/embedded-tweet-parameter-reference">for tweets</a>, <a href="https://developer.twitter.com/en/docs/twitter-for-websites/moments/guides/parameter-reference0">for moments</a> and <a href="https://developer.twitter.com/en/docs/twitter-for-websites/timelines/guides/parameter-reference">for timelines</a>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>title (optional)</strong></td> | ||
<td>Define a <code>title</code> attribute for the component. The default is <code>Twitter</code>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>common attributes</strong></td> | ||
<td>This element includes <a href="https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes">common attributes</a> extended to AMP components.</td> | ||
</tr> | ||
</table> | ||
|
||
## Validation | ||
|
||
See [amp-twitter rules](https://github.com/ampproject/amphtml/blob/main/extensions/amp-twitter/validator-amp-twitter.protoascii) in the AMP validator specification. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,240 @@ | ||
--- | ||
$category@: social | ||
formats: | ||
- websites | ||
teaser: | ||
text: Displays a Twitter Tweet or Moment. | ||
experimental: true | ||
bento: true | ||
--- | ||
|
||
# Bento Twitter | ||
|
||
## Behavior | ||
|
||
The Bento Twitter component allows you to embed a Tweet or Moment for the specified Twitter ID. Use it as a web component [`<bento-twitter>`](#web-component), or a Preact/React functional component [`<BentoTwitter>`](#preact/react-Component). | ||
|
||
### Web Component | ||
|
||
You must include each Bento component's required CSS library to guarantee proper loading and before adding custom styles. Or use the light-weight pre-upgrade styles available inline. See [Layout and style](#layout-and-style). | ||
|
||
The examples below demonstrate use of the `<bento-twitter>` web component. | ||
|
||
#### Example: Import via npm | ||
|
||
[example preview="top-frame" playground="false"] | ||
|
||
Install via npm: | ||
|
||
```sh | ||
npm install @ampproject/bento-twitter | ||
``` | ||
|
||
```javascript | ||
import '@ampproject/bento-twitter'; | ||
``` | ||
|
||
[/example] | ||
|
||
#### Example: Include via `<script>` | ||
|
||
[example preview="top-frame" playground="false"] | ||
|
||
```html | ||
<head> | ||
<script src="https://cdn.ampproject.org/custom-elements-polyfill.js"></script> | ||
<!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element --> | ||
<style data-bento-boilerplate> | ||
bento-twitter { | ||
display: block; | ||
overflow: hidden; | ||
position: relative; | ||
} | ||
</style> | ||
<!-- TODO(wg-bento): Once available, change src to bento-twitter.js --> | ||
<script async src="https://cdn.ampproject.org/v0/amp-twitter-1.0.js"></script> | ||
<style> | ||
bento-twitter { | ||
width: 375px; | ||
height: 472px; | ||
} | ||
</style> | ||
</head> | ||
<bento-twitter id="my-tweet" data-tweetid="885634330868850689"> | ||
</bento-twitter> | ||
<div class="buttons" style="margin-top: 8px;"> | ||
<button id="change-tweet"> | ||
Change tweet | ||
</button> | ||
</div> | ||
|
||
<script> | ||
(async () => { | ||
const twitter = document.querySelector('#my-tweet'); | ||
await customElements.whenDefined('bento-twitter'); | ||
// set up button actions | ||
document.querySelector('#change-tweet').onclick = () => { | ||
twitter.setAttribute('data-tweetid', '495719809695621121') | ||
} | ||
})(); | ||
</script> | ||
``` | ||
|
||
[/example] | ||
|
||
#### Layout and style | ||
|
||
Each Bento component has a small CSS library you must include to guarantee proper loading without [content shifts](https://web.dev/cls/). Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles. | ||
|
||
```html | ||
<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-twitter-1.0.css"> | ||
``` | ||
|
||
Alternatively, you may also make the light-weight pre-upgrade styles available inline: | ||
|
||
```html | ||
<style data-bento-boilerplate> | ||
bento-twitter { | ||
display: block; | ||
overflow: hidden; | ||
position: relative; | ||
} | ||
</style> | ||
``` | ||
|
||
**Container type** | ||
|
||
The `bento-twitter` component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with `height`, `width`, `aspect-ratio`, or other such properties): | ||
|
||
```css | ||
bento-twitter { | ||
height: 100px; | ||
width: 100%; | ||
} | ||
``` | ||
|
||
#### Attributes | ||
|
||
<table> | ||
<tr> | ||
<td width="40%"><strong>data-tweetid / data-momentid / data-timeline-source-type (required)</strong></td> | ||
<td>The ID of the Tweet or Moment, or the source type if a Timeline should be displayed. | ||
In a URL like https://twitter.com/joemccann/status/640300967154597888, <code>640300967154597888</code> is the tweet id. | ||
In a URL like https://twitter.com/i/moments/1009149991452135424, <code>1009149991452135424</code> is the moment id. | ||
Valid timeline source types include <code>profile</code>, <code>likes</code>, <code>list</code>, <code>collection</code>, <code>url</code>, and <code>widget</code>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>data-timeline-* (optional)</strong></td> | ||
<td>When displaying a timeline, further arguments need to be provided in addition to <code>timeline-source-type</code>. For example, <code>data-timeline-screen-name="amphtml"</code> in combination with <code>data-timeline-source-type="profile"</code> will display a timeline of the AMP Twitter account. | ||
For details on the available arguments, see the "Timelines" section in <a href="https://developer.twitter.com/en/docs/twitter-for-websites/javascript-api/guides/scripting-factory-functions">Twitter's JavaScript Factory Functions Guide</a>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>data-* (optional)</strong></td> | ||
<td>You can specify options for the Tweet, Moment, or Timeline appearance by setting <code>data-</code> attributes. For example, <code>data-cards="hidden"</code> deactivates Twitter cards. | ||
For details on the available options, see Twitter's docs <a href="https://developer.twitter.com/en/docs/twitter-for-websites/embedded-tweets/guides/embedded-tweet-parameter-reference">for tweets</a>, <a href="https://developer.twitter.com/en/docs/twitter-for-websites/moments/guides/parameter-reference0">for moments</a> and <a href="https://developer.twitter.com/en/docs/twitter-for-websites/timelines/guides/parameter-reference">for timelines</a>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>title (optional)</strong></td> | ||
<td>Define a <code>title</code> attribute for the component. The default is <code>Twitter</code>.</td> | ||
</tr> | ||
</table> | ||
|
||
### Preact/React Component | ||
|
||
The examples below demonstrate use of the `<BentoTwitter>` as a functional component usable with the Preact or React libraries. | ||
|
||
#### Example: Import via npm | ||
|
||
[example preview="top-frame" playground="false"] | ||
|
||
Install via npm: | ||
|
||
```sh | ||
npm install @ampproject/bento-twitter | ||
``` | ||
|
||
```javascript | ||
import React from 'react'; | ||
import { BentoTwitter } from '@ampproject/bento-twitter/react'; | ||
import '@ampproject/bento-twitter/styles.css'; | ||
|
||
function App() { | ||
return ( | ||
<BentoTwitter tweetid="1356304203044499462"> | ||
</BentoTwitter> | ||
); | ||
} | ||
``` | ||
|
||
[/example] | ||
|
||
#### Layout and style | ||
|
||
**Container type** | ||
|
||
The `BentoTwitter` component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with `height`, `width`, `aspect-ratio`, or other such properties). These can be applied inline: | ||
|
||
```jsx | ||
<BentoTwitter style={{width: '300px', height: '100px'}} tweetid="1356304203044499462"> | ||
</BentoTwitter> | ||
``` | ||
|
||
Or via `className`: | ||
|
||
```jsx | ||
<BentoTwitter className='custom-styles' tweetid="1356304203044499462"> | ||
</BentoTwitter> | ||
``` | ||
|
||
```css | ||
.custom-styles { | ||
height: 100px; | ||
width: 100%; | ||
} | ||
``` | ||
|
||
### Props | ||
|
||
<table> | ||
<tr> | ||
<td width="40%"><strong>tweetid / momentid / timelineSourceType (required)</strong></td> | ||
<td>The ID of the Tweet or Moment, or the source type if a Timeline should be displayed. | ||
In a URL like https://twitter.com/joemccann/status/640300967154597888, <code>640300967154597888</code> is the tweet id. | ||
In a URL like https://twitter.com/i/moments/1009149991452135424, <code>1009149991452135424</code> is the moment id. | ||
Valid timeline source types include <code>profile</code>, <code>likes</code>, <code>list</code>, <code>collection</code>, <code>url</code>, and <code>widget</code>.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>card / conversations (optional)</strong></td> | ||
<td>When displaying a tweet, further arguments can be provided in addition to <code>tweetid</code>. For example, <code>cards="hidden"</code> in combination with <code>conversation="none"</code> will display a tweet without additional thumbnails or comments.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>limit (optional)</strong></td> | ||
<td>When displaying a moment, further arguments can be provided in addition to <code>moment</code>. For example, <code>limit="5"</code> will display an embedded moment with up to five cards.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>timelineScreenName / timelineUserId (optional)</strong></td> | ||
<td>When displaying a timeline, further arguments can be provided in addition to <code>timelineSourceType</code>. For example, <code>timelineScreenName="amphtml"</code> in combination with <code>timelineSourceType="profile"</code> will display a timeline of the AMP Twitter account.</td> | ||
</tr> | ||
<tr> | ||
<td width="40%"><strong>options (optional)</strong></td> | ||
<td>You can specify options for the Tweet, Moment, or Timeline appearance by passing in an object to the <code>options</code> prop. | ||
For details on the available options, see Twitter's docs <a href="https://developer.twitter.com/en/docs/twitter-for-websites/embedded-tweets/guides/embedded-tweet-parameter-reference">for tweets</a>, <a href="https://developer.twitter.com/en/docs/twitter-for-websites/moments/guides/parameter-reference0">for moments</a> and <a href="https://developer.twitter.com/en/docs/twitter-for-websites/timelines/guides/parameter-reference">for timelines</a>. Note: When passing in the `options` prop, make sure to optimize or memoize the object: | ||
<code> | ||
const TWITTER_OPTIONS = { | ||
// make sure to define these once globally! | ||
}; | ||
|
||
function MyComponent() { | ||
// etc | ||
return ( | ||
<Twitter optionsProps={TWITTER_OPTIONS} /> | ||
); | ||
}</code></td> | ||
|
||
</tr> | ||
<tr> | ||
<td width="40%"><strong>title (optional)</strong></td> | ||
<td>Define a <code>title</code> for the component iframe. The default is <code>Twitter</code>.</td> | ||
</tr> | ||
</table> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters