Setting up @Anywhere is easy. Let's start with a simple use case. Hovercards are a feature of Twitter.com that are also available via @Anywhere. Let's walk through how you can put Hovercards on your site.
If you already have Twitter usernames mentioned in your web site or application, Hovercards provide your users with a small, context-aware tooltip that provides access to data about a particular Twitter user.
Goto http://dev.twitter.com/anywhere and register your application
- When you call the anywhere() method, you pass in a callback that receives a Twitter API client instance as its only argument - By convention we name that argument "T" - All @Anywhere functionality is hung off of the API client instance ("T")
- T is a function that you can use to scope @Anywhere functionality - By default all @Anywhere functionality operates on the body of the document
- Over the past couple of years CSS selectors have become the preferred means of accessing elements in the DOM
- So, with @Anywhere you can pass a CSS selector to T to limit the scope of where the @Anywhere to a particular element or elements in the page
- This makes using @Anywhere easy because it is building on techniques most developers are already familiar with
Another design goal of @Anywhere was that it needed to be fast. This was especially important since optimizing client-side/in-browser performance has been a real priority in recent years. We didn't want developers to worry that by using/including @Anywhere they'd be making some sacrifices regarding performance.
- There is a one to many relationship between anywhere.js and @Anywhere client instances
- You only need to include the anywhere.js file once, and can then create any number of @Anywhere client instances (via twttr.anywhere()) per page as illustrated in this example
- All @Anywhere client instances share the same script resources
- Additionally, feature-specific resources are loaded on-demand
- For example, the TweetBox code is not loaded into the page until the tweetBox() method is called
- Because @Anywhere features are loaded on demand, it makes it very easy to defer the loading and rendering of a given @Anywhere feature until it is request the by the user
- In this example, the TweetBox will be not be loaded and rendered until the user clicks the comment button.
- @Anywhere loads its dependencies into an iframe to keep our scripts sandboxed from those of the host site
- @Anywhere widgets run in an iframe to prevent styles of the host site bleeding in
- Under the hood @Anywhere is simply using the Twitter API. Therefore, there is functionality in @Anywhere that doesn't require the user to auth. We've seen one example of this already: being able to view a user's profile data in a Hovercard.
- For those things that DO require require the user to auth, @Anywhere handles all that for you (completely client-side auth)
- In addition you can piggy back on our auth, here's how
- @Anywhere provides an authComplete and signOut event that can be used to determine whether or not users of your web site or web application have logged in to Twitter and authorized your application for access.
- Using the "Connect with Twitter" button it is possible to bind listeners for both the authComplete and signOut events via an object literal passed to the connectButton method. Listeners for the authComplete are passed the logged in user as a single argument.
The connect flow is as follows:
1. Connect launches popup
2. User asked either to: - Auth (if logged in to Twitter) - Login + auth (if not logged in)
3. Single-level of permissions (for simplicity for the user and dev)
4. Tokens are good for 2 hours and are automatically refreshed as long as the user is logged into Twitter
- @Anywhere authentication is via OAuth 2.0
- Not fully implemented all profiles, just what we needed for @Anywhere
- Production, non @Anywhere implementations should continue to use the OAuth 1 endpoint until our OAuth 2.0 is deployed
- Once we have our OAuth 2.0 endpoint deployed we'll provide a complete migration plan
- The isConnected() method can be used to determine if the user has already logged in has authorized your web site or application. When the user is connected the "currentUser" property can be used to retrieve information about the logged-in user.
- The user object has a data method that can be passed a string representing the property to retrieve.
- This example illustrates how to use jQuery and @Anywhere to conditionally display either a Connect with Twitter button, or the user's screen name and profile image if they've already authenticated.
- This example is the same as the previous slide, but uses YUI 3's method of determining when the page is ready
The authComplete and signOut events are also globally accessible on the Twitter API client instance (T), allowing you to listen for them when triggered by any @Anywhere functionality.
@Anywhere provides a convenient way to link Twitter usernames found in your web site or application back to a user's profile page on Twitter.com. A Twitter screen name is an '@' symbol followed by 1 to 20 alphanumeric characters, including underscores ("_"). @ev or @biz and two examples of Twitter username.
- To automatically linkify Twitter usernames, simply call T.linkifyUsers()
- Calling linkifyUsers in this way would attempt to linkify all potential Twitter users in the <body> of the page.
- To limit the scope of what is linkified, simply pass a CSS selector to the Twitter API client (T).
- For example, to linkify only Twitter usernames found in an element with the id of "main", pass the selector "#main" to T.
API is consistent across each @Anywhere util and widget
- Specify the element(s) via selector (omitting selector == apply to <body>)
- Call method the collection
- Each has options - specified via an object literal
- Developer documentation includes all configuration options for each @Anywhere feature along with working examples
Follow buttons make it easy to provide users of your site or application with a way to follow users on Twitter. Adding Follow Buttons to your web site or web application is easy: simply call T passing in a selector indicating where you want the Follow Button to appear, and call the followButton method specifying a Twitter username.
The Tweet Box allows Twitter users to tweet directly from within your web site or web application. To use the Tweet Box, call T passing in a selector indicating where you want the Tweet Box to appear, and call the tweetBox method.
- All API methods are asynchronous
- Can specify a success callback as the second argument to any API method call
If you wish to listen for both success and error, you can specify those listeners via an object literal passed as a second argument to any API method call
Because AJAX operations are asynchronous, calls need to nested
When declaring a version number, specifying the version as a whole number will result in @Anywhere using the latest available version for that major version number. For example, if the current available version of @Anywhere is version 1.2.1, specifying a version of 1 will result in @Anywhere using version 1.2.1.
It is also possible to use @Anywhere by declaring a specific version number. Indicating a specific version number will ensure your @Anywhere integration remains on a desired version regardless of the latest available version.
- You can pass the version of @Anywhere as the first argument to the anywhere() method
- The primary use case for passing the version as an argument to the anywhere() would be running two different versions of @Anywhere side-by-side on the same page
- Can create multiple instances of the @Anywhere client
- Can target an @Anywhere client instance at another window
- All instances of the same version share resources
Complete @Anywhere documentation is available at http://dev.twitter.com/anywhere/begin
Developer support provided via the twitter-dev-anywhere Google Group
@Anywhere bugs can be filed via Google Code: http://code.google.com/p/twitter-api/issues/list
Of course you can also find support for @Anywhere via Twitter by following @Anywhere