How blog locks work
v0.0.1
A lock keeps a post, a collection or a tag to the readers who hold a permission. You set it in the record's Permissions field. This page explains which record locks which, and where a lock applies: on the record's page, in lists and counts, in the language dropdown, in the sitemap, in comments and in the API. For the steps to lock a page or a post, see Lock a page or post to members. For permission names and wildcards, see How permissions work.
What a lock is
The Permissions field holds permission names. Left empty, everyone may open the record. With names in it, only a reader who holds at least one of them may open it. The names can be any in the permission catalogue, admin or not, except a name that starts with admin:api:, which opens for nobody. A master can create a name such as members:read and grant it to a group of readers.
The field's help text reads Who may open this post: anyone holding one of these. None: everyone. A collection and a tag say the same of themselves.
Which record locks which
| Record | It opens with |
|---|---|
| Collection | Its own permissions. If it names none, those of the nearest parent collection that names some. |
| Post | Its own permissions. If it names none, those of the locked collections it is filed under, each as that collection opens. Holding one of any of them is enough. A collection that names no lock adds no way in, so a post filed under one locked and one open collection is locked. A post in no locked collection is public. |
| Tag | Its own permissions, and nothing else. A tag locks only its own page, because a tag is only attached to posts. |
| Comment | Its post's. |
| Blogger, team | They have no Permissions field, so the record itself cannot be locked. The page that shows them can be. |
What a record names itself always wins over what it would take from above. A post with its own permissions ignores the locks of its collections.
Where a lock applies
- The record's page. A post, collection or tag page opens only for readers who hold one of its names. A reader who holds none gets the site's not-found page, whether signed in or not, so the refusal does not confirm the page exists. The page also tells search engines not to index it. The record's names are checked after the page's own.
- Lists, counts and search. Every block that reads records reads as the visitor, so a locked record is left out of the list and the search results. Every count covers only the published posts that visitor may open: the number beside a category, a tag or a blogger, the total on a category's, tag's, blogger's or team's own page, and the number the search box gives for the posts it searches. The number beside a category counts the posts in its own language, and the number beside a tag in the tag cloud counts the posts in every language. The tag cloud's default order,
popular, sorts by that count. A category or a tag with no post the visitor may open is left out of its block while the block'shide_emptyis on, which is the default. - Languages. The header's language dropdown and the head's alternate links offer only the editions the reader may open, so the address and title of a locked edition are not shown to a reader it is locked from.
- The sitemap. A record that opens with a permission is left out.
- Comments, ratings, bookmarks and votes. A reader can write one on a locked post, or vote on one of its comments, only if the reader may open the post. Otherwise the action is refused with Post not found or does not belong to your site. or Comment not found or does not belong to your site.
- The API. A reader list leaves out what the caller may not open. A locked post, collection or tag asked for by itself answers not found (404), the same as an id that is not stored. A category's or a tag's
published_post_countcounts only what the caller may open, and the API refuses a filter on it.
The admin screens are not filtered by locks. They follow the blog's admin permissions instead. See Blog permissions.
Details that can surprise you
- A collection locks its posts while it exists, whatever its status. Setting a locked collection to Draft does not open the posts filed under it. A deleted collection no longer counts.
- A post filed under two locked collections opens for a reader who may open either one.
- A team can carry permissions of its own, but its members do not inherit them. Every check reads the permissions a user holds.
- A page that shows a kind of record can be locked too, in the page's own Permissions field. While every active page that shows posts is locked to permissions a reader does not hold, that reader gets no post in a list, a count, the search or the API, and the comments of those posts go with them. Categories, tags, bloggers and teams follow the same rule for their own pages.
- Changing a record's permissions, or a reader's, takes effect on the next check. A reader who is already on the page is checked again as well. See How permissions work.
Example: a members-only collection
A site publishes a series for paying members. A master creates the permission members:read, and the site's owner grants it to each member. The owner then opens the series' collection, adds members:read to Permissions and saves.
- Every post filed under that collection and naming no permissions of its own now needs
members:read. - Members open the posts. A guest who follows a link, and a signed-in reader who is not a member, both see the not-found page.
- The posts and the collection disappear from the blog's lists, search and sitemap for everyone else, and the count of a tag that those posts carry drops to the posts the reader may open.
- Comments on those posts are visible and writable only to members.