Struct ViewData 

pub struct ViewData { /* private fields */ }

What one render of a view produced: a note about the whole of it, and the body it is to be read as.

The body is one of three: sections of rows, groups of cards, or one thing in detail. A view answers with one of them, and a view that built two is a failure naming both rather than a page that shows whichever the browser happened to look for first.

Implementations

impl ViewData

pub fn new() -> Self

Examples found in repository

examples/library/main.rs (line 628)

    fn render(&self, args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;
        let branches = Self::branches(ctx)?;
        let code = args.get_or("branch", "");
        let branch = branches.iter().find(|b| b.code == code);
        let named = branch.map(|b| b.name.as_str()).unwrap_or(code);

        let genre = args.get_or("genre", "");
        let subgenre = args.get_or("subgenre", "");
        let author = args.get_or("author", "").trim().to_lowercase();

        // The books this branch holds that answer the rest of the question,
        // whether they are out or not. A parameter left empty asks nothing.
        let held: Vec<&Book> = books
            .iter()
            .filter(|b| b.shelved.contains_key(code))
            .filter(|b| genre.is_empty() || b.genre == genre)
            .filter(|b| subgenre.is_empty() || b.subgenre == subgenre)
            .filter(|b| {
                author.is_empty()
                    || format!("{} {}", b.author_first, b.author_last)
                        .to_lowercase()
                        .contains(&author)
            })
            .collect();

        let now = today();
        let mut out = Vec::new();
        let mut overdue = Vec::new();
        for book in held.iter().filter(|b| b.lent.unwrap_or(false)) {
            let days = days_from_civil(&book.due).map(|due| now - due).unwrap_or(0);
            if days > 0 {
                overdue.push(OnLoan::row(book, days));
            } else {
                out.push(OnLoan::row(book, days));
            }
        }

        let lent = out.len() + overdue.len();
        Ok(ViewData::new()
            .note(format!(
                "{lent} of {} book(s) at {named} are out on loan. A title links to its catalogue entry.",
                held.len()
            ))
            .section(
                Section::new(OnLoan::columns())
                    .heading("Out")
                    .note("Days left before they are due.")
                    .rows(out)?,
            )
            .section(
                Section::new(OnLoan::columns())
                    .heading("Overdue")
                    .note("Days past due. Chase these.")
                    .rows(overdue)?,
            ))
    }
}

// ── The Branches view, which is a card per branch ────────────────────────────

/// Every branch as a card, grouped by whether it is open.
///
/// A card is what a view answers with when the question is "how do these things
/// stand" rather than "what are the values of these fields": there are no
/// columns here, and each card says how one branch stands, what it is called,
/// and two counts, with the whole card a link to the branch's own page.
struct BranchCards;

/// How many of the books a branch holds, and how many of those are out.
fn shelf_counts(books: &[Book], code: &str) -> (usize, usize) {
    let here: Vec<&Book> = books
        .iter()
        .filter(|b| b.shelved.contains_key(code))
        .collect();
    let out = here.iter().filter(|b| b.lent.unwrap_or(false)).count();
    (here.len(), out)
}

fn librarian(branch: &Branch) -> String {
    format!("{} {}", branch.librarian_first, branch.librarian_last)
        .trim()
        .to_string()
}

impl ViewLogic for BranchCards {
    fn name(&self) -> &'static str {
        "all-branches"
    }

    fn title(&self) -> &'static str {
        "All branches"
    }

    fn render(&self, _args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let branches: Vec<Branch> = ctx.optional_rows(BRANCHES_FILE)?;
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;

        let card = |branch: &Branch| {
            let (here, out) = shelf_counts(&books, &branch.code);
            let open = branch.open.unwrap_or(false);
            let mut card = Card::new(branch.name.as_str())
                .status(if open {
                    Status::new("Open", Tone::Good)
                } else {
                    // A shut branch is a fact about it rather than a fault, so
                    // it is neutral—which is also what reads quieter.
                    Status::new("Shut", Tone::Neutral)
                })
                .identifier(branch.code.as_str())
                .subtitle(format!(
                    "{}, {} staff",
                    librarian(branch),
                    branch.staff.unwrap_or(0)
                ))
                .row("Books here", here)
                .row("Out on loan", out)
                .link(ViewLink::new("branch").arg("branch", &branch.code));
            if branch.hours.is_empty() {
                card = card.sentence(
                    "No opening hours are recorded, so nothing here says when it can be visited.",
                );
            }
            card
        };

        let group = |heading: &str, open: bool| {
            CardGroup::new(heading).cards(
                branches
                    .iter()
                    .filter(|b| b.open.unwrap_or(false) == open)
                    .map(&card),
            )
        };

        Ok(ViewData::new()
            .note("A card is a branch. Open one for what it holds and what is out.")
            .group(group("Open", true))
            .group(group("Shut", false)))
    }
}

// ── The Branch view, which is one branch in detail ───────────────────────────

/// One branch: what it has out, what is on its shelves, and when it is open.
///
/// It is reached from a card rather than from the switcher, so its one
/// parameter is hidden: the page draws no control for it, and the card's link
/// is what answers it. The parameter is a select all the same, so a link to a
/// branch that has since gone falls back to the first one rather than to a page
/// about nothing.
struct BranchDetail;

impl BranchDetail {
    /// The books a branch holds, best rated first, which is the order the
    /// numbered section is a ranking in.
    fn by_rating<'a>(books: &'a [Book], code: &str, lent: bool) -> Vec<&'a Book> {
        let mut held: Vec<&Book> = books
            .iter()
            .filter(|b| b.shelved.contains_key(code) && b.lent.unwrap_or(false) == lent)
            .collect();
        held.sort_by(|a, b| {
            b.rating
                .unwrap_or(0.0)
                .total_cmp(&a.rating.unwrap_or(0.0))
                .then_with(|| a.title.cmp(&b.title))
        });
        held
    }

    /// What a form asks before a book goes out. The four kinds of field are all
    /// here, since this is the page the bundle's form controls are developed
    /// against.
    fn loan_form(title: &str) -> Form {
        Form::new("lend-a-book")
            .arg("title", title)
            .field(Field::text("borrower", "Borrower"))
            .field(Field::number("days", "Days out").default(21))
            .field(Field::date("from", "Date lent").default(civil_from_days(today())))
            .field(
                Field::one_of(
                    "condition",
                    "Condition it left in",
                    ["As new", "Good", "Worn"],
                )
                .default("Good"),
            )
    }
}

impl ViewLogic for BranchDetail {
    fn name(&self) -> &'static str {
        "branch"
    }

    fn title(&self) -> &'static str {
        "Branch"
    }

    /// This page is about one branch, and which one arrives through a card's
    /// link. A switcher entry for it would open whichever branch the parameter
    /// happens to default to, which is nobody's question.
    fn in_switcher(&self) -> bool {
        false
    }

    fn params(&self, ctx: &Context, _asked: &ViewArgs) -> Result<Vec<Param>, ApiError> {
        let branches: Vec<Branch> = ctx.optional_rows(BRANCHES_FILE)?;
        let codes: Vec<SelectOption> = branches
            .iter()
            .map(|b| SelectOption::labelled(&b.code, &b.name))
            .collect();
        let first = branches.first().map(|b| b.code.clone()).unwrap_or_default();
        Ok(vec![
            Param::select("branch", "Branch", codes)
                .default(first)
                .hidden(),
        ])
    }

    fn render(&self, args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let branches: Vec<Branch> = ctx.optional_rows(BRANCHES_FILE)?;
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;
        let code = args.get_or("branch", "");
        let branch = branches
            .iter()
            .find(|b| b.code == code)
            .ok_or_else(|| ApiError::new(404, format!("no branch has the code \"{code}\"")))?;

        let (here, out) = shelf_counts(&books, code);
        let now = today();

        // What is out, with how it stands against its due date. A row's own
        // link is the catalogue entry, and one book's link is a `javascript:`
        // URL, which the page shows as text rather than following.
        let mut lent = DetailSection::main("Out on loan");
        for book in BranchDetail::by_rating(&books, code, true) {
            let late = days_from_civil(&book.due).map(|due| now - due);
            let mut row = DetailRow::new(book.title.as_str()).link(book.link.as_str());
            if !book.due.is_empty() {
                row = row.fact(format!("due {}", book.due));
            }
            row = match late {
                Some(days) if days > 0 => row.fact(format!("{days} day(s) late")),
                Some(days) => row.fact(format!("{} day(s) to go", -days)),
                None => row.note("No due date is recorded."),
            };
            lent = lent.row(row.button(Button::disabled("Chase the borrower", "Not built yet")));
        }
        if out == 0 {
            lent = lent.note("Everything this branch holds is on the shelf.");
        }

        // What can go out, ranked, with the one action this example offers.
        let mut shelf = DetailSection::main("On the shelf")
            .numbered()
            .note("Best rated first.");
        for book in BranchDetail::by_rating(&books, code, false) {
            let mut row = DetailRow::new(book.title.as_str());
            if let Some(rating) = book.rating {
                row = row.fact(format!("rated {rating}"));
            }
            if let Some(year) = book.year {
                row = row.fact(year);
            }
            if !book.notes.trim().is_empty() {
                row = row.note(book.notes.as_str());
            }
            shelf = shelf.row(
                row.button(Button::link("Catalogue", book.link.as_str()))
                    .button(Button::form(
                        "Lend it out",
                        BranchDetail::loan_form(&book.title),
                    )),
            );
        }
        if here == out {
            shelf = shelf.note("Nothing this branch holds is on the shelf today.");
        }

        let mut hours = DetailSection::side("When it is open").collapsed_on_phone();
        for (day, open) in &branch.hours {
            hours = hours.row(DetailRow::new(day.as_str()).fact(open.as_str()));
        }
        if branch.hours.is_empty() {
            hours = hours.note("No hours are recorded for this branch.");
        }

        // A count per genre, which is a section of facts rather than of things
        // to do, so it sits beside the page rather than in it.
        let mut counts: BTreeMap<&str, usize> = BTreeMap::new();
        for book in books.iter().filter(|b| b.shelved.contains_key(code)) {
            *counts.entry(book.genre.as_str()).or_default() += 1;
        }
        let mut genres = DetailSection::side("Genres here");
        for (genre, count) in counts {
            genres = genres.row(DetailRow::new(genre).fact(count));
        }

        Ok(ViewData::new().detail(
            Detail::new(branch.name.as_str())
                .status(if branch.open.unwrap_or(false) {
                    Status::new("Open", Tone::Good)
                } else {
                    Status::new("Shut", Tone::Neutral)
                })
                .subtitle(format!(
                    "{}, {} staff, {here} book(s) here, {out} out",
                    librarian(branch),
                    branch.staff.unwrap_or(0)
                ))
                .back(ViewLink::new("all-branches"))
                .section(lent)
                .section(shelf)
                .section(hours)
                .section(genres),
        ))
    }

pub fn note(self, note: impl Into<String>) -> Self

Examples found in repository

examples/library/main.rs (lines 629-632)

    fn render(&self, args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;
        let branches = Self::branches(ctx)?;
        let code = args.get_or("branch", "");
        let branch = branches.iter().find(|b| b.code == code);
        let named = branch.map(|b| b.name.as_str()).unwrap_or(code);

        let genre = args.get_or("genre", "");
        let subgenre = args.get_or("subgenre", "");
        let author = args.get_or("author", "").trim().to_lowercase();

        // The books this branch holds that answer the rest of the question,
        // whether they are out or not. A parameter left empty asks nothing.
        let held: Vec<&Book> = books
            .iter()
            .filter(|b| b.shelved.contains_key(code))
            .filter(|b| genre.is_empty() || b.genre == genre)
            .filter(|b| subgenre.is_empty() || b.subgenre == subgenre)
            .filter(|b| {
                author.is_empty()
                    || format!("{} {}", b.author_first, b.author_last)
                        .to_lowercase()
                        .contains(&author)
            })
            .collect();

        let now = today();
        let mut out = Vec::new();
        let mut overdue = Vec::new();
        for book in held.iter().filter(|b| b.lent.unwrap_or(false)) {
            let days = days_from_civil(&book.due).map(|due| now - due).unwrap_or(0);
            if days > 0 {
                overdue.push(OnLoan::row(book, days));
            } else {
                out.push(OnLoan::row(book, days));
            }
        }

        let lent = out.len() + overdue.len();
        Ok(ViewData::new()
            .note(format!(
                "{lent} of {} book(s) at {named} are out on loan. A title links to its catalogue entry.",
                held.len()
            ))
            .section(
                Section::new(OnLoan::columns())
                    .heading("Out")
                    .note("Days left before they are due.")
                    .rows(out)?,
            )
            .section(
                Section::new(OnLoan::columns())
                    .heading("Overdue")
                    .note("Days past due. Chase these.")
                    .rows(overdue)?,
            ))
    }
}

// ── The Branches view, which is a card per branch ────────────────────────────

/// Every branch as a card, grouped by whether it is open.
///
/// A card is what a view answers with when the question is "how do these things
/// stand" rather than "what are the values of these fields": there are no
/// columns here, and each card says how one branch stands, what it is called,
/// and two counts, with the whole card a link to the branch's own page.
struct BranchCards;

/// How many of the books a branch holds, and how many of those are out.
fn shelf_counts(books: &[Book], code: &str) -> (usize, usize) {
    let here: Vec<&Book> = books
        .iter()
        .filter(|b| b.shelved.contains_key(code))
        .collect();
    let out = here.iter().filter(|b| b.lent.unwrap_or(false)).count();
    (here.len(), out)
}

fn librarian(branch: &Branch) -> String {
    format!("{} {}", branch.librarian_first, branch.librarian_last)
        .trim()
        .to_string()
}

impl ViewLogic for BranchCards {
    fn name(&self) -> &'static str {
        "all-branches"
    }

    fn title(&self) -> &'static str {
        "All branches"
    }

    fn render(&self, _args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let branches: Vec<Branch> = ctx.optional_rows(BRANCHES_FILE)?;
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;

        let card = |branch: &Branch| {
            let (here, out) = shelf_counts(&books, &branch.code);
            let open = branch.open.unwrap_or(false);
            let mut card = Card::new(branch.name.as_str())
                .status(if open {
                    Status::new("Open", Tone::Good)
                } else {
                    // A shut branch is a fact about it rather than a fault, so
                    // it is neutral—which is also what reads quieter.
                    Status::new("Shut", Tone::Neutral)
                })
                .identifier(branch.code.as_str())
                .subtitle(format!(
                    "{}, {} staff",
                    librarian(branch),
                    branch.staff.unwrap_or(0)
                ))
                .row("Books here", here)
                .row("Out on loan", out)
                .link(ViewLink::new("branch").arg("branch", &branch.code));
            if branch.hours.is_empty() {
                card = card.sentence(
                    "No opening hours are recorded, so nothing here says when it can be visited.",
                );
            }
            card
        };

        let group = |heading: &str, open: bool| {
            CardGroup::new(heading).cards(
                branches
                    .iter()
                    .filter(|b| b.open.unwrap_or(false) == open)
                    .map(&card),
            )
        };

        Ok(ViewData::new()
            .note("A card is a branch. Open one for what it holds and what is out.")
            .group(group("Open", true))
            .group(group("Shut", false)))
    }

pub fn section(self, section: Section) -> Self

Examples found in repository

examples/library/main.rs (lines 633-638)

    fn render(&self, args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;
        let branches = Self::branches(ctx)?;
        let code = args.get_or("branch", "");
        let branch = branches.iter().find(|b| b.code == code);
        let named = branch.map(|b| b.name.as_str()).unwrap_or(code);

        let genre = args.get_or("genre", "");
        let subgenre = args.get_or("subgenre", "");
        let author = args.get_or("author", "").trim().to_lowercase();

        // The books this branch holds that answer the rest of the question,
        // whether they are out or not. A parameter left empty asks nothing.
        let held: Vec<&Book> = books
            .iter()
            .filter(|b| b.shelved.contains_key(code))
            .filter(|b| genre.is_empty() || b.genre == genre)
            .filter(|b| subgenre.is_empty() || b.subgenre == subgenre)
            .filter(|b| {
                author.is_empty()
                    || format!("{} {}", b.author_first, b.author_last)
                        .to_lowercase()
                        .contains(&author)
            })
            .collect();

        let now = today();
        let mut out = Vec::new();
        let mut overdue = Vec::new();
        for book in held.iter().filter(|b| b.lent.unwrap_or(false)) {
            let days = days_from_civil(&book.due).map(|due| now - due).unwrap_or(0);
            if days > 0 {
                overdue.push(OnLoan::row(book, days));
            } else {
                out.push(OnLoan::row(book, days));
            }
        }

        let lent = out.len() + overdue.len();
        Ok(ViewData::new()
            .note(format!(
                "{lent} of {} book(s) at {named} are out on loan. A title links to its catalogue entry.",
                held.len()
            ))
            .section(
                Section::new(OnLoan::columns())
                    .heading("Out")
                    .note("Days left before they are due.")
                    .rows(out)?,
            )
            .section(
                Section::new(OnLoan::columns())
                    .heading("Overdue")
                    .note("Days past due. Chase these.")
                    .rows(overdue)?,
            ))
    }

pub fn group(self, group: CardGroup) -> Self

One group of cards. A group with no cards in it is dropped rather than drawn empty, so a view can name every group it knows about and let the data decide which of them the page has.

Examples found in repository

examples/library/main.rs (line 726)

    fn render(&self, _args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let branches: Vec<Branch> = ctx.optional_rows(BRANCHES_FILE)?;
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;

        let card = |branch: &Branch| {
            let (here, out) = shelf_counts(&books, &branch.code);
            let open = branch.open.unwrap_or(false);
            let mut card = Card::new(branch.name.as_str())
                .status(if open {
                    Status::new("Open", Tone::Good)
                } else {
                    // A shut branch is a fact about it rather than a fault, so
                    // it is neutral—which is also what reads quieter.
                    Status::new("Shut", Tone::Neutral)
                })
                .identifier(branch.code.as_str())
                .subtitle(format!(
                    "{}, {} staff",
                    librarian(branch),
                    branch.staff.unwrap_or(0)
                ))
                .row("Books here", here)
                .row("Out on loan", out)
                .link(ViewLink::new("branch").arg("branch", &branch.code));
            if branch.hours.is_empty() {
                card = card.sentence(
                    "No opening hours are recorded, so nothing here says when it can be visited.",
                );
            }
            card
        };

        let group = |heading: &str, open: bool| {
            CardGroup::new(heading).cards(
                branches
                    .iter()
                    .filter(|b| b.open.unwrap_or(false) == open)
                    .map(&card),
            )
        };

        Ok(ViewData::new()
            .note("A card is a branch. Open one for what it holds and what is out.")
            .group(group("Open", true))
            .group(group("Shut", false)))
    }

pub fn detail(self, detail: Detail) -> Self

Examples found in repository

examples/library/main.rs (lines 888-905)

    fn render(&self, args: &ViewArgs, ctx: &Context) -> Result<ViewData, ApiError> {
        let branches: Vec<Branch> = ctx.optional_rows(BRANCHES_FILE)?;
        let books: Vec<Book> = ctx.optional_rows(BOOKS_FILE)?;
        let code = args.get_or("branch", "");
        let branch = branches
            .iter()
            .find(|b| b.code == code)
            .ok_or_else(|| ApiError::new(404, format!("no branch has the code \"{code}\"")))?;

        let (here, out) = shelf_counts(&books, code);
        let now = today();

        // What is out, with how it stands against its due date. A row's own
        // link is the catalogue entry, and one book's link is a `javascript:`
        // URL, which the page shows as text rather than following.
        let mut lent = DetailSection::main("Out on loan");
        for book in BranchDetail::by_rating(&books, code, true) {
            let late = days_from_civil(&book.due).map(|due| now - due);
            let mut row = DetailRow::new(book.title.as_str()).link(book.link.as_str());
            if !book.due.is_empty() {
                row = row.fact(format!("due {}", book.due));
            }
            row = match late {
                Some(days) if days > 0 => row.fact(format!("{days} day(s) late")),
                Some(days) => row.fact(format!("{} day(s) to go", -days)),
                None => row.note("No due date is recorded."),
            };
            lent = lent.row(row.button(Button::disabled("Chase the borrower", "Not built yet")));
        }
        if out == 0 {
            lent = lent.note("Everything this branch holds is on the shelf.");
        }

        // What can go out, ranked, with the one action this example offers.
        let mut shelf = DetailSection::main("On the shelf")
            .numbered()
            .note("Best rated first.");
        for book in BranchDetail::by_rating(&books, code, false) {
            let mut row = DetailRow::new(book.title.as_str());
            if let Some(rating) = book.rating {
                row = row.fact(format!("rated {rating}"));
            }
            if let Some(year) = book.year {
                row = row.fact(year);
            }
            if !book.notes.trim().is_empty() {
                row = row.note(book.notes.as_str());
            }
            shelf = shelf.row(
                row.button(Button::link("Catalogue", book.link.as_str()))
                    .button(Button::form(
                        "Lend it out",
                        BranchDetail::loan_form(&book.title),
                    )),
            );
        }
        if here == out {
            shelf = shelf.note("Nothing this branch holds is on the shelf today.");
        }

        let mut hours = DetailSection::side("When it is open").collapsed_on_phone();
        for (day, open) in &branch.hours {
            hours = hours.row(DetailRow::new(day.as_str()).fact(open.as_str()));
        }
        if branch.hours.is_empty() {
            hours = hours.note("No hours are recorded for this branch.");
        }

        // A count per genre, which is a section of facts rather than of things
        // to do, so it sits beside the page rather than in it.
        let mut counts: BTreeMap<&str, usize> = BTreeMap::new();
        for book in books.iter().filter(|b| b.shelved.contains_key(code)) {
            *counts.entry(book.genre.as_str()).or_default() += 1;
        }
        let mut genres = DetailSection::side("Genres here");
        for (genre, count) in counts {
            genres = genres.row(DetailRow::new(genre).fact(count));
        }

        Ok(ViewData::new().detail(
            Detail::new(branch.name.as_str())
                .status(if branch.open.unwrap_or(false) {
                    Status::new("Open", Tone::Good)
                } else {
                    Status::new("Shut", Tone::Neutral)
                })
                .subtitle(format!(
                    "{}, {} staff, {here} book(s) here, {out} out",
                    librarian(branch),
                    branch.staff.unwrap_or(0)
                ))
                .back(ViewLink::new("all-branches"))
                .section(lent)
                .section(shelf)
                .section(hours)
                .section(genres),
        ))
    }

Trait Implementations

impl Clone for ViewData

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ViewData

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ViewData

fn default() -> Self

Returns the “default value” for a type.

impl Serialize for ViewData

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.