Posts ¶

Contents

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: none)
- current_page – converted into filtered with filters for the current page: Home, Author, Section, Tag, Search
- filtered (see: Filtered Source)
- collection (see: Collection Source)
- river (see: River Source)
- multi (see: Multi Source)
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]
    [request filter]
    [ai 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)
[request filter] (see: Request Filter)
[ai filter] (see: AI Filter)
order (default: newest)
- newest – for the most recent results to appear at the top
- oldest – for the least recent results to appear at the top
- manual – for manually set order to be used
- title – for ordering by title
- none – for not forcing any order (required for the Request Filter)
- 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
- similarity – for ordering by similarity to the AI prompt

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)
[buckets filter] does not work with other filters
[request filter] does not work with other filters

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

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

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.

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¶

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 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¶

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 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

AI Filter ¶

Examples¶

<posts
    ...
    ai-engine="open-ai"
    ai-prompt="select some interesting posts for me"
    ai-collection="some-collection"  <!-- optional -->
    ai-embeddings-version="2"  <!-- optional, default 1 -->
    ...
/>

<posts
    ...
    ai-engine="open-ai"
    ai-prompt="!select-related-posts({{page.post.id}})"
    ...
/>

<posts
    ...
    ai-engine="open-ai"
    ai-prompt="!select-related-posts([{{page.post.id}},45678901,23456789], weights=5,3,1&param1=value1&param2=value2)"
    ...
/>

<posts
    ...
    ai-engine="open-ai"
    ai-prompt="!select-posts-from-kappa({{page.post.id}}, param1=value1&param2=value2)"
    ...
/>

Attributes¶

ai-engine – allows to choose AI backend to use
- Can be open-ai only for now
ai-prompt – allows to specify the prompt to be sent to the AI backend
- Can be a Skeleton Expression
ai-collection – allows to specify the collection to be used by the AI backend
- Can be a Skeleton Expression
ai-embeddings-version – allows to specify the embeddings version to be used by the AI backend

Request Filter ¶

Examples¶

<posts
    ...
    request-href="https://demo0715986.mockable.io/posts"
    request-method="GET"
    request-timeout="3"
    request-use_proxies="false"
    order="none"
    ...
/>

<posts
    ...
    request-href="https://demo0715986.mockable.io/posts/search?q={{request.GET.q}}"
    request-method="POST"
    request-payload="something to be sent as the body"
    request-headers="{&quot;Header-X&quot;: &quot;some header value&quot;}"
    request-timeout="3"
    request-use_proxies="true"
    order="none"
    ...
/>

Expected Response from the Endpoint¶

% curl -X POST 'https://demo0715986.mockable.io/posts/search?q=hello+world' -H 'Content-Length: 0'
{
  "hits": {
    "hits": [
      {"_id": "2650127784"},
      {"_id": "2650142835"},
      {"_id": "2650142837"},
      {"_id": "2650142831"},
      {"_id": "2650142825"}
    ]
  }
}

Attributes¶

request-href – defines the endpoint to access
request-method – defines a HTTP method to access the endpoint with (default: GET)
- Can be GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, or TRACE
request-payload – allows to submit a payload to the endpoint with an appropriate method
request-headers – allows to specify custom headers to be sent to the endpoint. Should be in JSON format escaped for XML
request-timeout – defines a timeout in seconds for the request (default: 3)
request-use_proxies – allows to use proxies for the request (default: true)
- Can be true or false

Modifiers ¶

Load Page Views ¶

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

Description¶

Loads PVs for each post into post[‘page_views’] variable