119 lines
4.7 KiB
C#
119 lines
4.7 KiB
C#
using System.Text.Json.Serialization;
|
|
|
|
namespace Elternbeirat.Contracts;
|
|
|
|
/// <summary>
|
|
/// A topic the FAQ entries are grouped under, as stored in PocketBase.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// A <see cref="Faq"/> points at its topic through a relation, so the FAQ page
|
|
/// groups the questions by topic and shows the groups in <see cref="Order"/>.
|
|
/// Making the topic its own record (rather than a free-text field on each
|
|
/// question) means the heading, its order and its optional <see cref="Intro"/>
|
|
/// are edited in one place and shared by every question in the group.
|
|
/// </remarks>
|
|
public record FaqTopic
|
|
{
|
|
/// <summary>
|
|
/// Gets the PocketBase record id.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <see langword="required"/>: every stored record has an id. Modeling it as
|
|
/// required states which fields a record must carry, independent of the store,
|
|
/// so a future data source has to supply them too.
|
|
/// </remarks>
|
|
[JsonPropertyName("id")]
|
|
public required string Id { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets the heading shown above the group of questions, e.g.
|
|
/// <c>"Mensa und Mittagessen"</c>.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Free text; may contain umlauts and spaces. For the URL, see <see cref="Slug"/>.
|
|
/// <see langword="required"/>: a topic without a heading has nothing to show, and
|
|
/// the field is required in PocketBase.
|
|
/// </remarks>
|
|
[JsonPropertyName("title")]
|
|
public required string Title { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets the URL slug of the topic, e.g. <c>"cafeteria"</c>.
|
|
/// </summary>
|
|
/// <value>
|
|
/// A URL path segment: lowercase letters, digits and single hyphens as
|
|
/// separators, no umlauts. PocketBase enforces this on save via a field
|
|
/// pattern (<c>^[a-z0-9]+(-[a-z0-9]+)*$</c>), so every stored slug is already
|
|
/// canonical and the app can use it verbatim.
|
|
/// </value>
|
|
/// <remarks>
|
|
/// <see langword="required"/>: the slug is required in PocketBase and is the
|
|
/// stable identifier of a topic, independent of its display title.
|
|
/// </remarks>
|
|
[JsonPropertyName("slug")]
|
|
public required string Slug { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets the optional introduction shown below the topic heading, as Markdown.
|
|
/// </summary>
|
|
/// <value>
|
|
/// The intro Markdown, or an empty string when the topic has none.
|
|
/// </value>
|
|
[JsonPropertyName("intro")]
|
|
public string Intro { get; init; } = string.Empty;
|
|
|
|
/// <summary>
|
|
/// Gets the sort order of the topic among the FAQ groups.
|
|
/// </summary>
|
|
/// <value>
|
|
/// The sort key; topics with smaller values appear first.
|
|
/// </value>
|
|
[JsonPropertyName("order")]
|
|
public double Order { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets the expanded relations returned by PocketBase, or <see langword="null"/>
|
|
/// when the query did not expand any.
|
|
/// </summary>
|
|
[JsonPropertyName("expand")]
|
|
public FaqTopicExpand? Expand { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets the questions of this topic, ordered by <see cref="Faq.Order"/>, or an
|
|
/// empty list when none are linked or the relation was not expanded.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Convenience over <see cref="Expand"/>: questions name their topic, so
|
|
/// PocketBase returns them under the back-relation key when the query expands it
|
|
/// (<c>faqs_via_topic</c>). The FAQ page reads them from here. They
|
|
/// arrive unsorted, so this orders them by <see cref="Faq.Order"/> for a stable
|
|
/// render. Drafts are dropped: PocketBase does not apply the topic query's
|
|
/// <c>public</c> filter to the expanded children, so this keeps
|
|
/// non-public questions (<see cref="Faq.Public"/>) off the page.
|
|
/// </remarks>
|
|
[JsonIgnore]
|
|
public IReadOnlyList<Faq> Faqs =>
|
|
Expand?.Faqs is { } faqs
|
|
? [.. faqs.Where(faq => faq.Public).OrderBy(faq => faq.Order)]
|
|
: [];
|
|
}
|
|
|
|
/// <summary>
|
|
/// The relations of a <see cref="FaqTopic"/> that PocketBase returns under
|
|
/// <c>expand</c> when the query asks for them.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// The questions point at their topic, so PocketBase exposes them as the
|
|
/// back-relation <c>faqs_via_topic</c>. <see cref="FaqTopic.Faqs"/> reads through
|
|
/// this.
|
|
/// </remarks>
|
|
public record FaqTopicExpand
|
|
{
|
|
/// <summary>
|
|
/// Gets the expanded questions of the <c>faqs_via_topic</c> back-relation, if it
|
|
/// was expanded.
|
|
/// </summary>
|
|
[JsonPropertyName("faqs_via_topic")]
|
|
public IReadOnlyList<Faq>? Faqs { get; init; }
|
|
}
|