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:

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

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

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:

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

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