Sharing links on Facebook and Twitter is a huge traffic driver for websites. We’ve all pasted a link into that little box and watched that preview magically appear, but how does it know what to put in there? The answer is ‘Well, it does kind of, but not really for sure unless we tell it.’ This is not to say that it’s completely dumb – it is right a pretty good amount of the time; but why not customize it if we can?

The magic is in Open Graph and Twitter Card tags. Before we start, though, there’s an important caveat: This only works with public pages, since the page needs to be accessible to Twitter and Facebook to generate the previews.


David Walsh provides a very good summary of Open Graph tags in this blog post; and just at a glance, you’ll see some things we can easily pull in from Velocity. If you plug a page’s URL into Facebook’s Open Graph Object Debugger, you’ll see how Facebook sees it, complete with helpful suggestions on how to tweak what displays. The only fields really required are og:type (which in our case will almost certainly be website) and og:title, but the rest are easy enough to add that there’s no reason not to while we’re in the neighbourhood. (While we’re at it, we’ll also set the canonical URL with a link tag to prevent the debugger from complaining.)

If there’s no <meta descripton=""> tag on a page, or if it’s empty, then Facebook will grab the first thing it finds that’s over 120 characters long and wrapped in <p> tags, which may not be what you want to share. The ‘Description’ field in the Control Panel under Site Pages > [Page] > SEO populates the <meta description=""> tag, and we can re-purpose that data for the Open Graph tag. og:image is a bit trickier – Facebook usually does a pretty good job of grabbing an image for you; but if you want full control, you can specify that here. The site logo is easy enough to pull in from Velocity; so if you don’t trust the crawler’s judgement, it’s a good idea if you’re looking for a ‘set it and forget it’ solution.


Twitter Cards are previews of links added to tweets, similar to what Facebook does. There are several different kinds of cards, so you can choose the one that suits your particular purpose. For this example, we’ll use the Summary card, which provides a basic preview similar to Facebook’s.

Unsurprisingly, this also means that we can re-use a lot of the fields we brought in for Facebook in the form of Cards markup tags. The example from the documentation uses these fields:

  • twitter:card: The type of card
  • twitter:site: The Twitter username associated with the site, like ‘@liferay’
  • twitter:creator: The Twitter username of the page content’s creator
  • twitter:title: The title of the page (Required)
  • twitter:description: A brief summary of the page’s content (Required)
  • twitter:image: An image associated with the content

We probably won’t want to change the type of card frequently, if at all, so we can safely hard-code that. (It defaults to summary, but it doesn’t hurt to include it anyway.) twitter:title and twitter:description have the same content as the Open Graph tags we pulled in earlier – in fact, if they’re not present, they’ll actually fall back to the content of the matching Open Graph tags – so most of our work is already done! The documentation cautions you to not use an image that appears on multiple pages, like a logo, for twitter:image, so I’ll leave that decision up to you. (Hint: if the tag isn’t there, it too will fall back to the Open Graph tag.)

The whole point of posting on Twitter, though, is presumably to drive Twitter engagement; so it would be helpful to add your Twitter username. The easiest way to do this is with a quick expando. In the Control Panel, go to Custom Fields (6.1) or Configuration > Custom Fields (6.2) In this case, I’ll assume we want to associate the same Twitter username with the entire site; so under Site, add a Text field called twitter-username.

Go to Sites > [Site Name] > Custom Fields (6.1) or Configuration > Site Settings > Custom Fields (6.2) and add the username to the field. Call it in the theme as we do below, and you’re ready to go! It’s worth mentioning that Twitter also has a Card Validator, much like Facebook’s service, so you can check your work.

The Markup

Herewith, a set of auto-populated tags that you can snugly secure into the <head> of your portal_normal.vm and rest safe in the knowledge that your audience on Facebook and Twitter will see your site the way you want them to see it:

<meta property="og:site_name" content="$site_name" />
<meta property="og:url" content="$themeDisplay.getPortalURL()$themeDisplay.
    getURLCurrent()" />
<meta property="og:type" content="website" />
<meta property="og:title" content="$the_title" />
<meta property="og:image" content="$themeDisplay.getPortalURL()$site_logo" />
<meta property="og:description" content="$themeDisplay.getLayout().
    getDescriptionCurrentValue()" />

<meta name="twitter:card" content="summary" />
<meta name="twitter:site" description="$themeDisplay.getScopeGroup().
    getExpandoBridge().getAttribute('twitter-username')" />
<meta name="twitter:title" content="$the_title" />
<meta name="twitter:description" content="$themeDisplay.getLayout().
    getDescriptionCurrentValue()" />

<link rel="canonical" href="$themeDisplay.getPortalURL()$themeDisplay.
    getURLCurrent()" />

Thanks to Abdul Alshberi for extra legwork and testing!

Share This