Search
Meerkat

Meerkat

Basic Filtering

Meerkat filters allow you to quickly locate the precise data you need to implement your front end designs.

#Default Filters

Meerkat applies some filters by default to account for the most common use cases when rendering your comment threads. These default filters automatically remove soft deleted comments, spam comments, and comments that have not been approved (or published). If this is all you need, there are no extra steps on your end and you can just use the following snippet:

1{{ meerkat:responses }}
2 
3 {{ comments }}
4 <!-- Render your comment thread. -->
5 {{ /comments }}
6 
7{{ /meerkat:responses }}

For more information on how to build comment threads, consider checking out the The Comment Thread guide.

#Simple Filter Parameters

Beyond the default filters, Meerkat also offers a handful of simple filter parameters that can be used (Meerkat filters can get much more powerful, but we will get into that later). These filter parameters are:

Filter Description Type Default
with_trashed Indicates if soft deleted comments should be included. bool false
include_spam Indicates if spam comments should be included. bool false
include_unapproved Indicates if unapproved should be included. bool false

The following is an example of how these may be used:

1{{ meerkat:responses with_trashed="false" include_spam="true" }}
2 
3<ul>
4 {{ comments }}
5 <li>
6 <p>{{ author.name }} says: {{ content }}</p>
7 </li>
8 {{ /comments }}
9</ul>
10 
11{{ /meerkat:responses }}

Important Note Regarding Truthiness

The simple default parameters operate strictly on the "truthiness" of the underlying comment value. For example, include_spam="true/false" can only select between comments that are spam or not spam; this simple filter cannot select comments that are neither. We will cover this scenario in a more advanced section.

#An Introduction to Filter Expressions

The basic filters cover the vast majority of filtering use-cases, but do not account for everything. Because of this, Meerkat's responses tag accepts a filter parameter. The filter parameter accepts a single filter expression as its only argument. Filter expressions are an incredibly powerful way to request data from the underlying Meerkat query engine.

Filter expressions are string values that contain the filtering instructions; multiple filters can be supplied by separating them with a pipe | character. Before we get too far into the details, let's revisit the example of using the basic spam filter:

1{{ meerkat:responses include_spam="true" }}
2 
3<ul>
4 {{ comments }}
5 <li>
6 <p>{{ author.name }} says: {{ content }}</p>
7 </li>
8 {{ /comments }}
9</ul>
10 
11{{ /meerkat:responses }}

We could rewrite this as a filter expression like so:

1{{ meerkat:responses filter="is:spam(true)" }}
2 
3<ul>
4 {{ comments }}
5 <li>
6 <p>{{ author.name }} says: {{ content }}</p>
7 </li>
8 {{ /comments }}
9</ul>
10 
11{{ /meerkat:responses }}

Remember how the default include_spam can only check if a comment is either spam or not spam? We can use filter expressions to request a comment that is either (or null) by supplying a wildcard value (*) as the argument:

1{{ meerkat:responses filter="is:spam(*)" }}
2 
3<ul>
4 {{ comments }}
5 <li>
6 <p>{{ author.name }} says: {{ content }}</p>
7 </li>
8 {{ /comments }}
9</ul>
10 
11{{ /meerkat:responses }}

By using the wildcard argument (*) Meerkat will return comments that are either spam or not spam or null. Filters can be chained by using the pipe | character; the following example will use filter expressions to return approved comments that are not spam:

1{{ meerkat:responses filter="is:published(true)|is:spam(false)" }}
2 
3<ul>
4 {{ comments }}
5 <li>
6 <p>{{ author.name }} says: {{ content }}</p>
7 </li>
8 {{ /comments }}
9</ul>
10 
11{{ /meerkat:responses }}

Order Matters!

When chaining comment filters, Meerkat will take the results of one filter and supply that as the input to the next filter. In the previous example, the is:published filter would receive the entire list of comments and the is:spam filter would only receive those comments that are published (as filtered by the is:published filter).

If you've developed a custom filter that is computationally expensive, consider using simpler filters first to reduce the total number of comments the expensive filter will operate on to improve performance.

Filter expressions are an incredibly powerful way to ask Meerkat for specific data. In fact, the simple default filters like with_trashed and include_spam are converted to filter expressions behind the scenes. While specifying additional filters using filter expressions will work with the simple default filters, it is highly recommended you choose one or the other, depending on the use case.

#Default Expression Filters

Now that we have a basic idea of how filter expressions work, lets take a look at the default filters that are available to you when using filter expressions. There are a large number of built-in filters, organized into "namespaces".

Namespaces are just a syntactical way to organize filters, and serve no functional purpose. In the previous section we were introduced to the is:published filter; in this case, the namespace name is is (namespaces are anything comes before the first :). Care has been taken to organize the defaults filters in a way that reads well, and there are some filters that could have belonged to a different namespace but were placed elsewhere to help developers internalize what the filter will do.

The following table lists all of the provided filters:

Filter Description Accepts
is:before Returns comments received before a specified date. UNIX timestamp, or a parsable date string.
is:after Returns comments received after a specified date. UNIX timestamp, or a parsable date string.
is:between Returns comments received between two dates. UNIX timestamps, or two parsable date strings, separated by a comma (,).
is:spam Filters comments based on their current spam status. Boolean or wildcard (*) value.
is:published Filters comments based on their current published status. Boolean or wildcard (*) value.
is:deleted Filters comments based on their current soft deleted status. Boolean or wildcard (*) value.
like Filters using a comment property and a SQL-like pattern. A comment data attribute and a search pattern.
not:like Filters comments where the provided property does not match the SQL-like pattern. A comment data attribute and a search pattern.
search:terms Filters comments using a full-text search. The search terms.
thread:in Filters comments to only those that appear in the specified threads. A list of thread identifiers.
not:thread:in Filters comments to only those that do not appear in the specified threads. A list of thread identifiers.
user:from_auth Filters comments based on if they were left by an authenticated user or not. Boolean or wildcard (*) value.
user:in Filters comments to only those left by authenticated users that appear in the specified users.. A list of user identifiers.
not:user:in Filters comments to only those left by authenticated users that do not appear in the specified users. A list of user identifiers.
where Filters comments based on whether or not a property comparison to a check value is true. A comment property, a comparison operator, and a comparison value.
where:in Filters comments based on whether a property appears in a list of values. A comment property, and a list of values to check against.
not:where:in Filters comments based on whether a property does not appear in a list of values. A comment property, and a list of values to check against.

#Supplying Multiple Parameters

By taking a quick scan of that table, you may notice that some filters accept multiple parameters. Parameters are separated by a comma (,). For example, if we wanted to filter our comments to only those left by an authenticated user in a known list, we could do so like so (whitespace will be trimmed for you automatically):

1{{ meerkat:responses filter="user:in(92283631-5e22-4e21-8764-0aad0cf59bfe, 6f2d63ce-e760-4c5b-85ad-7ddbaf7d7ada)" }}
2 
3<ul>
4 {{ comments }}
5 <li>
6 <p>{{ author.name }} says: {{ content }}</p>
7 </li>
8 {{ /comments }}
9</ul>
10 
11{{ /meerkat:responses }}

Don't want to include long list inputs in your template code? You can use Custom Variable Input to dynamically inject values from PHP code - even if PHP support is disabled for Antlers templates.

#Defining Custom Filters

Meerkat's data query system supports custom filters, as well. Please consult the Advanced Filtering article to learn how to create custom filters, filter groups, and more.

Some absolutely amazing
people

The following amazing people help support this site and my open source projects ♥️
If you're interesting in supporting my work and want to show up on this list, check out my GitHub Sponsors Profile.