Template:UI/guides library
Curated Guides library page. Drop
Guides
Tutorials, assembly guides, and how-tos contributed by the community.
18Guides8Distinct topics
into a content page (e.g. the wiki's Guides page) to
render a searchable, filterable view of the top-level guides in
Category:Guide — i.e. pages whose
Has document type is Guide.
Subguides (Has document type=Subguide) live under
Category:Guide for taxonomy but are excluded here so the library lists
only standalone guides; surface a guide's subguides on the guide page
itself via Property:Has parent guide backlinks.
Renders, top to bottom:
- Header — h1 title + lead paragraph + a stat strip showing
total guide count and distinct guide-topic count.
- Filtered guides list — an SRF
format=filtered
ask that pairs the Template:UI/guides_library/entry row partial with client-side filter controls for the Guide faceting properties.
Faceting kit
Reuses the same per-wiki page-typed faceting kit Category:Guide declared in #90:
- Guide topic (sidebar + row chip) — primary subject tag.
- Guide format (row chip only) — Tutorial, Assembly guide,
Quick start, Troubleshooting, … Still shown as the chip beside each title, but no longer a filter control.
- Workflow stage (sidebar) — Planning, Assembly, Surgery,
Recording, Analysis. Multi-valued, so a single guide can span stages.
- Audience level (row chip only) — Beginner / Intermediate /
Advanced. Still shown in the row kicker, but no longer a filter control.
- Target audience (sidebar) — PIs, Lab members, Devs, …
- Project (sidebar) — project-scoped browse.
Workflow stage, target audience, and project stay sidebar-only —
they're useful filters but per-row chips for all of them would
clutter rows. Same trade-off Publications + FAQs libraries make.
Guide format and audience level are intentionally display-only:
their printouts are still fetched (so the row chip and kicker
render) but carry no +filter=value, so they don't
appear in the filter sidebar.
Why format=filtered
Same rationale documented in Template:UI/publications_library
and Template:UI/faqs_library: SRF's filtered format gives a
single-page faceted browse without round-tripping to
Special:SearchByProperty. Filter sidebar chip list is
built client-side from the distinct values seen across the loaded
result set, so the controlling knob for facet coverage is the
limit parameter — too low a limit hides matching
guides from the filter UI.
Sort order
Descending by Has date (newest first), then ascending by Has name as a tiebreaker. Has date is required on Category:Document (Guide's parent), so every guide carries a date and the sort is total. The newest-first default matches user expectation for a documentation library ("what's new?") without losing browsability for older guides — they're one filter click away by topic or format.
Main-namespace filter
By default the directory excludes guides outside the main namespace,
so admin-namespace guides (e.g. Workshop admin:Onboarding)
stay out of the public library.
Implemented row-side: same pattern
Template:UI/recent_activity_feed uses (see its row template's
noinclude for the full reasoning). The library passes
userparam= through the
#ask, and Template:UI/guides_library/entry wraps
its entire output in a conditional — when the page is not in main
namespace AND userparam is empty, the row template
emits nothing at all (no empty wrapper, no whitespace).
SMW has no clean pre-query main-namespace condition: the
Namespace:+ idiom needs a namespace name and
main has none, and the ~ LIKE operator only matches
the dbkey (page name within namespace) so !~*:*
doesn't actually exclude pages in named namespaces — confirmed
against the live miniscope.org wiki. Row-side is the workaround
that actually works.
Known limitation: the KPI strip's "Guides" and "Distinct topics"
counts at the top of the page use format=count, which
runs server-side and doesn't iterate the row template. They count
the full set, including admin-
namespace guides, so the KPI count may exceed the visible row
count. The discrepancy is bounded by the number of non-main-namespace
guides and is usually small.
Set include_non_main=1 to disable the filter and
surface guides from every namespace (useful for an admin-facing
index page).
Parameters (all optional)
heading— page heading (default: "Guides"). Empty
string suppresses the <h1>.
lead— short intro paragraph below the heading
(default: a generic explainer).
limit— how many guides to load into the filtered
list (default: 200). Filtering happens client-side over the loaded result set; too low a limit hides matching guides from the filter UI.
include_non_main— set to any truthy value to
disable the main-namespace filter and include guides from every namespace. Matches the same opt-out convention used by Template:UI/recent_activity_feed.
Cross-template dependencies
- Template:UI/guides_library/entry — row partial for the
filtered list; handles the row-side namespace check.
- Template:UI/kpi_card — used for the stat strip.
- Semantic Result Formats with the filtered format enabled
($srfgFormatsincludesfiltered). The filtered-format JS/CSS resources must be loaded; without them the list will render but the filter sidebar will be inert.