> ## Content Index
> Fetch the complete content index at: https://getpublii.com/dev/llms.txt
> Use this file to discover other available public pages before exploring further.

# {{getPostsByCustomFields}}

- URL: https://getpublii.com/dev/getpostsbycustomfields/
- Published: 2024-03-04T07:51:11.838Z
- Updated: 2024-03-09T10:20:14.746Z
- Description: 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…
- Author: Tomasz Dziuda
- Tags: Helpers

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:

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

Example: 

```handlebars
{{#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