Scripting: Factory Functions

By using Twitter JavaScript, you agree to the Developer Rules of the Road.

If you’re integrating your site with Twitter using Twitter for Websites and Web Intents, you can dynamically generate widgets using JavaScript functions.

Twitter for Websites products—Tweet buttons, Follow buttons, embedded Tweets and timelines—are all loaded using a JavaScript utility named widgets-js. When adding a Twitter widget to your page, this JavaScript file is included in the HTML embed code, or you can directly include https://platform.twitter.com/widgets.js in your page. (See the TFW set-up documentation for a recommended code snippet.)

By default, widgets-js will find mark-up in a page and convert basic, functional mark-up into rich interactive widgets. In addition, there are a number of functions of widgets-js that allow you to work with Twitter content dynamically:

Creating widgets at run-time with factory functions

Widgets can be generated at run-time, without requiring an HTML embed code. A set of factory functions can generate any widget type:

• twttr.widgets.createShareButton
• twttr.widgets.createFollowButton
• twttr.widgets.createHashtagButton
• twttr.widgets.createMentionButton
• twttr.widgets.createTimeline
• twttr.widgets.createTweet

Buttons

createShareButton, createFollowButton, createHashtagButton, and createMentionButton take similar arguments.

Primary Argument

The first argument is required, and is unique to the button type. Provide a string representing one of:

• url: The URL to be shared.
• screen_name: The screen_name of a user to be followed, or mentioned.
• hashtag: Hashtag to be Tweeted and displayed on the button.

Additional Arguments:

• target: Required. The element in which to render the widget.
• options: Optional. An object hash of additional options to configure the widget.

Note that widgets usually render as iframe elements. When an iframe is moved within the DOM the browser will reload its content. For buttons this can waste bandwidth, while for Tweets and timelines this will cause dynamically injected content to be lost. Use the target argument to render widgets into their final location in a page. If you need to delay the display of a widget, use CSS to position the widget off-screen until needed.

Every create function returns a Promise. You can execute code after a widget has been created by passing a callback to:

twttr.widgets.createFoo()
.then(function (element) {
  console.log("Widget created.")
 });

When fulfilled, the promise will pass a reference to a newly created widget element to the chained callback.

Examples:

Create a share button for a URL:

twttr.widgets.createShareButton(
  'https://dev.twitter.com/',
  document.getElementById('new-button'),
  {
    count: 'none',
    text: 'Sharing a URL using the Tweet Button'
  }).then(function (el) {
    console.log("Button created.")
  });

Create a Follow button for a user:

twttr.widgets.createFollowButton(
  'endform',
  document.getElementById('new-button'),
  {
    size: 'large'
  }).then(function (el) {
    console.log("Follow button created.")
  });

Tweets

createTweet takes the ID for a Tweet, and then the same additional arguments as for buttons.

Arguments

• tweetId: The ID of a Tweet to be rendered. (This should be provided as a String, since Twitter IDs are generated from 64-bit integers, and JavaScript integers are limited to 53 bits.)
• target: Required. The element in which to render the widget.
• options: Optional. A hash of additional options to configure the widget.

Examples:

Create an embedded Tweet for a Tweet from the US Department of Interior:

twttr.widgets.createTweet(
  '511181794914627584',
  document.getElementById('first-tweet'),
  {
    align: 'left'
  })
  .then(function (el) {
    console.log("@ev's Tweet has been displayed.")
  });

Timelines

createTimeline takes the ID for a timeline, as obtained by first creating a timeline in your widget settings. Additional arguments are consistent with embedded Tweets.

Arguments

• widgetId: The ID of a timeline widget to be rendered.
• target: Required. The element in which to render the widget.
• options: Optional. A hash of additional options to configure the widget.

Examples:

Create a timeline widget:

twttr.widgets.createTimeline(
  '123456',
  document.getElementById('timeline'),
  {
    width: '450',
    height: '700',
    related: 'twitterdev,twitterapi'
  }).then(function (el) {
    console.log("Embedded a timeline.")
  });