Yew interface

The tables on this page are checked against the Rust source. A test reads the struct that backs each table and fails when a field, a type or a default differs from what is written here. The code blocks that show usage are regions of prose-yew/tests/site_examples.rs, which cargo test -p prose-yew compiles and renders on the server.

Four components exist: OdrlProse, OdrlProseView, ProseGlossary and ProseProblems. The first renders a policy given as JSON text. The second renders and edits a parsed document, and is controlled: it never changes the document, and the host applies every event it emits. Three hooks keep the host's state: use_prose_editor, use_prose_editor_with and use_validation.

OdrlProse #

A function component that renders ODRL JSON-LD as semantic HTML with prose_core::render_with. It emits no <style>. The host styles it through the prose-* classes, or through class on the root.

SharedWording wraps an Rc<Wording>. Two values are equal when they are the same Rc, so the component renders again only when the host hands it another Rc.

A policy that cannot be read renders <article class="ds-prose"><p class="prose-error" role="alert">. A struct literal of OdrlProseProps needs all six fields, because 0.4 added four of them; html! fills the defaults.

#[function_component(Reader)]
fn reader() -> Html {
    html! { <OdrlProse json={POLICY} /> }
}

From prose-yew/tests/site_examples.rs, region reader.

With a profile, the glossary switched off and a class:

#[function_component(ReaderWithWording)]
fn reader_with_wording() -> Html {
    let wording = SharedWording(Rc::new(Wording::new()));
    html! { <OdrlProse json={POLICY} wording={Some(wording)} glossary={false} class="my-prose" /> }
}

From prose-yew/tests/site_examples.rs, region reader_wording.

OdrlProseView #

Renders a parsed EditDoc in read or edit mode. In edit mode the slots are contenteditable, the selects and the add and remove buttons appear, and focus is managed. Every committed edit leaves through onedit as an EditEvent. A structural event whose new document has not arrived within 500 ms is treated as refused: focus does not move and nothing is announced.

The root is <article class="ds-prose prose-view {config.classes.root} [prose-edit [prose-reveal-hover]] {class}" tabindex="-1">. prose-edit is present only in edit mode, and prose-reveal-hover only in edit mode with Reveal::OnHoverOrFocus. In edit mode with base_css on, the first child of the root is the <style> element holding BASE_CSS. Read mode never writes a <style>.

#[function_component(ReadOnlyView)]
fn read_only_view() -> Html {
    let doc = use_memo((), |_| read_model(POLICY).unwrap_or_default());
    html! { <OdrlProseView doc={doc} /> }
}

From prose-yew/tests/site_examples.rs, region read_view.

The edit layer reads bare property keys only (permission, not odrl:permission, and no full IRIs). OdrlProse reads all three. A document written with prefixed keys renders in OdrlProse and reads as no rules in read_model.

EditMode #

• EditMode::Read (the default): the same sentences with display text and no controls.
• EditMode::Edit: contenteditable slots, selects, add and remove buttons, suggestions, issues and focus management.

ProseGlossary #

Renders the profile terms one policy uses as <details class="prose-glossary" open> with a <dl>. OdrlProse uses it for you. Use it directly to place a glossary elsewhere. It renders nothing for an empty glossary, and shows at most 30 entries.

ProseProblems #

The findings of a validation, grouped by rule, each with a "Go to" button and one button for each fix. See Validation.

Hooks #

A ready-made host. It owns the document, applies each event with the rules, and keeps an undo history capped at 50 entries.

pub fn use_prose_editor(initial: impl FnOnce() -> EditDoc, rules: Rc<EditRules>) -> ProseEditor
pub fn use_prose_editor_with(
    initial: impl FnOnce() -> EditDoc,
    rules: Rc<EditRules>,
    validator: Option<Validator>,
    policy: StrictEdit,
) -> ProseEditorWith
pub fn use_validation(doc: &Rc<EditDoc>, validator: Option<&Validator>) -> Rc<Report>

use_prose_editor is use_prose_editor_with(initial, rules, None, StrictEdit::Flag).editor. use_validation recomputes the report only when the document or the validator is another one. Without a validator it returns the advisory report of no profile, which has no findings.

#[function_component(Editor)]
fn editor() -> Html {
    let rules = use_memo((), |_| EditRules::default());
    let config = use_memo((), |_| EditConfig::default());
    let editor = use_prose_editor(|| read_model(POLICY).unwrap_or_default(), rules);
    html! {
        <OdrlProseView doc={editor.doc.clone()} mode={EditMode::Edit}
                       config={config} onedit={editor.onedit.clone()} />
    }
}

From prose-yew/tests/site_examples.rs, region editor.

ProseEditor #

What use_prose_editor returns. Pass doc and onedit to OdrlProseView.

ProseEditorWith #

What use_prose_editor_with returns. It is #[non_exhaustive]: do not build it with a struct literal.

StrictEdit #

What the reducer does with an event the loaded profiles do not allow. It is #[non_exhaustive].

• StrictEdit::Flag (the default): commit every edit the rules allow. The validator marks a violation as an error.
• StrictEdit::RefuseTerms: refuse, as EditError::OutsideProfile, an event that writes a term the validator does not allow into a vocabulary slot. It never applies to the empty string, free text, right operands, structural events or undo. The stock view asks the validator first and does not send such a term itself, so a refusal reaches only a host that bypasses the view.

After EditConfig::with_strict, give the hook Rc::new(cfg.rules.clone()) and cfg.validator.clone(). The reducer applies the rules it is handed, not the config's. A host that keeps EditRules::default() gets the defaults it set, not those with_strict made admissible.

EditConfig #

The whole configuration of an editing view. It is Clone, PartialEq and Default.

Two builders consume the config and return it:

pub fn with_wording(self, w: Rc<Wording>) -> EditConfig
pub fn with_strict(self, options: Options) -> EditConfig

with_wording uses the profiles and adds their terms to vocab under labels.group_profile, so set the labels first. with_strict validates against wording with options, usually Options::strict(), and rewrites rules.defaults (left operand, operator, action, policy type) so that what an add button creates is admissible. Call it after with_wording.

Choices that fix a name:

• ButtonContent::Symbol, ButtonContent::Text and ButtonContent::SymbolAndText (the default). The accessible name of a button is always the specific label, whatever it shows.
• Reveal::Always (the default) and Reveal::OnHoverOrFocus, which adds prose-reveal-hover to the root.

Labels #

Labels holds every word the editor writes: the section headings, the rule kinds, the empty states, the names of the buttons, the notes of the strict mode. Every field is public. Templates substitute {noun}, {n}, {field}, {owner}, {action}, {phrase} and {raw}, and in specific fields {profile}, {terms}, {note}, {kept}, {typed}, {label}, {suggestion}, {errors}, {warnings} and {notes}. When a button template has no {owner}, the owner chain is appended, so each button has a distinct name.

Keep the visible text of a button contained in its accessible name. A change of wording goes in a copy of Labels::default():

Nested wording #

nouns, fields and placeholders are structs of text. empty holds the texts shown where a list is empty, whose defaults come from prose-core.

Examples #

Every block above comes from prose-yew/tests/site_examples.rs. The remaining two are the configuration with your own CSS, which Styling explains, and the strict editor with the problems panel, which Validation explains.

The demo in demo/ is the full host: demo/src/edit.rs adds undo, the strict bar, issues and onjump.