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)current_page – converted into one of the following sources: frontpage, tag, or search
frontpage (see: Section Source (deprecated))
frontpage on Community/Author page (see: Collection Source (deprecated))
tag (see: Tag Source (deprecated))
search (see: Search Source (deprecated))
popular (see: Popular Source (deprecated))
filtered (see: Filtered Source)
collection (see: Collection Source)
river (see: River Source)
stream (see: Stream Source (deprecated))
multi (see: Multi Source)
source_id
(default:none
) – allows for the combination of several<posts />
elements into a single DB callUsually generated automatically based on the other attributes
source_unique
(default: false) – allows for the management of duplicateswithout_current
(default: false) – allows for the management of current post exclusionwithout_posts
(default:none
) – allows for the exclusion of explicitly specified postsCan 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 firstFor 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 searchCan 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 account12h – 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¶
page-views ordering does not work with
page-views ordering limitedly works with
IDs Filter (only exclusion)
Statuses Filter (phasing)
Sections Filter (failing when filtered by primary sections, phasing when has more than 1 included regular section, or has excluded sections, or
order_period
= lifetime)Period Filter (phasing)
relevance ordering limitedly works with
Statuses Filter (phasing)
manual ordering does not work with
manual ordering limitedly works with
IDs Filter (only exclusion)
Sections Filter (failing when has more than 1 included section, phasing when has excluded sections)
[bucket filter]
does not work with other filters
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 fromCan 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 postsCan 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 fromq
query parameter)Can be a specific phrase
Can be a Skeleton Expression
bucket
(default:none
) – allows for searching within a specific pre-defined bucketCan 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 is10 – the older results quickly become irrelevant
0 – the age of the result doesn’t influence how current it
Popular Source (deprecated)¶
Deprecated: please use attribute “order” by “page-views”. see Source Attributes
Example¶
<posts
source="popular"
period="lifetime"
[sections filter]
limit="20"
/>
Attributes¶
period
(default: 1h) – allows specifying period ending now for Page Views to be taken into the account12h – loads posts ordered by PVs from the last 12 hours
7d – loads posts ordered by PVs from the last 7 days
lifetime – loads posts ordered by total number of PVs
[sections filter]
(see: Sections Filter)
Notes¶
Posts from this tag are being loaded after all the other posts loaded
River Source¶
Example¶
<posts
source="river"
user_id="{{request.user.id}}"
limit="20"
/>
Attributes¶
user_id
– requires specifying a particular user ID for accessing RiverCan 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 poststype
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 whentype="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 fromCan 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 fromCan 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 sectionsCan 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 IDsCan 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 typesCan be a comma separated list of types
Can be a Skeleton Expression
from_types_other_than
– allows excluding posts by specific typesCan be a comma separated list of types
Can be a Skeleton Expression
Types¶
article – TBD
image – TBD
video – TBD
event – TBD
place – TBD
recipe – TBD
product – TBD
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 statusesCan be a comma separated list of statuses
Can be a Skeleton Expression
from_statuses_other_than
– allows excluding posts by specific statusesCan be a comma separated list of statuses
Can be a Skeleton Expression
If neither specified, applies
from_statuses="roar"
behavior
Statuses¶
admin – TBD
featured – TBD
community – TBD
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 postCan 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 onesCan be a comma separated list of section slugs
Can be a Skeleton Expression
from_primary_sections
– allows including posts by specific primary sectionsCan be a comma separated list of section slugs
Can be a Skeleton Expression
from_primary_sections_other_than
– allows excluding posts by specific primary sectionsCan 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 postCan 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 onesCan be a comma separated list of section slugs
Can be a Skeleton Expression
from_regular_sections
– allows including posts by specific sectionsCan be a comma separated list of section slugs
Can be a Skeleton Expression
from_regular_sections_other_than
– allows excluding posts by specific sectionsCan 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 postCan be true or false
from_communities_of_current_post_other_than
– allows including posts by any community of the current post other the specified onesCan be a comma separated list of community slugs
Can be a Skeleton Expression
from_communities
– allows including posts by specific communitiesCan be a comma separated list of community slugs
Can be a Skeleton Expression
from_communities_other_than
– allows excluding posts by specific communitiesCan be a comma separated list of community slugs
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 now12h – 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 now12h – 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 oneCan be true or false
published_after
– allows include only posts published after the specified dateCan be <Year>, <Year>-<Month>, <Year>-<Month>-<Day>, or <Year>-<Month>-<Day> <Hours>-<Minutes>-<Seconds>
published_before
– allows include only posts published before the specified dateCan 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 postCan be true or false
from_buckets_of_current_post_other_than
– allows including posts by any bucket of the current post other the specified onesCan be a comma separated list of bucket slugs
Can be a Skeleton Expression
from_buckets
– allows including posts by specific bucketsCan be a comma separated list of bucket slugs
Can be a Skeleton Expression
from_buckets_other_than
– allows excluding posts by specific bucketsCan 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