Struct Param 

pub struct Param { /* private fields */ }

One control at the top of a view.

Implementations

impl Param

pub fn select( key: impl Into<String>, label: impl Into<String>, options: impl IntoIterator<Item = impl Into<SelectOption>>, ) -> Self

A choice among options, which are rebuilt on every request like a schema is, so a select can be filled from a table.

Examples found in repository

examples/library/main.rs (line 577)

    fn params(&self, ctx: &Context, asked: &ViewArgs) -> Result<Vec<Param>, ApiError> {
        let branches = Self::branches(ctx)?;
        let options: 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();

        // A genre and one of its subgenres. The second list follows the first
        // one's answer, which is why `params` is told what was asked before
        // anything is settled. A subgenre belonging to the genre chosen last
        // time is no answer to the question being asked now, and falls back to
        // every subgenre of the genre chosen this time.
        let genres: Vec<Genre> = ctx.optional_rows(GENRES_FILE)?;
        let mut named: Vec<&str> = genres.iter().map(|g| g.genre.as_str()).collect();
        named.sort_unstable();
        named.dedup();

        let chosen = asked.get_or("genre", "");
        let mut subgenres: Vec<&str> = genres
            .iter()
            .filter(|g| g.genre == chosen)
            .map(|g| g.subgenre.as_str())
            .collect();
        subgenres.sort_unstable();

        Ok(vec![
            Param::select("branch", "Branch", options).default(first),
            Param::select("genre", "Genre", Self::any("Every genre", named)).default(""),
            Param::select(
                "subgenre",
                "Subgenre",
                Self::any("Every subgenre", subgenres),
            )
            .default(""),
            Param::string("author", "Author"),
        ])
    }

    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(),
        ])
    }

pub fn string(key: impl Into<String>, label: impl Into<String>) -> Self

Examples found in repository

examples/library/main.rs (line 585)

    fn params(&self, ctx: &Context, asked: &ViewArgs) -> Result<Vec<Param>, ApiError> {
        let branches = Self::branches(ctx)?;
        let options: 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();

        // A genre and one of its subgenres. The second list follows the first
        // one's answer, which is why `params` is told what was asked before
        // anything is settled. A subgenre belonging to the genre chosen last
        // time is no answer to the question being asked now, and falls back to
        // every subgenre of the genre chosen this time.
        let genres: Vec<Genre> = ctx.optional_rows(GENRES_FILE)?;
        let mut named: Vec<&str> = genres.iter().map(|g| g.genre.as_str()).collect();
        named.sort_unstable();
        named.dedup();

        let chosen = asked.get_or("genre", "");
        let mut subgenres: Vec<&str> = genres
            .iter()
            .filter(|g| g.genre == chosen)
            .map(|g| g.subgenre.as_str())
            .collect();
        subgenres.sort_unstable();

        Ok(vec![
            Param::select("branch", "Branch", options).default(first),
            Param::select("genre", "Genre", Self::any("Every genre", named)).default(""),
            Param::select(
                "subgenre",
                "Subgenre",
                Self::any("Every subgenre", subgenres),
            )
            .default(""),
            Param::string("author", "Author"),
        ])
    }

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

What the view is asked for when the address names nothing.

Examples found in repository

examples/library/main.rs (line 577)

    fn params(&self, ctx: &Context, asked: &ViewArgs) -> Result<Vec<Param>, ApiError> {
        let branches = Self::branches(ctx)?;
        let options: 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();

        // A genre and one of its subgenres. The second list follows the first
        // one's answer, which is why `params` is told what was asked before
        // anything is settled. A subgenre belonging to the genre chosen last
        // time is no answer to the question being asked now, and falls back to
        // every subgenre of the genre chosen this time.
        let genres: Vec<Genre> = ctx.optional_rows(GENRES_FILE)?;
        let mut named: Vec<&str> = genres.iter().map(|g| g.genre.as_str()).collect();
        named.sort_unstable();
        named.dedup();

        let chosen = asked.get_or("genre", "");
        let mut subgenres: Vec<&str> = genres
            .iter()
            .filter(|g| g.genre == chosen)
            .map(|g| g.subgenre.as_str())
            .collect();
        subgenres.sort_unstable();

        Ok(vec![
            Param::select("branch", "Branch", options).default(first),
            Param::select("genre", "Genre", Self::any("Every genre", named)).default(""),
            Param::select(
                "subgenre",
                "Subgenre",
                Self::any("Every subgenre", subgenres),
            )
            .default(""),
            Param::string("author", "Author"),
        ])
    }

    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(),
        ])
    }

pub fn hidden(self) -> Self

Draw no control for this parameter. It is for a parameter that arrives through a link rather than through the page—which story a detail page is about—where a control would be a second way to ask a question the reader has already asked. It is still declared, so it takes a default and is still handed to the view.

Examples found in repository

examples/library/main.rs (line 805)

    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(),
        ])
    }

pub fn key(&self) -> &str

Trait Implementations

impl Clone for Param

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 Param

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

Formats the value using the given formatter.

impl Serialize for Param

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

where __S: Serializer,

Serialize this value into the given Serde serializer.