Posts

General Usage

Example

<posts
    source="current_page"
    source_id="some-common-source-id"
    source_unique="true"
    without_current="true"
    without_posts="123123,3123123,5325235"
    limit="20"
    priority="0"
/>

Attributes

  • source (default: frontpage)

  • source_id (default: none) – allows for the combination of several <posts /> elements into a single DB call

    • Usually generated automatically based on the other attributes

  • source_unique (default: false) – allows for the management of duplicates

  • without_current (default: false) – allows for the management of current post exclusion

  • without_posts (default: none) – allows for the exclusion of explicitly specified posts

    • Can be a comma-separated list of post IDs

    • Can be a Skeleton Expression

  • priority (default: 0) – allows to alter the posts loading order. <posts> elements with higher priority are loaded first

    • For example, this can have an effect on duplicated posts between different sources

Sources

Filtered Source

Example

 <posts
     source="filtered"
     phrase="{{page.search_phrase}}"
     [types filter]
     [statuses filter]
     [sections filter]
     [communities filter]
     [authors filter]
     [tags filter]
     [period filter]
     [buckets_filter]
     order="newest"
     limit="20"
 />

Attributes

  • phrase – enables full-text search

    • Can be a specific phrase

    • Can be a Skeleton Expression

  • [ids filter] (see: IDs Filter)

  • [types filter] (see: Types Filter)

  • [statuses filter] (see: Statuses Filter)

  • [sections filter] (see: Sections Filter)

  • [communities Filter] (see: Communities Filter)

  • [authors filter] (see: Authors Filter)

  • [tags filter] (see: Tags Filter)

  • [period filter] (see: Period Filter)

  • [buckets filter] (see: Buckets Filter)

  • order (default: newest)

    • newest – for the most recent results to appear at the top

    • manual – for manually set order to be used

    • title – for ordering by title

    • best – for ordering by rating (deprecated)

    • page-views – for ordering by page views during period:

      • order_period (default: 1h) – allows specifying period ending now for Page Views to be taken into the account

        • 12h – by PVs from the last 12 hours

        • 7d – by PVs from the last 7 days

        • lifetime – by total number of PVs

    • relevance – for ordering by relevance to phrase

      • order_decay-speed (default: 10) – allows to specify the level of relevance vs. the age of the results:

        • 10 – the older results quickly become irrelevant

        • 0 – the age of the result doesn’t influence the order

Limitations

Multi Source

Example

 <posts source="multi" limit="20" strategy="fallback">
     <source name="filtered" ... from_regular_sections="section-1" />
     <source name="filtered" ... from_regular_sections="section-2" />
     <source name="filtered" ... from_regular_sections="section-3" />
 </posts>

 <posts source="multi" limit="20" strategy="max-limit">
     <source name="filtered" ... from_regular_sections="section-1" limit="3" />
     <source name="filtered" ... from_regular_sections="section-2" limit="5" />
     <source name="filtered" ... from_regular_sections="section-3" />
 </posts>

 <posts source="multi" limit="20" strategy="mutually-exclusive">
     <source name="filtered" ... from_regular_sections="section-1" />
     <source name="filtered" ... from_regular_sections_other_than="section-1" />
 </posts>

Notes

  • Allows to combine multiple sources

Strategies

  • Fallback strategy loads missing number of posts from the second and consequent sources only for the first page. Pagination can be achieved using ignore_page_number=”true” attribute but it must be used with caution because of the performance implications

  • Max-limit strategy works fine with pagination by it always performs queries for the first sources (with max limits). In order to minimize impact on the performance those limits should not be large

  • Mutually Exclusive strategy performs as less queries as possible but requires the sets of posts from the sources to be mutually exclusive. Otherwise, there are going to be duplicates.

Collection Source

Example

<posts
    source_site="current_site"
    source="collection"
    section_url="my-recipes"
    limit="20"
/>

Attributes

  • section_url – allows you to specify which section to pull posts from

    • Can be a specific section name

    • Can be a Skeleton Expression

Tag Source (deprecated)

Deprecated: please use Tags Filter instead.

Example

<posts
    source="tag"
    tag_name="news"
    limit="20"
/>

Attributes

  • tag_name (default: none) – allows you to specify which tag to use to pull posts

    • Can be a specific tag name

    • Can be a Skeleton Expression

    • If not specified, current tag posts are loaded on a Tag Page

Search Source (deprecated)

Deprecated: please use attribute “phrase” in Filtered Source or Multi Source instead.

Example

 <posts
     source="search"
     phrase="{{page.search_phrase}}"
     bucket="archived"
     [types filter]
     [sections_filter]
     [communities_filter]
     order="relevancy"
     decay_speed="5"
     limit="20"
     cache_ttl_in_seconds="120"
 />

Attributes

  • phrase (default: value from q query parameter)

    • Can be a specific phrase

    • Can be a Skeleton Expression

  • bucket (default: none) – allows for searching within a specific pre-defined bucket

    • Can be a specific bucket

  • [types filter] (see: Types Filter)

  • [sections filter] (see: Sections Filter)

  • [communities filter] (see: Communities Filter)

  • order (default: relevancy)

    • recency – ignore relevancy completely; the most recent results to appear at the top

    • relevancy – keep in mind that using relevancy of the results penalizes older results based on decay_speed

  • decay_speed (default: 10) – allows for the adjustment of the returned results’ order in terms of how current each one is

    • 10 – the older results quickly become irrelevant

    • 0 – the age of the result doesn’t influence how current it

River Source

Example

<posts
    source="river"
    user_id="{{request.user.id}}"
    limit="20"
/>

Attributes

  • user_id – requires specifying a particular user ID for accessing River

    • Can be a user ID

    • Can be a Skeleton Expression

Stream Source (deprecated)

Deprecated: please use Buckets Filter instead.

Example

<posts
    source="stream"
    bucket="~all~"
    type="popular"
    period="lifetime"
/>

Attributes

  • bucket – requires specifying a particular bucket of posts

  • type

    • popular – such streams contain posts ordered by PVs

    • movable – such streams initially contains posts ordered by publishing date but also are supposed to provide an ability to move the posts around manually

  • period – allows specifying period ending now for Page Views to be taken into the account in the case when type="popular"

Notes

  • This is still under development

  • It is aimed to replace most of the other sources

Collection Source (deprecated)

Example

<posts
    source_site="current_site"
    source="frontpage"
    section_url="my-recipes"
    limit="20"
/>

Attributes

  • section_url – allows you to specify which section to pull posts from

    • Can be a specific section name

    • Can be a Skeleton Expression

Section Source (deprecated)

Deprecated: please use Sections Filter instead.

Example

<posts
    source="frontpage"
    section_url="news"
    from_sections_other_than="politics,sport"
    order="primacy"
    limit="20"
/>

Attributes

  • section_url (default: none) – allows you to specify which section to pull posts from

    • Can be a specific section name

    • Can be a Skeleton Expression

    • If not specified - Loads Home section posts on the Home Page - Loads current section posts on Section Pages

  • from_sections_other_than (default: none) – allows for the exclusion of posts from specified sections

    • Can be a comma-separated list of section names

    • Can be a Skeleton Expression

  • order (default: recency)

    • recency – for the most recent results to appear at the top

    • primacy – for posts matched by Primary Section to appear at the top

Filters

IDs Filter

Example

 <posts
     ...
     ids="123,456,789"
     ...
 />

Attributes

  • ids – allows including posts by specific IDs

    • Can be a comma separated list of IDs

    • Can be a Skeleton Expression

Types Filter

Example

 <posts
     ...
     from_types="article"
     from_types_other_than="special"
     ...
 />

Attributes

  • from_types – allows including posts by specific types

    • Can be a comma separated list of types

    • Can be a Skeleton Expression

  • from_types_other_than – allows excluding posts by specific types

    • Can be a comma separated list of types

    • Can be a Skeleton Expression

Types

  • articleTBD

  • imageTBD

  • videoTBD

  • eventTBD

  • placeTBD

  • recipeTBD

  • productTBD

  • special – alias for event,place,recipe,product (subject to change)

Statuses Filter

Example

 <posts
     ...
     from_statuses="published"
     from_statuses_other_than="featured,community"
     ...
 />

Attributes

  • from_statuses – allows including posts by specific statuses

    • Can be a comma separated list of statuses

    • Can be a Skeleton Expression

  • from_statuses_other_than – allows excluding posts by specific statuses

    • Can be a comma separated list of statuses

    • Can be a Skeleton Expression

  • If neither specified, applies from_statuses="roar" behavior

Statuses

  • adminTBD

  • featuredTBD

  • communityTBD

  • roar – alias for admin,featured

  • published – alias for admin,featured,community

Sections Filter

Examples

 <posts
     ...
     from_primary_sections_of_current_post="true"
     from_primary_sections_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_primary_sections_of_current_post_other_than="news"
     from_primary_sections_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_primary_sections="news"
     from_primary_sections_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_regular_sections_of_current_post="true"
     from_regular_sections_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_regular_sections_of_current_post_other_than="news"
     from_regular_sections_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_regular_sections="news"
     from_regular_sections_other_than="politics,sport"
     ...
 />

Attributes

  • from_primary_sections_of_current_post – allows including posts by primary section of the current post

    • Can be true or false

  • from_primary_sections_of_current_post_other_than – allows including posts by primary section of the current post other the specified ones

    • Can be a comma separated list of section slugs

    • Can be a Skeleton Expression

  • from_primary_sections – allows including posts by specific primary sections

    • Can be a comma separated list of section slugs

    • Can be a Skeleton Expression

  • from_primary_sections_other_than – allows excluding posts by specific primary sections

    • Can be a comma separated list of section slugs

    • Can be a Skeleton Expression

  • from_regular_sections_of_current_post – allows including posts by any section of the current post

    • Can be true or false

  • from_regular_sections_of_current_post_other_than – allows including posts by any section of the current post other the specified ones

    • Can be a comma separated list of section slugs

    • Can be a Skeleton Expression

  • from_regular_sections – allows including posts by specific sections

    • Can be a comma separated list of section slugs

    • Can be a Skeleton Expression

  • from_regular_sections_other_than – allows excluding posts by specific sections

    • Can be a comma separated list of section slugs

    • Can be a Skeleton Expression

Communities Filter

Examples

 <posts
     ...
     from_communities_of_current_post="true"
     from_communities_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_communities_of_current_post_other_than="news"
     from_communities_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_communities="news"
     from_communities_other_than="politics,sport"
     ...
 />

Attributes

  • from_communities_of_current_post – allows including posts by any community of the current post

    • Can be true or false

  • from_communities_of_current_post_other_than – allows including posts by any community of the current post other the specified ones

    • Can be a comma separated list of community slugs

    • Can be a Skeleton Expression

  • from_communities – allows including posts by specific communities

    • Can be a comma separated list of community slugs

    • Can be a Skeleton Expression

  • from_communities_other_than – allows excluding posts by specific communities

    • Can be a comma separated list of community slugs

    • Can be a Skeleton Expression

Authors Filter

Examples

 <posts
     ...
     from_authors_of_current_post="true"
     from_authors_other_than="john.doe,jane.roe"
     ...
 />
 <posts
     ...
     from_authors_of_current_post_other_than="john.nokes"
     from_authors_other_than="john.doe,jane.roe"
     ...
 />
 <posts
     ...
     from_authors="john.nokes"
     from_authors_other_than="john.doe,jane.roe"
     ...
 />

Attributes

  • from_authors_of_current_post – allows including posts by any author of the current post

    • Can be true or false

  • from_authors_of_current_post_other_than – allows including posts by any author of the current post other the specified ones

    • Can be a comma separated list of author slugs

    • Can be a Skeleton Expression

  • from_authors – allows including posts by specific authors

    • Can be a comma separated list of author slugs

    • Can be a Skeleton Expression

  • from_authors_other_than – allows excluding posts by specific authors

    • Can be a comma separated list of author slugs

    • Can be a Skeleton Expression

Tags Filter

Examples

 <posts
     ...
     from_primary_tags_of_current_post="true"
     from_primary_tags_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_primary_tags_of_current_post_other_than="news"
     from_primary_tags_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_primary_tags="news"
     from_primary_tags_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_regular_tags_of_current_post="true"
     from_regular_tags_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_regular_tags_of_current_post_other_than="news"
     from_regular_tags_other_than="politics,sport"
     ...
 />
 <posts
     ...
     from_regular_tags="news"
     from_regular_tags_other_than="politics,sport"
     ...
 />

Attributes

  • from_regular_tags_of_current_post – allows including posts by any tag of the current post

    • Can be true or false

  • from_regular_tags – allows including posts by specific tags

    • Can be a comma separated list of tags

    • Can be a Skeleton Expression

  • from_regular_tags_other_than – allows excluding posts by specific tags

    • Can be a comma separated list of tags

    • Can be a Skeleton Expression

  • from_primary_tags_of_current_post – allows including posts by primary tag of the current post

    • Can be true or false

  • from_primary_tags – allows including posts by specific primary tags

    • Can be a comma separated list of tags

    • Can be a Skeleton Expression

  • from_primary_tags_other_than – allows excluding posts by specific primary tags

    • Can be a comma separated list of tags

    • Can be a Skeleton Expression

Period Filter

Examples

 <posts
     ...
     period="12h"
     ...
 />
 <posts
     ...
     period="7d"
     published_before_period="3d"
     ...
 />
 <posts
     ...
     period="7d"
     published_before_current_post="true"
     ...
 />

Attributes

  • period (default: lifetime) – allows only including posts published within the specified period ending now

    • 12h – loads posts published during the last 12 hours

    • 7d – loads posts published during the last 7 days

  • published_before_period – allows excluding posts published within the specified period ending now

    • 12h – loads posts published not later than 12 hours ago

    • 7d – loads posts published not later than 7 days ago

  • published_before_current_post – allows excluding posts published after the current one

    • Can be true or false

  • published_after – allows include only posts published after the specified date

    • Can be <Year>, <Year>-<Month>, <Year>-<Month>-<Day>, or <Year>-<Month>-<Day> <Hours>-<Minutes>-<Seconds>

  • published_before – allows include only posts published before the specified date

    • Can be <Year>, <Year>-<Month>, <Year>-<Month>-<Day>, or <Year>-<Month>-<Day> <Hours>-<Minutes>-<Seconds>

Buckets Filter

Examples

 <posts
     ...
     from_buckets_of_current_post="true"
     from_buckets_other_than="archive,sponsored"
     ...
 />
 <posts
     ...
     from_buckets_of_current_post_other_than="articles"
     from_buckets_other_than="archive,sponsored"
     ...
 />
 <posts
     ...
     from_buckets="articles"
     from_buckets_other_than="archive,sponsored"
     ...
 />

Attributes

  • from_buckets_of_current_post – allows including posts by any bucket of the current post

    • Can be true or false

  • from_buckets_of_current_post_other_than – allows including posts by any bucket of the current post other the specified ones

    • Can be a comma separated list of bucket slugs

    • Can be a Skeleton Expression

  • from_buckets – allows including posts by specific buckets

    • Can be a comma separated list of bucket slugs

    • Can be a Skeleton Expression

  • from_buckets_other_than – allows excluding posts by specific buckets

    • Can be a comma separated list of bucket slugs

    • Can be a Skeleton Expression

Modifiers

Load Page Views

For Roars

 <posts ...>
     <filters>
         <load_page_views
             bucket="~all~"
             period="lifetime"
             as="page_views"
         />
     </filters>
 </posts>

For Runners

 <posts ... load_page_views="true" />

Description

Both code snippets load PVs for each post into post[‘page_views’] variable