Social metadata (bottle_utils.meta)

This module provides classes for working with social metadata (Facebook, Google+, Twitter).

How it works

There are two flavors of metadata classes, SimpleMetadata and Metadata. Both render the title tag and description met tag, while the latter also renders a full set of social meta tags used by Facebook, Google+, and Twitter.

Using any of the two classes, you normally instantiate an object passing it metadata as constructor arguments, and then simply use the objects as string values in the template. You can also call the render() method on the object, but that is redundant except in rare cases where str type is expected.

Example usage is provided for both of the classes.

Warning

Authors of this module use social metadata only very rarely. As such, the features found in this module may not always be up to date. Please file issues you find with the social metadata support to the GitHub issue tracker.

Classes

class bottle_utils.meta.MetaBase[source]

Base class for metadata. This class is a simple placeholder to collect base functionality for various subclasses.

Currently, the only functionality this base class provides is calling render() method when __str__() magic method is called on the class.

render()[source]

Render the meta object into HTML. In the base class this method renders to empty string.

class bottle_utils.meta.Metadata(title=u'', description=u'', thumbnail=u'', url=u'')[source]

Complete set of social meta tags. This class renders a complete set of social meta tags including schema.org properties, OpenGraph tags, and Twitter Cards markup.

The meta tags are only rendered for the arguments that are specified (i.e., one or more of the title, description, thumbnail, url). The arguments map to common properties that have the following meanings:

  • title: page title
  • description: page description (usually used as message shown next to the post on a social network)
  • thumbnail: (also known as ‘image’) appears as a thumbnail or banner alongside the post on a social network
  • url: canonical URL of the page (usually an URL that does not include any query parameters that change it’s appearance or generate unnecessary data, such as Google Analytics campaign tags, etc), which is used instead of the URL that was shared

To render social tags, simply instantiate an object using meta data of your choosing and render the object in template (treat is as a string).

Here is an example of what it may look like in a handler function:

@app.get('/my/shareable/page')
@bottle.view('page')
def handler():
    m = Metadata(title='My page',
                 description='A page about sharing',
                 thumbnail='/static/images/awesome.png',
                 url=bottle.request.path)
    return dict(meta=m)

And here is a template:

<html>
    <head>
        <meta charset="utf-8">
        {{! meta }}
    </head>
    <body>
    ....
    </body>
</html>

Note

In template engines that support automatic escaping of HTML, you need to suppress escaping. For instance, in SimpleTemplates, using {{! }} instead of {{ }} accomplishes this.

This class does not render any of the other numerous tags (authorship tags, for instance). However, the instance methods it provides can be used to render them.

For example, to render a Twitter creator tag in a template that has access to any instance of this class:

{{! meta.twitterprop('creator', '@OuternetForAll') }}

Note

When it comes to thumbnails and canonical URLs, the social networks usually expect to see a full URL (including scheme and hostname). However, it may not feel right to hard-code these things. This class automatically converts paths to full URLs based on request data, so passing paths is fine.

itemprop(name, value)[source]

Render schema.org itemprop meta tag. This method renders a schema.org itemprop meta tag which uses the itemprop attribute to designate the name of the tag.

This form is used by Google, but it’s otherwise an open standard for semantic markup. This method only renders meta tags, and not every other kind of markup that schema.org uses.

The arguments are rendered into the following markup:

<meta itemprop="$name" content="$value">
static make_full(url)[source]

Convert an input to full URL if not already a full URL. This static method will ensure that the specified url is a full URL.

This method only checks if the provided URL starts with ‘http’, though, so it is possible to trick it using a path that looks like ‘httpfoo’: it is clearly not a full URL, but will be treated as one. If the input value is user-supplied, please perform a more through check.

Under the hood, this method uses bottle_utils.common.full_url() to convert paths to full URLs.

Parameters:url – path or full URL
Returns:full URL as per request data
nameprop(namespace, name, value)[source]

Render a generic name property. This method renders a generic name property meta tag that uses name attribute to designate the tag name.

Each tag name consist of namespace and name parts. Most notably, Twitter Card markup uses this form.

The arguments are rendered like this:

<meta name="$namespace:$name" content="$value">
ogprop(name, value)[source]

Renders OpenGraph meta tag. This method renders a property meta tag that uses ‘og’ namespace.

The arguments are rendered like this:

<meta property="og:$name" content="$value">
prop(namespace, name, value)[source]

Render a generic property meta tag. This method renders a generic property meta tags that uses property attribute to designate the tag name.

Each tag name consists of two parts: namespace and name. Most notably, OpenGraph uses this form with ‘og’ namespace.

The arguments are rendered like this:

<meta property="$namespace:$name" content="$value">
render()[source]

Render the meta object into HTML.

twitterprop(name, value)[source]

Renders Twitter Card markup. This method renders Twitter Card markup meta data. That is a name property meta tag with ‘twitter’ namespace.

The arguments are rendered like so:

<meta name="twitter:$name" content="$value">
class bottle_utils.meta.SimpleMetadata(title=u'', description=u'')[source]

The basic (classic) metadata. This class is used to render title tag and description meta tag.

Both title and description are option. If neither is supplied, it is rendered into empty string.

Here is a simple example handler:

@app.get('/my/shareable/page')
@bottle.view('page')
def handler():
    m = SimpleMetadata(title='My page',
                       description='A page about sharing')
    return dict(meta=m)

In the template, simply render this object in <head> section where you would normally have the <title> tag.:

<html>
    <head>
        <meta charset="utf-8">
        {{! meta }}
    </head>
    <body>
    ...
    </body>
</html>

This renders the following tags:

<title>My Page</title>
<meta name="description" content="A page about sharing">

Note

In template engines that support automatic escaping of HTML, you need to suppress escaping. For instance, in SimpleTemplates, using {{! }} instead of {{ }} accomplishes this.

static meta(attr, name, value)[source]

Render a generic <meta> tag. This function is the basis for rendering most of the social meta tags.

The arguments are rendered like this:

<meta $attr="$name" content="$value">
render()[source]

Render the meta object as HTML.

simple(name, value)[source]

Render a simple ‘name’ meta tag. This function renders a meta tag that uses the ‘name’ attribute.

The arguments are rendered like this:

<meta name="$name" content="$value">