Transformer Rules

Overview

A valid Instant Article is comprised of a subset of standard HTML tags, detailed in the Format Reference. Adhering to these restrictions ensures that content renders reliably and performant on mobile devices within Facebook but naturally constrains what is allowed within the markup. What's more, the hierarchy of the permitted tags also matters.

For example, to render text bold in an Instant Article, the <strong> tag must be used. But if your content makes use of <b> as a means to stylize text bold, you would find that your source markup is valid HTML, but ultimately is not valid Instant Articles markup.

The Transformer of this SDK helps mitigate these constraints by converting any markup into Instant Articles markup, and it's the Transformer Rules which instructs it on how to do so. Collectively, these rules form a mapping between elements in the source markup and what they should be transformed into within the generated Instant Article. Analogous to a car, if the Transformer were the engine powering the conversion of the markup, the Transformer Rules would be the driver.

Many example rules have been defined which aim to cover most common scenarios. Additional rules can be added to amend or override existing ones.

Transformer Rule Configuration

At a high level, configuring a Transformer Rule involves three steps:

  1. Rule Selector: Identifying a source element in your markup
  2. Rule Class: Associating it with an existing Transformer Rule Class in a permitted context
  3. Rule Properties: Defining any value for attributes on the transformed element that the Rule Class expects (not always needed)

Take the following example which would cause text within <span class="bold"> to be stylized bold in the generated Instant Article.

// Transformer Rule associating <span class="bold"> to the `BoldRule` class
{
  "class": "BoldRule",
  "selector": "span.bold"
  //"properties": {} // Not needed since the `BoldRule` class has no properties
}

Note: the resulting markup within the Instant Article for the BoldRule class is the <b> tag; the fact that this detail is abstracted by the Transformer is intentional.

Caveat: the example above makes no mention of context. It turns out, the rule above would only work as expected if it were being processed within a particular parent context of the generated document. Read more about rule context.

Rule Selector

The selector is used to identify elements in the source markup. Both CSS selectors and Xpath are supported formats.

// Identical rules using the different selector types.
{
  "class": "BoldRule",
  "selector" : "span.bold" // CSS Selector
}

{
  "class": "BoldRule",
  "selector" : "//span[class=bold]" // Xpath Selector
}

Note: there are some limitations to the CSS selectors.

Rule Properties

Some Transformer Rules have properties who's value are obtained from content in the source markup. In the configuration of your rule, use a key called properties to define all the relevant properties allowed for the particular rule. Use the name of the property as the key for an object of key-value pairs explained below. For example:

{
 "class": "AnchorRule",  // Rule class
 "selector": "a",        // Matching source element (CSS selector)
 "properties" : {        // All supported properties

   "anchor.href" : {     // Name of property
     "type" : "string",
     "selector" : "a",   // Additional selector specific to this property (scoped within the Rule's selector above)
     "attribute": "href" // Attribute of the property's selector to use as the value for this property (optional)
   }

 }
}

The content intended to be used for the value of the property isn't specified within the rule verbatim; rather, the rule instructs the transformer where in the source element the value is located, again by use of its own selector. An additional option called attribute may be used to specify that the property's value originate from an attribute on the element; if this attribute option isn't present, the inner contents of the element identified by selector is used.

The key-value pairs allowed for a property are explained below:

Key Notes

selector

Required. A CSS selector (run within the scope of the rule's selector) for targetting an element in the source markup from where the value of the property should be obtained from.

attribute

Required only if type is "exists".



The name of the attribute on the element, identified by the value in selector, whose value you want to use as the content for the property of the Transformer Rule.



When type is "exists", the value of the property will be true simply by the presence of the attribute, regardless of its value.

Examples

For example, take the standard case of configuring the transformer to recognize anchor tags, such as <a href="http://example.com"> for generating links with an Instant Article:

// Source Markup: <a href="http://example.com" target="_blank">
{
 "class": "AnchorRule",
 "selector": "a",
 "properties" : {

   "anchor.href" : {
     "type" : "string",
     "selector" : "a",
     "attribute": "href"
   }

 }
}
// Generated Markup: <a href="http://example.com">

As a contrived example, here's a rule which would transform source markup formatted as such: <span class="custom-href" data-link="http://example.com"> into the same link within the generated Instant Article:

// Source Markup: <span class="custom-href" data-link="http://example.com">
{
 "class": "AnchorRule",
 "selector": "span.custom-href",
 "properties" : {

   "anchor.href" : {
     "type" : "string",
     "selector" : "span.custom-href",
     "attribute": "data-link"
   }

 }
}
// Generated Markup: <a href="http://example.com">

Rule Class

A Rule Class is simply a pre-determined link to a valid Instant Article component. It defines supported properties and permitted context(s) for the Rule.

Rule Context

The hierarchal nature of an HTML document implies that an element always exists within the context of a parent element. A similar hierarchy is built during a document's transformation into an Instant Article giving each individual element a context. This context plays an important role for the Transfer Rules since, along with the selector, it is a condition that must be matched before a rule is executed.

As the Transformer traverses through the entire HTML document, it attempts to execute all of rules for every tag element it encounters. But two criteria need to be met each time:

  1. the selector of the rule must match the current element
  2. the context in which the rule would run must match one of the allowed context(s) of the rule class

In other words, as the Transformer progresses, it uses the rules to build a hierarchy of transformed elements, giving context to each subsequent rule. Rules are only permitted to execute within an allowed context defined for the Rule Class is uses.

Available Rule Classes

Listed below are all the available Rule Classes, along with their supported properties and permitted context(s), whereby source markup can be mapped to a valid Instant Article component via the selector of the Rule Class. They are arranged into logical groups by function. For the properties, assume type of "string" unless noted otherwise.

Formatting

Rule Class Properties Permitted Context Notes

AnchorRule

anchor.href


anchor.rel

TextContainer

BoldRule

TextContainer

ItalicRule

TextContainer

LineBreakRule

TextContainer

Layout

Rule Class Properties Permitted Context Notes

BlockquoteRule

InstantArticle

H1Rule

type = "exists" for one of either text alignment options:


op-left


op-center


op-right



type = "exists" for one of either vertical position options:


op-vertical-below


op-vertical-above


op-vertical-center



type = "exists" for one of either size options:


op-size-medium


op-size-large


op-size-extra-large

Caption, InstantArticle

Used to specify the Header value for multiple Element types.

H2Rule

type = "exists" for one of either text alignment options:


op-left


op-center


op-right



type = "exists" for one of either vertical position options:


op-vertical-below


op-vertical-above


op-vertical-center

Caption, InstantArticle

HeaderRule

InstantArticle

ListElementRule

InstantArticle

ListItemRule

ListElement

ParagraphRule

InstantArticle

PullquoteCiteRule

Pullquote

PullquoteRule

InstantArticle

SponsorRule

sponsor.page_url, type: string

Header

The Sponsor rule is related to Branded Content so the URL must be from a Facebook page, this way the image will be fetched correctly.

Graphic

Rule Class Properties Permitted Context Notes

AdRule

ad.url


ad.height


ad.width


ad.embed

InstantArticle

AnalyticsRule

analytics.url


analytics.embed

InstantArticle

GeoTagRule

map.geotag

Image, Video, Map

Used to specify the Geotag value for multiple Element types.



Multiple definitions of the same map.geotag property are allowed and each one will be processed independently.

HeaderAdRule

ad.url


ad.height


ad.width


ad.embed

Header

HeaderImageRule

image.url

Header

ImageRule

image.url


image.like


image.comments

InstantArticle

InteractiveRule

interactive.iframe


interactive.url


interactive.height


no-margin


column-width

InstantArticle

This rule can be used to transform Social embed content (like Facebook comments, Twitter, Instagram), or any content that doesn't have an Instant Article component transform to.

MapRule

InstantArticle

Media

Rule Class Properties Permitted Context Notes

AudioRule

audio.url


audio.title


audio.autoplay


audio.muted

Audible

RelatedArticlesRule

related.title

InstantArticle

Wrapper for a Related Article component

RelatedItemRule

related.sponsored


related.url

RelatedArticles

For individual articles within a RelatedArticlesRule

SlideshowImageRule

image.url


caption.title


caption.credit

Slideshow

For individual images within a SlideshowRule

SlideshowRule

InstantArticle

Wrapper for a Slideshow component

VideoRule

video.url


video.type


video.playback


video.controls


video.like


video.comments



type = "exists" for any of the video player options:


loop


data-fade



one of the following:


aspect-fit


aspect-fit-only


fullscreen


non-interactive

InstantArticle

Article Structure

Rule Class Properties Permitted Context Notes

AuthorRule

author.url


author.name


author.description


author.role_contribution

Header

CaptionCreditRule

type = "exists" for one of either text alignment options:


op-left


op-center


op-right



type = "exists" for one of either vertical position options:


op-vertical-below


op-vertical-above


op-vertical-center

Caption

CaptionRule

caption.default



type = "exists" for one of either text alignment options:


op-left


op-center


op-right



type = "exists" for one of either vertical position options:


op-vertical-below


op-vertical-above


op-vertical-center



type = "exists" for one of either size options:


op-size-medium


op-size-large


op-size-extra-large

Map, Image, Interactive, Slideshow, SocialEmbed, Video

Used to specify the Caption value for multiple Element types.



Multiple definitions of the same caption.default property are allowed and each one will be processed independently.

FooterRelatedArticlesRule

related.title

Footer

FooterRule

InstantArticle

HeaderKickerRule

Header

HeaderSubTitleRule

Header

HeaderTitleRule

Header

ParagraphFooterRule

Footer

TimeRule

article.time


article.time_type

Header

Special

Rule Class Properties Permitted Context Notes

IgnoreRule

(any)

This rule class will effectively strip out an element tag which matches the associated selector of the rule.

PassThroughRule

(any)

This rule class instructs the Transformer to not process any transformation on element tags which match the associated selector of the rule.

InstantArticleRule

article.canonical


article.charset


article.markup.version


article.auto.ad

InstantArticle

This is the entry point, or root node, of the hierarchy.

TextNodeRule

TextContainer