Posts
=====

.. contents:: :depth: 3

General Usage
-------------

Example
*******

.. code:: xml

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

.. code:: xml

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

.. _source_attributes:

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`_)

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

  - `Types Filter`_
  - `Authors Filter`_
  - `Tags Filter`_

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

  - `Types Filter`_
  - `Authors Filter`_
  - `Tags Filter`_
  - `Statuses Filter`_
  - `Period Filter`_

- *manual* ordering **limitedly** works with

  - `IDs Filter`_ (only exclusion)
  - `Sections Filter`_ (failing when has more than 1 included section, phasing when has excluded sections)

- ``[request filter]`` does not work with other filters


Collection Source
*****************

Example
#######

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

    <posts
        ...
        from_primary_sections_of_current_post="true"
        from_primary_sections_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_primary_sections_of_current_post_other_than="news"
        from_primary_sections_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_primary_sections="news"
        from_primary_sections_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_regular_sections_of_current_post="true"
        from_regular_sections_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_regular_sections_of_current_post_other_than="news"
        from_regular_sections_other_than="politics,sport"
        ...
    />

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

    <posts
        ...
        from_primary_tags_of_current_post="true"
        from_primary_tags_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_primary_tags_of_current_post_other_than="news"
        from_primary_tags_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_primary_tags="news"
        from_primary_tags_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_regular_tags_of_current_post="true"
        from_regular_tags_other_than="politics,sport"
        ...
    />

.. code:: xml

    <posts
        ...
        from_regular_tags_of_current_post_other_than="news"
        from_regular_tags_other_than="politics,sport"
        ...
    />

.. code:: xml

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

.. code:: xml

    <posts
        ...
        period="12h"
        ...
    />

.. code:: xml

    <posts
        ...
        period="7d"
        published_before_period="3d"
        ...
    />

.. code:: xml

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


AI Filter
*********

Examples
########

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: xml

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

.. code:: shell

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

.. code:: xml

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

Description
###########

Loads PVs for each post into `post['page_views']` variable

Force Preload Meta tag
**********************

.. code:: xml

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

Description
###########

Adds preload meta tag of the `<posts />` element in the head of the HTML document

.. code:: html

    <link fetchpriority="high" rel="preload" imagesrcset="{}" as="image">

Notes:
######

- If posts has more than 1 post to render (limit attribute) it will render for the first post image only.

You could find more details and examples here_.

.. _here: https://docs.google.com/document/d/1AHYrr0eEX-mkk_6S-7Isns7_n6-H71NkfiylRPIbwHc