Skip to content

Commit

Permalink
📖 bento-twitter documentation (#35847)
Browse files Browse the repository at this point in the history 
* Copy to 0.1 subdir

* Edit existing documentation

* Create readme
  • Loading branch information
@caroqliu @honeybadgerdontcare
caroqliu authored and honeybadgerdontcare committed Aug 31, 2021
1 parent 42ab651 commit 735e5ad
Show file tree
Hide file tree
Showing 3 changed files with 377 additions and 1 deletion.
131 changes: 131 additions & 0 deletions extensions/amp-twitter/0.1/amp-twitter.md
View file
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>
&mdash; 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&#39;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>
&mdash; 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.
240 changes: 240 additions & 0 deletions extensions/amp-twitter/1.0/README.md
View file
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>
7 changes: 6 additions & 1 deletion extensions/amp-twitter/amp-twitter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
$category@: social
formats:
- websites
- stories
teaser:
text: Displays a Twitter Tweet or Moment.
experimental: true
bento: true
---

# amp-twitter
Expand All @@ -29,6 +30,10 @@ Here's an example of a basic embedded Tweet:

[/example]

### Standalone use outside valid AMP documents

Bento AMP allows you to use AMP components in non-AMP pages without needing to commit to fully valid AMP. You can take these components and place them in implementations with frameworks and CMSs that don't support AMP. Read more in our guide [Use AMP components in non-AMP pages](https://amp.dev/documentation/guides-and-tutorials/start/bento_guide/). To find the standalone version of `amp-twitter`, see [`bento-twitter`](./1.0/README.md).

## 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.
Expand Down

0 comments on commit 735e5ad

Please sign in to comment.