<h1id="dev_page_title">Instant Views and Where to Find Them</h1>
<divid="dev_page_content"><!-- scroll_nav -->
<p>This document describes Telegram's Instant View format in <strong>stupefying detail</strong>. If this is your first time hearing about Instant View, please check out our <ahref="/"><strong>Introduction</strong></a> and <ahref="/samples/"><strong>Sample Templates</strong></a> before you dive in. </p>
<p>If you're comfortable with the idea of Instant View templates, let's look at what makes them tick. To begin with, this is our in-house artist's idea of how Instant View pages are generated:</p>
<div>
<ahref="/file/811140069/3/HNOgxR07ql4.872234/f83bfd30da8845e186"target="_blank"><imgsrc="/file/811140938/2/FF1p2pxErHM.79819/a582b1940327a15468"title="How Instant View Pages are made, click for hi-res version"class="dev_page_image"/></a>
</div>
<p>It turns out, he is not entirely wrong. This is how Instant View pages are <strong>really</strong> generated:</p>
<ol>
<li>Whenever Telegram needs to display a link preview for a URL, it also checks whether an <strong>Instant View template</strong> exists for that domain.</li>
<li>If a template exists, our Instant View Bot obtains the page using the URL (it only processes pages that have the MIME-type <code>text/html</code>).</li>
<li>The bot then applies <strong>rules</strong> from the template that determine the positioning of the key elements on the source page (using <ahref="https://www.w3.org/TR/xpath/">XPath 1.0</a> expressions) and modifies the page content to fit the <strong>Instant View format</strong>.</li>
<li>The edited page is used to create a new <strong>Instant View page</strong> that will be displayed to the user.</li>
</ol>
<p>This document will explore the <ahref="#instant-view-format">Instant View Format</a>, the <ahref="#types-of-rules">Types of Rules</a> your template can utilize, as well as some useful <ahref="#extended-xpath">XPath constructs</a>, <ahref="#supported-conditions">conditions</a>, and <ahref="#supported-functions">functions</a> that may help you build better templates.</p>
<p>This manual was intended to be used as a reference, so you don't have to read the entire thing to get started. Our <ahref="/samples">sample templates</a> make for a much better entry point. You can check back here whenever something is not clear.</p>
<li>Supported the <code>srcset</code> attribute in <strong>Image</strong> and <strong>Icon</strong> types. The IV engine will automatically take the highest image resolution available (but not higher than 2560px).</li>
<li>The <ahref="#match">@match</a> function now returns only nodes which content was matched by regular expression</li>
<li>The <ahref="#replace">@replace</a> function now returns only nodes which content was replaced by regular expression</li>
<li>The <ahref="#inline">@inline</a> function no longer follows canonical redirect links while fetching a page</li>
</ul>
<p><strong>Also in this update:</strong></p>
<ul>
<li>Added the new <ahref="#split-parent">@split_parent</a> function</li>
<p><strong>Instant View 2.0</strong> expands the platform with support for right-to-left languages, new page blocks, useful functions and much more. We recommend using the latest version in your templates. To do this, add the following rule <strong>at the beginning</strong> of the template:</p>
<pre><code>~version: "2.0"</code></pre>
<p>Below is a list of changes in version 2.0:</p>
<p>New <ahref="#properties">properties</a>:</p>
<ul>
<li>kicker</li>
<li>site_name</li>
</ul>
<p>New <ahref="#supported-types">types</a>:</p>
<ul>
<li>Map</li>
<li>Table</li>
<li>Details</li>
<li>RelatedArticles</li>
<li>Marked</li>
<li>Subscript</li>
<li>Superscript</li>
<li>Icon</li>
<li>PhoneLink</li>
<li>Reference</li>
</ul>
<p>New <ahref="#types-of-rules">types of rules</a>:</p>
<p>An Instant View page is an object with the following <ahref="#properties"><strong>properties</strong></a>:</p>
<tableclass="table">
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>title</strong><em>Required</em></td>
<td>RichText</td>
<td>Page title</td>
</tr>
<tr>
<td><strong>subtitle</strong></td>
<td>RichText</td>
<td>Page subtitle</td>
</tr>
<tr>
<td><strong>kicker</strong> </td>
<td>RichText</td>
<td>Kicker</td>
</tr>
<tr>
<td><strong>author</strong></td>
<td>String</td>
<td>Author name</td>
</tr>
<tr>
<td><strong>author_url</strong></td>
<td>Url</td>
<td>Author link</td>
</tr>
<tr>
<td><strong>published_date</strong></td>
<td>Unixtime</td>
<td>Date published</td>
</tr>
<tr>
<td><strong>description</strong></td>
<td>String</td>
<td>A short description (used in link preview)</td>
</tr>
<tr>
<td><strong>image_url</strong></td>
<td>Url</td>
<td>Link preview photo (used in link preview)</td>
</tr>
<tr>
<td><strong>document_url</strong></td>
<td>Url</td>
<td>Link preview document (used in link preview)</td>
</tr>
<tr>
<td><strong>site_name</strong> </td>
<td>String</td>
<td>Name of website (used in link preview)</td>
</tr>
<tr>
<td><strong>channel</strong></td>
<td>String</td>
<td>The username of the article author's (or the originating website's) <ahref="https://telegram.org/blog/channels">channel</a> on Telegram in the format <code>@username</code></td>
<p>The platform supports right-to-left languages. If <code><html></code> tag or tag referenced by body property has the attribute <code>dir="rtl"</code>, the page will be marked as RTL. In case this attribute is not set, you can set it manually to display the page in Instant View as RTL using the following rule:</p>
<pre><code> @set_attr(dir, "rtl"): $body # if body is already defined
@set_attr(dir, "rtl"): /html # alternative way</code></pre>
<td>We use the top-level of the <code><h1></code>–<code><h4></code> headings found on the source page</td>
</tr>
<tr>
<td><strong>Subheader</strong></td>
<td>RichText</td>
<td>Minor heading</td>
<td>We use the remaining headings <code><h1></code>–<code><h4></code> as well as <code><h5></code>–<code><h6></code> headings</td>
</tr>
<tr>
<td><strong>Paragraph</strong></td>
<td>RichText</td>
<td>A paragraph</td>
<td><code><p></code></td>
</tr>
<tr>
<td><strong>Preformatted</strong></td>
<td>RichText</td>
<td>Preformatted text</td>
<td><code><pre></code> with the optional attribute <code>data-language</code><ahref="#note-on-code-languages">*</a></td>
</tr>
<tr>
<td><strong>Anchor</strong></td>
<td>–</td>
<td>Anchor</td>
<td><code><anchor></code> with the attribute <code>name</code> that contains the anchor name</td>
</tr>
<tr>
<td><strong>Divider</strong></td>
<td>–</td>
<td>A separator</td>
<td><code><hr></code></td>
</tr>
<tr>
<td><strong>List</strong></td>
<td>ListItem</td>
<td>A list</td>
<td><code><ul></code> for a bullet list, <code><ol></code> for a numbered list</td>
<td><code><img></code> with the attribute <code>src</code> and the optional attribute <code>href</code> to make the image clickable. Allowed formats: GIF, JPG, PNG (GIF would be converted into Video type by IV)<br>As of <ahref="#march-20-2019">version 2.1</a>, supports the attribute <code>srcset</code> (<code>srcset</code> has higher priority than <code>src</code>, the same as in a browser; IV gets the highest available resolution under 2560px).</td>
</tr>
<tr>
<td><strong>Video</strong></td>
<td>–</td>
<td>A video</td>
<td><code><video></code> with the attribute <code>src</code>, or containing the tag <code><source type="video/mp4"></code> with the attribute <code>src</code></td>
</tr>
<tr>
<td><strong>Audio</strong></td>
<td>–</td>
<td>An audio</td>
<td><code><audio></code> with the attribute <code>src</code>, or containing the tag <code><source></code> with the attribute <code>src</code> and the attribute <code>type</code> (possible types: <code>audio/ogg</code>, <code>audio/mpeg</code>, <code>audio/mp4</code>)</td>
</tr>
<tr>
<td><strong>Embed</strong></td>
<td>–</td>
<td>An embedded element</td>
<td><code><iframe></code> with the attribute <code>src</code>. <ahref="#embedded-elements">List of supported embeds</a></td>
</tr>
<tr>
<td><strong>Map</strong> </td>
<td>–</td>
<td>A map</td>
<td><code><img></code> or <code><iframe></code> with the attribute <code>src</code> referring to Google or Yandex maps</td>
<td><code><figcaption></code><br> As of IV 2.0, can contain an additional tag <code><cite></code> with attribution (author, creator or source of the media)</td>
</tr>
<tr>
<td><strong>Table</strong> </td>
<td>TableCaption<br> TableRow</td>
<td>A table</td>
<td><code><table></code></td>
</tr>
<tr>
<td><strong>TableCaption</strong> </td>
<td>RichText</td>
<td>A table caption</td>
<td><code><caption></code></td>
</tr>
<tr>
<td><strong>TableRow</strong> </td>
<td>TableCell</td>
<td>A table row</td>
<td><code><tr></code> with the optional attributes <code>align</code>, <code>valign</code>, can be wrapped with <code><thead></code> or <code><tbody></code> or <code><tfoot></code> with the optional attributes <code>align</code>, <code>valign</code></td>
</tr>
<tr>
<td><strong>TableCell</strong> </td>
<td>RichText</td>
<td>A table cell</td>
<td><code><td></code> for a standard cell, <code><th></code> for a header cell, with the optional attributes <code>align</code>, <code>valign</code>, <code>colspan</code>, <code>rowspan</code></td>
<td>A visible heading for the collapsible block</td>
<td><code><summary></code></td>
</tr>
<tr>
<td><strong>RelatedArticles</strong> </td>
<td>Header<br> Link</td>
<td>Related articles</td>
<td><code><related></code> containing one of <code><h1></code>–<code><h6></code> tag as header of the block and <code><a></code> tags with the attribute <code>href</code> containing a URL of related article. <strong>Note:</strong> Only articles that have an IV will appear in this block on the IV page.</td>
<td><code><b></code> or <code><strong></code></td>
</tr>
<tr>
<td><strong>Italic</strong></td>
<td>RichText</td>
<td>Italic text</td>
<td><code><i></code> or <code><em></code></td>
</tr>
<tr>
<td><strong>Underline</strong></td>
<td>RichText</td>
<td>Underlined text</td>
<td><code><u></code> or <code><ins></code></td>
</tr>
<tr>
<td><strong>Strike</strong></td>
<td>RichText</td>
<td>Strikethrough text</td>
<td><code><s></code> or <code><del></code> or <code><strike></code></td>
</tr>
<tr>
<td><strong>Fixed</strong></td>
<td>RichText</td>
<td>Monospace text</td>
<td><code><code></code> or <code><kbd></code> or <code><samp></code> or <code><tt></code></td>
</tr>
<tr>
<td><strong>Marked</strong> </td>
<td>RichText</td>
<td>Marked text</td>
<td><code><mark></code></td>
</tr>
<tr>
<td><strong>Subscript</strong> </td>
<td>RichText</td>
<td>Subscript text</td>
<td><code><sub></code></td>
</tr>
<tr>
<td><strong>Superscript</strong> </td>
<td>RichText</td>
<td>Superscript text</td>
<td><code><sup></code></td>
</tr>
<tr>
<td><strong>Icon</strong> </td>
<td>–</td>
<td>A small image inside the text</td>
<td><code><pic></code> with the attribute <code>src</code>, <code>width</code>, <code>height</code>. Can contain the attribute <code>optional</code> if the image is not important and may be ignored. Allowed formats: JPG, PNG.<br>As of <ahref="#march-20-2019">version 2.1</a>, supports the attribute <code>srcset</code> (<code>srcset</code> has higher priority than <code>src</code>, the same as in a browser).</td>
</tr>
<tr>
<td><strong>Link</strong></td>
<td>RichText</td>
<td>A link</td>
<td><code><a></code> with the attribute <code>href</code> containing a URL</td>
</tr>
<tr>
<td><strong>EmailLink</strong></td>
<td>RichText</td>
<td>A link to an email address</td>
<td><code><a></code> with the attribute <code>href</code> containing a <code>mailto:</code> link</td>
</tr>
<tr>
<td><strong>PhoneLink</strong> </td>
<td>RichText</td>
<td>A link to a phone number</td>
<td><code><a></code> with the attribute <code>href</code> containing a <code>tel:</code> link</td>
</tr>
<tr>
<td><strong>Reference</strong> </td>
<td>RichText</td>
<td>A reference</td>
<td><code><reference></code> with the attribute <code>name</code> that contains the reference name</td>
</tr>
<tr>
<td><strong>LineBreak</strong></td>
<td>–</td>
<td>Line break</td>
<td><code><br></code></td>
</tr>
</tbody>
</table>
<h5><aclass="anchor-link"href="#note-on-code-languages"><iclass="anchor-icon"></i></a><aclass="anchor"name="note-on-code-languages"></a>Note on code languages</h5>
<p>Telegram apps currently do not support code highlighting, but they will in the future. For this reason, it is advisable to include the code language attribute (<code>data-language</code>) for large <code><pre></code> blocks if it is supplied in the source.</p>
<hr>
<h3><aclass="anchor-link"href="#types-of-rules"><iclass="anchor-icon"></i></a><aclass="anchor"name="types-of-rules"></a>Types of Rules</h3>
<p>Instant View rules are instructions that tell our IV bot where to find the meta-elements on the source page and how it should modify the content of the page when an Instant View page is created.</p>
<p>Each new line in a template describes a new rule. When the bot renders a page into the Instant View format, it applies rules from the relevant template one after another and ignores any empty lines. You can leave comments by starting a line with <code>#</code>, all following text on that line will be ignored unless enclosed in quote marks. You can use the <code>\</code> symbol to carry a rule over to the next string, like this:</p>
<pre><code># Comment
# You can break up \
a long rule into \
multiple strings</code></pre>
<p>Most rules are based on <ahref="https://www.w3.org/TR/xpath/">XPath 1.0</a> expressions used to locate the required nodes on the source page.</p>
<p>A block of rules may have a name. In this case, it can be reused in other rules.</p>
<p>Conditions offer unlimited flexibility for your templates. Rules of this type begin with the symbols <code>?</code> or <code>!</code> and use the following format:</p>
<pre><code>?condition: xpath_query # condition example
!condition: regexp # parameter on the right depends on the type of the condition
?condition # some conditions don't have parameters</code></pre>
<p>Groups of conditions that immediately follow one another are interpreted as a block. <code>?</code>-rules follow the OR logic when joined, while <code>!</code>-rules follow the AND logic. This means that for the bot to apply each block, all <code>!</code>-conditions in the block and at least one of the <code>?</code>-conditions within it must be met. This also means that each block must have at least one <code>?</code>-condition.</p>
<p>Blocks of conditions split your rule set into groups. Groups of rules that do not have any conditions are always applied. All other groups are only applied if their conditions are met.</p>
<p><strong>Examples</strong></p>
<pre><code># If a rule is placed here, it will be applied
# Same with the one here
?false # This condition is always false
# The rule placed here will never be applied, because the condition is not met
# Very useful indeed
?exists: //article # This condition is true if the page has an article tag
# On these lines, a new group of rules is located, and it will be applied if
# there's an article tag on the page, despite the ?false condition above
?exists: //article
?exists: //div[@id="article"]
!exists: //meta[@property="og:title"]
# The rules below this block will be applied if an <article> tag or a
# <div id="article"> can be found, this tag must also be present: <meta property="og:title"></code></pre>
<div><br></div>
<blockquote>
<p><ahref="#supported-conditions">Check out the Supported Conditions to see what works out of the box »</a></p>
<p>Properties are the building blocks for your IV page. Check the <ahref="#instant-view-format">Instant View Format</a> for a list of properties that can be used when creating IV pages (you can also define custom properties, but they will not be used anywhere on the resulting IV page). Use this format to fill properties:</p>
<pre><code>property: xpath_query
property: "Some string"
property: null</code></pre>
<p>Properties store the first node that matches the XPath expression <code>xpath_query</code>. By default, if a property already has a value, it will <strong>not</strong> be overwritten. You can change this behavior by adding <code>!</code> to the property name – in this case a new non-empty value can be assigned. If you add <code>!!</code> to the property name, even an empty new value can be assigned to the property.</p>
<p>You can also assign a <code>string</code> to the property instead of the <code>xpath_query</code>. In this case, the property will contain a text element with the specified text. It is also possible to assign <code>null</code> to discard the property's value (will only work with <code>!!</code>).</p>
<p><strong>Examples</strong></p>
<pre><code>title: //article//h1 # Looking for the 'title' in the article heading
title: //h1 # If not found, checking for any headings at all
title: //head/title # If no luck either, trying the <title> tag
?path: /blog/.* # On pages in the /blog/ section
title!: //div[@id="title"] # we prefer to use <div id="title">, if present
?path: /news/.* # On pages in the /news/ section
title!!: //h3 # title is always in an h3 tag
author: //article/@author # Get author name from the author attribute
<p>Variables are useful for storing and manipulating nodes before assigning them to <ahref="#properties">properties</a> for the final IV page. Variable names begin with the <code>$</code> symbol. Use this format to initialize them:</p>
<pre><code>$variable: xpath_query
$variable: "Some text"
$variable: null</code></pre>
<p>Variables store a list of nodes that match the Xpath expression <code>xpath_query</code>. If a variable is assigned for the second time, its previous value is overwritten. You can change this behavior by adding <code>?</code> to the variable name. You can also append a list of nodes to the previous one by adding <code>+</code> to the variable name.</p>
<p>You can also assign a <code>string</code> to the variable instead of the <code>xpath_query</code>. In this case, the variable will contain a list with one text element that has the specified text. It is also possible to assign <code>null</code> to discard the variable's value.</p>
<p><strong>Examples</strong></p>
<pre><code>$images: //img
$images: //img[@src] # the previous value will be overwritten
$images?: //article//img # a new value will only be assigned if the variable is empty
$medias: //img
$medias+: //video # now $medias contains all img and video tags</code></pre>
<p>Functions are extremely flexible, but you'll probably mostly use them to strip unnecessary nodes from the page and to replace certain elements with others. Function names begin with the <code>@</code> symbol, you can use the following format:</p>
<pre><code>@function: xpath_query # a function without parameters
@function(param): xpath_query # additional parameters are placed in paretheses
@function(p1 p2): xpath_query # a function with two parameters
@function(p1, "param #2"): xpath_query # parameters can be separated by commas
# and enclosed in quote marks when needed
@function: "Some text" # use string instead of xpath_query if needed</code></pre>
<p>The main argument of a function is a list of nodes that match the Xpath expression <code>xpath_query</code>. You can also use a <code>string</code> as the main argument instead of an <code>xpath_query</code>. In this case, the main argument passed to the function will be a list with one text element that has the specified text.</p>
<p><strong>Examples</strong></p>
<pre><code>@remove: //header # removes all <header> tags found on the page
@replace_tag(<h1>): //div[@class="header"] # replaces all <div class="header"> tags with <h1>
<h1>: //div[@class="header"] # an alias for @replace_tag(<h1>)</code></pre>
<div><br></div>
<p><strong>Note:</strong> You may find the <ahref="#debug">@debug function</a> particularly useful when creating XPath expressions.</p>
<blockquote>
<p>Check out <ahref="#supported-functions">Supported Functions</a> to see what else works out of the box.</p>
<p>Block functions manipulate blocks of rules. Block function names also begin with the <code>@</code> symbol, you can use the following format:</p>
<pre><code>@function(xpath_query) { # opening bracket should be at the end of the line
$variable: xpath_query # some other rules here
@function: $@ # inside the block function
} # closing bracket should be on a separate line</code></pre>
<p>A block function can contain another block function so they can be nested. Block function can not contain <ahref="#conditions">conditions</a>.</p>
<blockquote>
<p>Please note that block functions that execute a block of rules several times <strong>(map</strong>, <strong>repeat</strong>, <strong>while</strong>, <strong>while_not)</strong> have a limit on the total number of iterations for the entire template.</p>
</blockquote>
<p><strong>Examples</strong></p>
<pre><code>@if( //article ) { # if <article> exists
@append(<p>): $$ # append paragraph into it
}</code></pre>
<div><br></div>
<blockquote>
<p>Check out <ahref="#supported-block-functions">Supported Block Functions</a> to see what else works out of the box.</p>
<p><strong>Note:</strong> This is a service rule, it <strong>will not work</strong> in your templates. It was included in this reference to give you a better understanding of how the system works. You can see an example of this rule at work in the <ahref="#processing-pages">Processing Pages</a> section.</p>
</blockquote>
<p>Rules of this type begin with the <code>+</code> symbol and use the following format:</p>
<pre><code>+ rules</code></pre>
<p>This rule inserts a block of rules with the specified name. In most cases, the name corresponds to the domain to which the rules apply.</p>
<p><strong>Examples</strong></p>
<pre><code>+ core.telegram.org # inserting the block of rules that is used for core.telegram.org
?not_exists: $body
+ telegram.org # inserting the block of rules that is used for telegram.org</code></pre>
<h4><aclass="anchor-link"href="#special-variables-and"><iclass="anchor-icon"></i></a><aclass="anchor"name="special-variables-and"></a>Special variables <code>$$</code> and <code>$@</code></h4>
<p>The special variables work within a group of rules.</p>
<ul>
<li>The <code>$$</code> variable always contains the result of the most recent XPath query. </li>
<li>The <code>$@</code> variable holds the return of the most recently run function.</li>
</ul>
<p>These variables come in handy when you're creating chains of rules. If a rule is missing xpath_query, the statement is considered to be equal to <code>$$</code>.</p>
<p><strong>Examples</strong></p>
<pre><code># Put a picture into a <figure> tag, then set it as the cover
<p>Regular XPath queries search for nodes in the context of the entire document. To specify the context for a particular expression, you can use variables in the format <code>$context</code>. If a matching variable exists, the query will be made relative to each variable node. If it doesn't and a matching property exists, the query will be made relative to the property node. If no matching variables or properties exist, the query return an empty list.</p>
<p><strong>Examples</strong></p>
<pre><code>$headers: //h1 # all <h1> tags on the page
article: //article # the first <article> tag on the page
$art_headers: $article//h1 # all <h1> tags inside article
$header_links: $art_headers//a # all <a> tags inside each $art_headers node</code></pre>
<h4><aclass="anchor-link"href="#zeroing-in-on-nodes"><iclass="anchor-icon"></i></a><aclass="anchor"name="zeroing-in-on-nodes"></a>Zeroing in on nodes</h4>
<p>The result of an XPath query is always a list of matching nodes. If you'd like to narrow the list down to a single node, you can use the following syntax: <code>(xpath_query)[n]</code>, where <code>n</code> is the number of the desired node. Numbering starts at 1, you can get the last node by using the <code>last()</code> function. This syntax can only be applied to the entire expression.</p>
<p><strong>Examples</strong></p>
<pre><code>$headers: //h1 # all <h1> tags on the page
$header2: (//h1)[2] # the second <h1> tag on the page
$header2: ($headers)[2] # same
$last_link: ($header2//a)[last()] # the last link inside $header2</code></pre>
<p>You will often need to locate nodes that have a certain class. To do this, you can use the <code>has-class("class")</code> function that serves as an alias for the expression <code>contains(concat("", normalize-space(@class), ""), " class ")</code>.</p>
<p><strong>Examples</strong></p>
<pre><code># Transform all div.header elements into h1
<p>XPath has a <code>starts-with</code> function that checks whether the first string starts with the second string but does not have <code>ends-with</code>. In IV you can use the <code>ends-with("haystack","needle")</code> function that serves as an alias for the expression <code>(substring("haystack", string-length("haystack") - string-length("needle") + 1) = "needle")</code>.</p>
<p>Checks whether the domain of the current page matches a regular expression. The check is case-insensitive, so the actual expression used will look like this: <code>/^regexp$/i</code>.</p>
<p><strong>Examples</strong></p>
<pre><code># Rule for *.subdomain.example.com URLs
<p>Checks whether the domain of the current page does not match a regular expression. The check is case-insensitive, so the actual expression used will look like this: <code>/^regexp$/i</code>.</p>
<p><strong>Examples</strong></p>
<pre><code># Rule for *.subdomain.example.com URLs with an exception for dev.subdomain.example.com
<p>Checks whether the path to the current page matches a regular expression. The check is case-insensitive, so the actual expression used will look like this: <code>/^regexp$/i</code>.</p>
<p><strong>Examples</strong></p>
<pre><code># Rule for example.com/news/* links
?path: /news/.+ # no need to escape the slash</code></pre>
<p>Checks whether the path to the current page does not match a regular expression. The check is case-insensitive, so the actual expression used will look like this: <code>/^regexp$/i</code>.</p>
<p><strong>Examples</strong></p>
<pre><code># Rule for example.com/news/* links with an exception for example.com/news/recent
<p>Sets the version of IV used in the template. The behavior of some IV functions may change according to the version provided (see the manual of corresponding function).<br>The value must be one of <code>"1.0"</code>, <code>"2.0"</code> or <code>"2.1"</code>. We recommend using the latest version, <strong>2.1</strong>.</p>
<p><strong>Examples</strong></p>
<pre><code>~version: "2.1"
# Now you can use new features from IV 2.1</code></pre>
<blockquote>
<p>Please note that <code>version</code> should be set at the beginning of the template before any other rules.</p>
<p>Sets the origin (or the list of origins) from which content can be loaded using the <ahref="#load-new">@load</a> and <ahref="#inline">@inline</a> functions.<br>The value should be <em>String</em> or <em>Array of String</em>.</p>
<p>The general format for a function is the following:</p>
<pre><code>@function: xpath_query</code></pre>
<p>Each function accepts the list of nodes returned by the XPath statement as the main parameter. You may omit <code>xpath_query</code>, in which case <code>$$</code>, the result of the previous XPath query, will be passed into the function. The function then processes each element in the list and returns a list of transformed nodes which are stored in the <code>$@</code> variable.</p>
<p>Below is a list of functions that are supported in Instant View rules.</p>
<p>Logs the elements passed into the function, these elements will be displayed in the status line at the bottom of the screen in the <ahref="https://instantview.telegram.org/#instant-view-editor">Instant View Editor</a>. Returns the elements passed. Consider combining with <ahref="#special-variables-and"><code>$$</code> and <code>$@</code></a>.</p>
<p><strong>Example</strong></p>
<pre><code>@debug: //article//a # displays all links from the page in the log
@debug # displays all links again</code></pre>
<div><br></div>
<p>Look for debug output at the bottom of your Editor:</p>
<div>
<ahref="/file/811140378/19ec/lgDhyQ_HKcc.120673/c7602c526f316dc5a4"target="_blank"><imgsrc="/file/811140378/19ec/lgDhyQ_HKcc.120673/c7602c526f316dc5a4"title="Debug console at the bottom of the screen"class="dev_page_image"style="max-width: 600px"/></a>
<p>Inserts content, specified by the parameter, to the end of each target node.</p>
<ul>
<li>If the first parameter is in angle brackets, a new <code><tag></code> node will be created. The following two parameters then specify the name and value of an attribute for that node. If <code>value</code> has the format <code>@attr</code>, the value of the attribute <code>attr</code> in the target node will be used as the value. <code>value</code> can be an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node, and the text value of the returned elements will be used as the attribute's value. Otherwise, <code>value</code> will be used as the attribute's value.</li>
<li>If the first parameter has the format <code>@attr</code>, a new text element with value of the attribute <code>attr</code> of the targeted node will be created.</li>
<li>Otherwise, a text element with the text specified in the first parameter will be created.</li>
<p>Inserts content, specified by the parameter, to the beginning of each target node.</p>
<ul>
<li>If the first parameter is in angle brackets, a new <code><tag></code> node will be created. The following two parameters then specify the name and value of an attribute for that node. If <code>value</code> has the format <code>@attr</code>, the value of the attribute <code>attr</code> in the target node will be used as the value. <code>value</code> can be an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node, and the text value of the returned elements will be used as the attribute's value. Otherwise, <code>value</code> will be used as the attribute's value.</li>
<li>If the first parameter has the format <code>@attr</code>, a new text element with value of the attribute <code>attr</code> of the targeted node will be created.</li>
<li>Otherwise, a text element with the text specified in the first parameter will be created.</li>
<p>Inserts content, specified by the parameter, after each target node.</p>
<ul>
<li>If the first parameter is in angle brackets, a new <code><tag></code> node will be created. The following two parameters then specify the name and value of an attribute for that node. If <code>value</code> has the format <code>@attr</code>, the value of the attribute <code>attr</code> in the target node will be used as the value. <code>value</code> can be an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node, and the text value of the returned elements will be used as the attribute's value. Otherwise, <code>value</code> will be used as the attribute's value.</li>
<li>If the first parameter has the format <code>@attr</code>, a new text element with value of the attribute <code>attr</code> of the targeted node will be created.</li>
<li>Otherwise, a text element with the text specified in the first parameter will be created.</li>
<p>Inserts content, specified by the parameter, before each target node.</p>
<ul>
<li>If the first parameter is in angle brackets, a new <code><tag></code> node will be created. The following two parameters then specify the name and value of an attribute for that node. If <code>value</code> has the format <code>@attr</code>, the value of the attribute <code>attr</code> in the target node will be used as the value. <code>value</code> can be an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node, and the text value of the returned elements will be used as the attribute's value. Otherwise, <code>value</code> will be used as the attribute's value.</li>
<li>If the first parameter has the format <code>@attr</code>, a new text element with value of the attribute <code>attr</code> of the targeted node will be created.</li>
<li>Otherwise, a text element with the text specified in the first parameter will be created.</li>
<p>Inserts each target node to the end of the base node.</p>
<p>The first parameter specifies the base node. You can pass an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node. The <em>first relevant node</em> will be used as the base node. You can also pass a variable name. If such a variable exists, the <em>first relevant node</em> will be used as the base node. If the variable doesn't exist or is empty, the property with a matching name will be used as the base node.</p>
<p>Inserts each target node to the beginning of the base node.</p>
<p>The first parameter specifies the base node. You can pass an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node. The <em>first relevant node</em> will be used as the base node. You can also pass a variable name. If such a variable exists, the <em>first relevant node</em> will be used as the base node. If the variable doesn't exist or is empty, the property with a matching name will be used as the base node.</p>
<p>Inserts each target node after the base node.</p>
<p>The first parameter specifies the base node. You can pass an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node. The <em>first relevant node</em> will be used as the base node. You can also pass a variable name. If such a variable exists, the <em>first relevant node</em> will be used as the base node. If the variable doesn't exist or is empty, the property with a matching name will be used as the base node.</p>
<p>Inserts each target node before the base node.</p>
<p>The first parameter specifies the base node. You can pass an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node. The <em>first relevant node</em> will be used as the base node. You can also pass a variable name. If such a variable exists, the <em>first relevant node</em> will be used as the base node. If the variable doesn't exist or is empty, the property with a matching name will be used as the base node.</p>
<p>Wrap an HTML structure around the content of each target node in the <code><tag></code> tag. Returns a list of new <code><tag></code> elements.</p>
<p>Separates the target node from the rest in the parent tag. Creates a copy of the parent tag and wraps the target node into this new instance. Returns a list of parent tags that contain target nodes.</p>
<p>Splits the parent tag by the target node. Places preceding siblings wrapped into parent element before the target node. Places following siblings wrapped into parent element placed after target node.</p>
<p>Sets an attribute in each matching node. The name of the attribute is passed in the first parameter. The value of the attribute is the rest of the parameters concatenated.</p>
<p>If <code>value</code> has the format <code>@attr</code>, the value of the attribute <code>attr</code> of the target node will be used as the value. <code>value</code> can be an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node, and the text value of the returned elements will be used as the attribute's value. Otherwise, <code>value</code> will be used as the attribute's value.</p>
<p>Sets multiple attributes for each of the target nodes. Each two parameters specify the name and value for the new attributes.</p>
<p>If <code>value</code> has the format <code>@attr</code>, the value of the attribute <code>attr</code> of the target node will be used as the value. <code>value</code> can be an XPath expression that begins with <code>.</code>, in this case the query will be executed relative to the relevant node, and the text value of the returned elements will be used as the attribute's value. Otherwise, <code>value</code> will be used as the attribute's value.</p>
<p>Performs a search based on a regular expression. Replaces the content of the target node with the search result. The second parameter specifies the number of the captured parenthesized subpattern. If this is not specified, the text that matched the full pattern will be used. You can specify modifiers for the regular expression using the optional parameter (<ahref="http://pcre.org/pcre.txt">ims modifiers</a> are supported).</p>
<p>Returns a list of target nodes. As of IV <strong>2.1</strong>, returns a list of target nodes the content of which matched the regular expression.</p>
<p>Performs a search and replace operation using the regular expression. You can specify modifiers for the regular expression using the optional parameter (<ahref="http://pcre.org/pcre.txt">ims modifiers</a> are supported).</p>
<p>Returns a list of target nodes. As of IV <strong>2.1</strong>, returns a list of target nodes the content of which was replaced by the regular expression.</p>
<p>Gets a value of a CSS property from the style attribute and sets it into an attribute for each of the target nodes. Each two parameters specify the name for the new attribute and the name of CSS property. Returns a list of matching nodes.</p>
<p>Transforms the target node with a background picture into an <code><img></code> tag with an <code>src</code> attribute. The target node must contain a <code>style</code> attribute with the background. Returns a list of transformed nodes.</p>
<p>Transforms the content of the target node to the XML format. The contents must be in valid JSON format. The resulting XML tree will be inserted into the document. Returns the root element of the XML tree.</p>
<p>Combines each target node with its preceding node if such a node exists. You can use parameters to specify nodes to be inserted above the target node. If the parameter is in angular brackets, a new <code><tag></code> node will be created. Otherwise a text element with the text specified by the parameter will be used.</p>
<p>Returns a list of nodes, preceding the target nodes.</p>
<p>Transforms the date and time from the text of the target node into a unixtime timestamp. The parameter specifies the timezone of the original date and time.</p>
<p>You can also pass a locale and a pattern to parse the date and time in more complicated cases. If a non-gregorian calendar is used, this needs to be specified in the locale. For example, <code>"fa-IR@calendar=persian"</code>. Available patterns are documented <ahref="http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax">here</a>. </p>
<p>On success, returns a text element with the unixtime timestamp. Otherwise, returns the target element.</p>
<p><strong>Examples</strong></p>
<pre><code># <div id="date">1 January 2017, 15:04</div>
@datetime(-2): //div[@id="date"]
published_date: $@ # the property published_date will hold a unixtime timestamp
<p><strong>Note:</strong> This is a service function. There is no reason for you to use it in your templates. It was included in this reference to give you a better understanding of how the system works (see the <code>..after</code> block).</p>
</blockquote>
<pre><code>@simplify: xpath_query</code></pre>
<p>Processes the target nodes according to the Instant View format. Returns the target nodes.</p>
<p>If the target element is an <code><iframe></code> with the attribute <code>src</code>, the content of the iframe will be loaded. The target element will be replaced with the content of the iframe.</p>
<p>If the target node is an HTML-comment, a <code><comment></code> element with the content of the comment will be created. The comment will be replaced by the newly created node.</p>
<p>You can use <code>silent</code> parameter to ignore errors while processing this function. You will still see an error in the debug console, but the rules that come after will continue to execute.</p>
<p>Returns a list of replaced nodes.</p>
<blockquote>
<p>Note: The @inline function adheres to the <ahref="https://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a>. This means that the target and the inlined pages should have the same origin. You can specify additional allowed origins using the option <ahref="#allowed-origin-new">~allowed_origin</a></p>
<p>Loads the content of the URL. The URL can be specified as a string or be the content of the target node.</p>
<p>You can use <code>silent</code> parameter to ignore errors while processing this function. You will still see an error in the debug console, but the rules that come after will continue to execute.</p>
<p>Returns the newly created node with loaded content.</p>
<blockquote>
<p>Note: The @load function adheres to the <ahref="https://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a>. This means that the target and the loaded pages should have the same origin. You can specify additional allowed origins using the option <ahref="#allowed-origin-new">~allowed_origin</a></p>
<p><strong>Tip:</strong> It is important to identify that a page contains essential unsupported content — no IV page will be generated to ensure that the user never gets incomplete info from an article. The system will take care of the most popular cases in the <code>..after</code> block, but your template must cover everything that the system doesn't catch.</p>
<p>The general format for a block function is the following:</p>
<pre><code>@function(xpath_query) {
# block of rules
}</code></pre>
<p>Block functions usually accept the list of nodes returned by the XPath statement as a parameter. Depending on the function and its parameters, rules inside the block can be run several times or never. Block functions can contain any type of rules except conditions.</p>
<p>Below is a list of block functions that are supported in Instant View rules.</p>
<p>Executes the block of rules if target nodes exist on the current page. If target nodes do not exist, the block of rules will be skipped. The <code>$$</code> and <code>$@</code> variables contain target nodes found by the XPath query.</p>
<p><strong>Example</strong></p>
<pre><code>@if( //div[has-class("blockquote")] ) { # if div.blockquote exists
<blockquote>: $@ # change tag name to blockquote
<cite>: $@//div[has-class("author")] # and mark div.author as a caption
<p>Executes a block of rules if target nodes do not exist on the current page. If such nodes exist, the block of rules will be skipped. The <code>$$</code> and <code>$@</code> variables contain target nodes found by the XPath query.</p>
<p><strong>Example</strong></p>
<pre><code>@if_not( $body//footer ) { # if footer does not exist
@append(<footer>): $body # append it into body
<p>Executes a block of rules once per each target node found by the XPath query. At the beginning of each iteration, the following variables will be set: </p>
<ul>
<li><code>$$</code> will contain the target nodes found by XPath query;</li>
<li><code>$@</code> will contain the current target node;</li>
<li><code>$index</code> will contain the index of the current target node (starts with 1);</li>
<li><code>$first</code> will contain <code><true></code> if the current target node is the first in the list and an empty list otherwise;</li>
<li><code>$middle</code> will contain <code><true></code> if the current target node is between the first and the last in the list, empty list otherwise;</li>
<li><code>$last</code> would contain <code><true></code> if the current target node is the last one in the list, empty list otherwise.</li>
</ul>
<p><strong>Example</strong></p>
<pre><code>@map( //div[@id="list"]/p ) { # for each paragraph in list
$p: $@ # store the current paragraph in $p variable
@prepend_to($p): ". " # and
@prepend_to($p): $index # number them starting with 1
}</code></pre>
<blockquote>
<p>Please note that the <code>@map</code> function should be used <strong>only</strong> if it is impossible to use <strong>regular functions</strong> with xpath queries (for example you need to use $index). Otherwise, regular functions are faster because they process several nodes at once.</p>
<p>Executes a block of rules while target nodes exist on the current page. At the beginning of each iteration the following variables will be set: </p>
<ul>
<li><code>$$</code> and <code>$@</code> will contain target nodes found by XPath query;</li>
<li><code>$index</code> will contain the index of the current iteration (starts with 1);</li>
<li><code>$first</code> will contain <code><true></code> if it is the first iteration, an empty list otherwise.</li>
<p>Executes a block of rules while target nodes do not exist on the current page. At the beginning of each iteration the following variables will be set: </p>
<ul>
<li><code>$$</code> and <code>$@</code> will contain target nodes found by XPath query;</li>
<li><code>$index</code> will contain the index of the current iteration (starts with 1);</li>
<li><code>$first</code> will contain <code><true></code> if this is the first iteration, an empty list otherwise.</li>
</ul>
<p><strong>Example</strong></p>
<pre><code>@while_not( //video ) { # if no video exists on the current page
@inline: //iframe # try to inline iframes, maybe video is inside the frame
<p>Instant View supports widgets from popular services. We display them as embedded elements or specially formatted quotes. The Instant View bot analyzes all iframes in the document body and generates a widget if the service is supported.</p>
<blockquote>
<p>Some popular widgets do not use iframes. Note that the <code>..after</code> block of rules contains rules to transform such widgets to an Instant View compatible format.</p>
</blockquote>
<p>We currently support the following services:</p>
<p>In other words, at first the bot attempts to use a block of rules that features the full domain name. If such a block does not exist, the bot checks for the next level up to the second-level domain.</p>
<p><code>..after</code> is a special block of rules that is applied to all pages irrespective of the domain name.</p>
<h4><aclass="anchor-link"href="#working-with-subdomains"><iclass="anchor-icon"></i></a><aclass="anchor"name="working-with-subdomains"></a>Working with subdomains</h4>
<p>If the page is on a third-level domain or higher, you need to manually select the domain level to which your template will apply. Use this menu in the top left corner of the page:</p>
<p>Choose a level that hosts pages with the same structure, so that your rules are relevant to all the matching pages on this domain. </p>
<blockquote>
<p>For example, use <code>wikipedia.org</code> to create an IV page for <code>https://en.wikipedia.org/wiki/Domain_name</code> because the page structure doesn't depend on language in Wikipedia.</p>
<p>Log in here to create Instant View templates. Please enter your <b>phone number</b> in the <atarget="_blank"rel="noopener"href="https://telegram.org/faq#login-and-sms">international format</a> and we will send a confirmation message to your account via Telegram.</p>
