{{#getPostsByTags}} helper

{{getPostsByTags}} is a helper used to retrieve post data regardless of the current context and filter them to posts which uses a specific tag.

This helper since Publii 0.34 have a improved and more powerful syntax. Read more.

Syntax:

{{#getPostsByTags NUMBER_OF_POSTS TAG_ID "EXCLUDED_POST_ID_1,EXCLUDED_POST_ID_2"}}
...
{{/getPostsByTags}}

Example:

{{#getPostsByTags 5 1 "3,4"}}
<li>
    <h2>{{ title }}</h2>
    <div>{{{ excerpt }}}</div>
</li>
{{/getPostsByTags}}

Above example will show up to 5 posts, which uses tag with ID = 1, excluding posts with post ID equal to 3 or 4.

Posts are ordered by the same order as specified in the site settings.

You can also use tag slugs:

{{#getPostsByTags 5 "lorem,ipsum" ""}}
<li>
    <h2>{{ title }}</h2>
    <div>{{{ excerpt }}}</div>
</li>
{{/getPostsByTags}}

In the above example, code will show up to 5 posts, which uses tags with slug equal to "lorem" or "ipsum". No posts will be excluded.

If the number of posts will be set to -1 then all posts with given tags will be returned.

IMPORTANT: It requires availability of the @website.contentStructure global variable

New syntax available since Publii 0.34

Since Publii 0.34 this helper supports new syntax with querystring instead of many arguments:

{{#getPostsByTags "count=5&allowed=hidden,featured&tag_as=id&tags=1,2,3&excluded=1,2&offset=10&orderby=modifiedAt&ordering=asc"}} 
    <h2>{{ title }}</h2> 
    <div>{{{ excerpt }}}</div> 
{{/getPostsByTags}}

Query string param supports the following options:

• count: Defines the number of posts to be included in the results. This parameter limits the total number of posts returned.
• allowed: Specifies which post statuses should be included in the results. When this parameter is not explicitly specified, it defaults to any, including all posts with a published status, excluding those moved to trash or drafts. Specific statuses can be included by listing them, separated by commas e.g. hidden, published, featured, excluded (excluded from homepage),
• excluded_status: Lists post statuses that should be explicitly excluded from the results. Like the allowed parameter, multiple statuses can be specified, separated by commas (e.g., hidden, published, featured, excluded). 
• tags: Indicates the tags to filter posts by. Depending on the tag_as parameter, tags can be identified either by their IDs or slugs.
• excluded: Lists the IDs of posts that should be excluded from the results, ensuring specific posts are omitted.
• offset: Sets the number of posts to skip from the beginning of the result set.
• orderby: Determines the field by which the results should be ordered, such as publishedAt, modifiedAt, customField (more about the customField read below).
• ordering: Specifies the direction or method of sorting the results. Options include asc for ascending, desc for descending, and now random for a random order. The random option is particularly useful when displaying posts in a non-deterministic order, offering a diverse experience on each page load.
• tag_as: Chooses whether tags are selected by id or slug, ensuring accurate tag identification for filtering.
• operator: Defines the logical operation to apply when filtering by multiple tags. AND requires all specified tags to be associated with a post for it to be selected, while OR allows for selecting posts that contain any of the specified tags.

It is possible to combine querystring options with theme option values using the concatenate helper:

{{#getPostsByTags (concatenate "count=" @config.custom.amountOfPosts "&allowed=hidden,featured&tag_as=id" "&excluded_status=hidden" "&tags=" @config.custom.TagsDropdown
 "&excluded=1,2&offset=1&orderby=modifiedAt&ordering=asc")}}  
    <h2>{{ title }}</h2> 
    <div>{{{ excerpt }}}</div> 
{{/getPostsByTags}}

Sorting by Custom Fields in Posts

Since version 0.45, Publii introduces an advanced feature allowing users to order posts based on custom fields. This functionality allows for more flexible and dynamic post display options, catering to specific sorting criteria beyond the default fields like publishedAt or title. The orderby=customField parameter in conjunction with the customField=name parameter enables sorting by the specified custom field.

Syntax for Sorting by Custom Fields

To sort posts by a custom field, use the orderby parameter with the value customField and specify the name of the custom field using the customField parameter. Here's the syntax:

{{#getPostsByTags "count=5&tag_as=id&tags=1,2,3,4&orderby=customField&customField=indexTest1&ordering=desc&operator=OR"}}
    <h2>{{ title }}</h2>
    <div>{{{ excerpt }}}</div>
{{/getPostsByTags}}

In the example above, posts are sorted in descending order (ordering=desc) based on the custom field value named indexTest1. The operator=OR indicates that posts with any specified tags (tags=1,2,3,4) will be included.

Sorting Logic

The sorting logic depends on the content of the custom fields:

• Numeric Content: Sorting is performed numerically if the custom field contains numeric values. Note that numeric values are rounded to the nearest integer using parseInt() for comparison purposes.
• Textual Content: The sorting uses the localeCompare function for custom fields containing text. This ensures that the sorting considers locale-specific rules, making it particularly useful for text-based sorting criteria.

Language-Specific Sorting

To accommodate language-specific sorting rules, especially when sorting text fields, you can use the orderbyCompareLanguage parameter. This parameter allows you to specify the locale for sorting, ensuring that sorting behavior is consistent with language-specific conventions. For instance, adding orderbyCompareLanguage=pl enables sorting based on Polish language rules. This feature is beneficial when automatic language detection might not work as expected or when specific sorting behavior is required for a particular language.

{{#getPostsByTags "count=5&tag_as=id&tags=1,2,3,4&orderby=customField&customField=indexTest1&ordering=desc&operator=OR&orderbyCompareLanguage=pl"}}
    <h2>{{ title }}</h2>
    <div>{{{ excerpt }}}</div>
{{/getPostsByTags}}