-
Notifications
You must be signed in to change notification settings - Fork 3.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
📖 bento-twitter
documentation
#35847
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
..the specified Tweet ID?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like this is a pre-existing issue, I'll fix in another PR (mostly because I merged this one before seeing your comment 😅 ).