Understanding Instant Articles Transformation Rules

Posted on: Feb 11, 2018 by admin

Instant articles is one of the latest features of facebook. They consists in publishing web articles directly in facebook. This articles shows only on facebook mobile aplications and the main advantage of this articles is page load.

You can create this articles even from your website cms. You will need to create the structure of html along with your content and publish it in facebook page through an facebook application.

In order to publish them facebook need to transform your html into their structure through some transformation rules, so they will know when you want to publish an image, gallery or an iframe. This transformation rules are saved in a json file.

The default transformer rules file look like this: 
transformation_rules.json

 

So how this works?

Let's explain a simple example:

{
"class": "BoldRule",
"selector" : "b"
}

With this piece of code we are telling facebook that all "b" elements within our html will apply class BoldRule in facebook article.

What are some classes that we can use?

Class "PassThroughRule" means that this tag will not be transformed.  Usually with this class will be elements like head, titles, body, style and script.

Class "ItalicRule" means that all elements with this class will be italic. 

Class "BoldRule" means that all elements with this class will be Bold. 

Class ParagraphRule" means that all elements with this class will be treated as paragraphs. The element under this class doesn't have to be always "p". We can choose that a div  with a specified class to be treated as a paragraph. Here is an example:

{
"class": " ParagraphRule ",
"selector" : "div.paragraph"
}

In this example we are telling facebook to treat as paragraph all our divs that have class paragraph.

Class "HeaderTitleRule" specifies an element for article title.

Class "HeaderSubTitleRule" specifies an element for article SubTitle.

Class "H2Rule" specifies an element to be treated as "h2". This is the same for all other heading rules. "h1" - "h6".

Class "SlideshowRule " means that every element with this class will be treated as an image gallery.

Class "SlideshowImageRule " represent images inside galleries.

 

Now let's try to create rules for an image gallery.

{
  "class": "SlideshowImageRule",
  "selector" : "figure.slideshow_image",
  "properties" : {
  "image.url" : {
  "type" : "string",
  "selector" : "img",
  "attribute": "src"
  }
  }
}, 
{
  "class": "SlideshowRule",
  "selector" : "figure.slideshow"
}

From the above code our html should look like this:
 

<figure class="op-slideshow slideshow">
<figure class="slideshow_image"><img src="img.png" /></figure>
<figure class="slideshow_image"><img src="img.png" /></figure>
<figure class="slideshow_image"><img src="img.png" /></figure>
<figure>

Every figure element with "slideshow" class represent an image gallery and every figure element with class "slideshow_image" inside the slideshow represent a single image of that gallery. We can change classes in our html as we want but we have to declare them in transformation rules json file.

 

Now we want to add a youtube embed inside an instant article. How can we structure our HTML?

First we need to add a rule to our json file. Class for adding iframe in instant articles is called InteractiveRule

{
  "class": "InteractiveRule",
  "selector" : "div.pa-interactive",
  "properties" : {
  "interactive.url" : {
  "type" : "string",
  "selector" : "iframe",
  "attribute": "src"
  },
  "interactive.width" : {
  "type" : "int",
  "selector" : "iframe",
  "attribute": "width"
  },
  "interactive.height" : {
  "type" : "int",
  "selector" : "iframe",
  "attribute": "height"
  },
  "interactive.iframe" : {
  "type" : "children",
  "selector" : "iframe"
  },
  "interactive.caption" : {
  "type" : "element",
  "selector" : "figcaption"
  }
  }
  }

 

With this rule, every element with class "pa-interactive" will be treated as wrapper element of an iframe. In this rule we can add a specific width and height of the iframe as well as iframe element.
Our html should look like this in order to be rendered as an iframe:

<div class="pa-interactive">
<iframe class="video-iframe" width="560" height="315" src="https://www.youtube.com/embed/youtubeidhere/"></iframe>
</div>

 

Conclusion!

In order to use our html and content in instant articles we have to create rules for HTML tags so facebook will know what this tags will represent inside article.

Comments