{{getPostsByCustomFields}}

The {{getPostsByCustomFields}} helper is designed to retrieve post data based on the criteria defined by custom fields. This powerful feature allows for more precise control over which posts are displayed, based on custom criteria beyond the standard tags and categories.

Syntax

The basic syntax for {{getPostsByCustomFields}} involves specifying a query string that includes several parameters to define the search criteria:

{{#getPostsByCustomFields "PARAMETERS"}}
    <h2>{{ title }}</h2>
    <div>{{{ excerpt }}}</div>
{{/getPostsByCustomFields}}

Example: 

{{#getPostsByCustomFields "count=5&customField=indexTest1&customFieldValue=XYZ&customFieldCompare=not-equals"}}
    <h2>{{ title }}</h2>
    <div>{{{ excerpt }}}</div>
{{/getPostsByCustomFields}}

This example will display up to 5 posts where the custom field indexTest1 does not equal XYZ.

QueryString Options

• count: Specifies the number of posts to include in the result. Use -1 to return all posts matching the criteria.
• allowed: Defines which post statuses should be included (e.g., hidden, featured). If not specified, defaults to including all published posts.
• customField: Indicates the custom field to filter posts by.
• customFieldValue: Specifies the expected value of the custom field for a post to be included in the results.
• customFieldCompare: Defines how to compare the custom field's value with customFieldValue. Options include:
  • equals (default): Selects posts where the custom field value matches customFieldValue.
  • not-equals: Selects posts where the custom field value does not match customFieldValue.
  • greater, greater-equals, lesser, lesser-equals: For numeric comparisons.
  • starts-with, ends-with, contains, not-contains: For string comparisons.
• excluded: Lists IDs of posts to exclude from the results.
• excluded_status: Lists post statuses to explicitly exclude.
• offset: Sets the number of posts to skip from the beginning of the result set.
• orderby: Determines the field by which to order the results. Can be a standard field or a customField.
• ordering: Specifies the direction of sorting (e.g., asc, desc, random).
• orderbyCompareLanguage: If orderby=customField, allows specifying the locale for sorting, useful for language-specific sorting rules.

Detailed customFieldCompare Options

The customFieldCompare parameter in the {{getPostsByCustomFields}} helper allows for flexible comparisons between the specified customFieldValue and the values within the custom fields of posts. Understanding the available options for this parameter can significantly broaden your content display's customization and filtering capabilities.

Available  Values

• equals (default value): Selects posts where the custom field's value exactly matches the customFieldValue.
• not-equals: Selects posts where the custom field's value does not match the customFieldValue.
• greater: Targets posts where the custom field's value is greater than the customFieldValue. This is primarily used for numerical comparisons.
• greater-equals: Selects posts where the custom field's value is greater than or equal to the customFieldValue, again mainly for numerical values.
• lesser: Filters for posts where the custom field's value is less than the customFieldValue, suitable for numeric comparisons.
• lesser-equals: Chooses posts where the custom field's value is less than or equal to the customFieldValue, used for numbers.
• starts-with: Finds posts where the custom field's value begins with the sequence specified in customFieldValue.
• ends-with: Filters posts where the custom field's value ends with the sequence specified in customFieldValue.
• contains: Selects posts where the custom field's value contains the sequence specified in customFieldValue.
• not-contains: The opposite of contains; it selects posts where the custom field's value does not contain the specified sequence.

Understanding these options allows for precise control over which posts are retrieved based on custom field values, offering a powerful tool for customizing the display of content on your site.

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