Counts
A count reports how many records in a collection match a set of filters, written as a
phrase that reads correctly for one or many. It takes the same collection, any number of
count-filters (or a filter-any), a required count-message, and
an optional count-singular; {{count}} is the matching total:
<!-- localhoster:count collection="posts" -->
<!-- localhoster:count-filter field="status" op="eq" value="published" -->
<!-- localhoster:count-singular
```
{{count}} published post
``` -->
<!-- localhoster:count-message
```
{{count}} published posts
``` -->
… localhoster writes the count here …
<!-- localhoster:/count collection="posts" -->Filtering
count-filter takes the same field, op and value as a
listing filter; repeat it to require all of several (a count-singular is
optional, so this one shows just the message):
<!-- localhoster:count collection="posts" -->
<!-- localhoster:count-filter field="topic" op="contains" value="caddy" -->
<!-- localhoster:count-filter field="status" op="eq" value="published" -->
<!-- localhoster:count-message
```
{{count}} matching guides
``` -->
… localhoster writes the count here …
<!-- localhoster:/count collection="posts" -->| Parameter | Description |
|---|---|
field | the record field to test |
op | how to compare it, using the same operators as a listing filter: eq · ne · lt · lte · gt · gte · contains · starts · ends |
value | the value to compare against |
Filter Any
count-filter-any works just like the listing version: a paired block of plain
count-filters that passes a record matching any of them (OR):
<!-- localhoster:count collection="posts" -->
<!-- localhoster:count-filter-any -->
<!-- localhoster:count-filter field="status" op="eq" value="draft" -->
<!-- localhoster:count-filter field="status" op="eq" value="review" -->
<!-- localhoster:/count-filter-any -->
<!-- localhoster:count-message
```
{{count}} awaiting attention
``` -->
… localhoster writes the count here …
<!-- localhoster:/count collection="posts" -->Grouping
count-group collapses the matched records by a field before counting, so the
total reflects groups rather than rows, e.g. how many distinct categories have a post. It takes the same
by / using / order / start / count as a listing
group:
<!-- localhoster:count collection="posts" -->
<!-- localhoster:count-filter field="status" op="eq" value="published" -->
<!-- localhoster:count-group by="category" -->
<!-- localhoster:count-message
```
{{count}} categories with posts
``` -->
… localhoster writes the count here …
<!-- localhoster:/count collection="posts" -->Singular & Plural
count-message (required) is the phrase for any count; count-singular (optional)
replaces it when exactly one record matches. Omit the singular and the message is used
for one as well. Each is plain markup with one placeholder, {{count}}:
<!-- localhoster:count collection="posts" -->
<!-- localhoster:count-filter field="status" op="eq" value="draft" -->
<!-- localhoster:count-singular
```
<strong>{{count}}</strong> draft awaiting review
``` -->
<!-- localhoster:count-message
```
<strong>{{count}}</strong> drafts awaiting review
``` -->
… localhoster writes the count here …
<!-- localhoster:/count collection="posts" -->| Placeholder | Description |
|---|---|
{{count}} | the number of matching records |
Errors
A count is validated before it is written; a problem is reported against the page and the count, and the site is left unchanged until it is fixed (other sites still run):
| Message | When it appears |
|---|---|
count "…": a count needs a count-message template | no count-message (the required phrase) |
count "…" may not contain … | an unrecognised sub-command inside the count |
count "…": count-filter needs field="…" (also op, value) | a filter missing a required attribute |
count "…": count-filter op="…" is not one of … | an unknown comparison operator |
count "…": count-group needs by="…" | a count-group with no by field |
count "…": count-group order must be asc or desc | a group with an order other than asc/desc |
count "…": count-filter-any needs at least one count-filter | an empty filter-any block |
count "…": count-filter-any may only contain count-filter (found …) | a filter-any holding anything but plain filters |