Pinning Selected Documents to the Top of a DocLister Listing

A donor question about DocLister raised a very reusable listing pattern: keep the normal ordering logic, but push selected resources to the top of the result set.

In the original case, the listing was already sorted by menuindex. The missing piece was an extra TV flag such as “show on top” that should override the default order without replacing it entirely.

Why this is useful

• You can promote featured items without rebuilding the whole query model.
• You keep a predictable fallback order for everything else.
• Editors get a simple on/off control instead of micromanaging positions everywhere.

Conceptually, this is a two-level sort: featured documents first, normal documents after that, then the existing order inside each group.

That makes the pattern worth documenting because it works for pets, products, news, staff cards, and any listing that needs a lightweight “pin first” control.