Struct Element

pub struct Element<'a> { /* private fields */ }

Implementations

impl<'a> Element<'a>

pub const fn new(tag: &'a str) -> Self

pub fn class(self, cls: &'a str) -> Self

Assign a class to this element.

use sidoc_html5::Element;
let element = Element::new("p")
  .class("warning");

pub fn class_r(&mut self, cls: &'a str) -> &mut Self

Assign a class to this element in-place.

use sidoc_html5::Element;
let mut element = Element::new("p");
element.class_r("warning");

pub fn flag(self, key: &'a str) -> Self

Assign a “flag attribute” to the element.

Flag attributes do not have (explicit) values, and are used to mark elements as selected or checked and such.

use sidoc_html5::Element;
let element = Element::new("input")
  .raw_attr("type", "checkbox")
  .flag("checked");

pub fn flag_r(&mut self, key: &'a str) -> &mut Self

pub fn flag_if(self, f: bool, key: &'a str) -> Self

Conditionally add a flag attribute.

Flag attributes do not have (explicit) values, and are used to mark elements as selected or checked and such.

use sidoc_html5::Element;
for id in &[1, 2, 3] {
  let element = Element::new("option")
    .flag_if(*id == 3, "selected");
}

pub fn attr(self, key: &'a str, value: impl AsRef<str>) -> Self

Add an attribute.

The attribute value is escaped as needed.

Note: If the value is guaranteed not to require escaping then prefer the Element::raw_attr() method instead.

use sidoc_html5::Element;
let elem = Element::new("input")
  .attr("name", "foo");

pub fn attr_if<V>(self, flag: bool, key: &'a str, value: V) -> Self

where V: AsRef<str>,

Conditionally add an attribute.

The value is escaped as needed.

pub fn data_attr(self, key: &'a str, value: impl AsRef<str>) -> Self

Add a data--prefixed attribute.

The attribute value is escaped as needed.

use sidoc_html5::Element;
let elem = Element::new("tr")
  .data_attr("name", "foo");

pub fn data_attr_r(&mut self, key: &'a str, value: impl AsRef<str>) -> &mut Self

pub fn data_flag(self, key: &'a str) -> Self

pub fn data_flag_if(self, flag: bool, key: &'a str) -> Self

Conditionally add a boolean data- attribute.

Add a data-foo=true attribute to an element:

use sidoc_html5::Element;
let val = 7;
let elem = Element::new("p")
  .data_flag_if(val > 5, "foo");

pub fn optattr<T>(self, key: &'a str, value: Option<T>) -> Self

where T: AsRef<str>,

Add an attribute if its optional value is Some(); ignore it otherwise.

The value is escaped as needed.

Note: If the value is guaranteed to not needing escaping then prefer the Element::raw_optattr() method instead.

use sidoc_html5::Element;
let something = Some("something");
let nothing: Option<&str> = None;
let elem = Element::new("form")
  .optattr("id", something)
  .optattr("name", nothing);

pub fn optattr_map<T, F>(self, key: &'a str, value: Option<T>, f: F) -> Self

where F: FnOnce(&T) -> String,

If an an optional input value is set, apply a function on the contained value to allow it to generate the actual attribute value. Do nothing if the optional value is None.

The value returned by the closure is escaped as needed.

use sidoc_html5::Element;
let something = Some("something");
let elem = Element::new("p")
  .optattr_map("id", something, |v| {
    // Have a value -- format it and append "-aboo" to it.
    format!("{}-aboo", v)
  });

pub fn map_attr<T, F>(self, key: &'a str, value: Option<T>, f: F) -> Self

where F: FnOnce(&T) -> String,

pub fn opt_map<T, F>(self, value: Option<&T>, f: F) -> Self

where F: FnOnce(Self, &T) -> Self,

If an an optional input value is set, apply a function on the contained value.

pub fn map<T, F>(self, value: Option<&T>, f: F) -> Self

where F: FnOnce(Self, &T) -> Self,

pub fn map_opt<T, F>(self, o: Option<T>, f: F) -> Self

where F: FnOnce(Self, T) -> Self,

If an an optional input value is set, apply a function on the contained value.

use sidoc_html5::Element;
let opt_str = Some("enabled");
Element::new("body")
  .map_opt(opt_str, |this, s| {
    this.flag(s)
  });

pub fn map_attr_if<T, F>(self, flag: bool, key: &'a str, data: &T, f: F) -> Self

where F: FnOnce(&T) -> String,

Conditionally call a function to add an attribute with a generated value.

use sidoc_html5::Element;
let sv = vec!["foo".to_string(), "bar".to_string()];
Element::new("body")
  .map_attr_if(!sv.is_empty(), "data-mylist", &sv, |v: &Vec<String>| {
    v.join(",")
  });

pub fn map_if<F>(self, flag: bool, f: F) -> Self

where F: FnOnce(Self) -> Self,

Conditionally call a closure to modify self if a predicate is true.

use sidoc_html5::Element;
let someval = 42;
Element::new("body")
  .map_if(someval == 42, |obj| obj.flag("selected"));

pub fn mod_if<F>(&mut self, flag: bool, f: F) -> &mut Self

where F: FnOnce(&mut Self),

Conditionally call a closure to modify self, in-place, if a predicate is true.

use sidoc_html5::Element;
let someval = 42;
let mut e = Element::new("body");
e.mod_if(someval == 42, |obj| {
  obj.flag_r("selected");
});

impl<'a> Element<'a>

Methods that don’t transform the input.

pub fn raw_attr(self, key: &'a str, value: impl ToString) -> Self

Add an attribute.

The attribute value is not escaped.

use sidoc_html5::Element;
let elem = Element::new("form")
  .raw_attr("id", "foo");

pub fn raw_optattr<T>(self, key: &'a str, value: Option<&T>) -> Self

where T: ToString,

Add an attribute if its optional value is Some(); ignore it otherwise.

The value is assumed not to require escaping.

use sidoc_html5::Element;
let ss = "something".to_string();
let something = Some(&ss);
let nothing = None::<&String>;
let elem = Element::new("form")
  .raw_optattr("id", something)
  .raw_optattr("name", nothing);

pub fn raw_attr_if(self, flag: bool, key: &'a str, value: impl ToString) -> Self

Add an attribute if a condition is true.

The attribute value is not escaped.

impl<'a> Element<'a>

pub fn sub<F>(self, bldr: &mut Builder, f: F)

where F: FnOnce(&mut Builder),

Call a closure for adding child nodes.

use sidoc_html5::Element;
let mut bldr = sidoc::Builder::new();
Element::new("div")
  .sub(&mut bldr, |bldr| {
    Element::new("br")
      .add_empty(bldr);
});

Panics

If the extra-validation feature is enabled, panic if the tag name is not a known “void” element.

impl<'a> Element<'a>

Methods inserting element into a sidoc context.

pub fn add_empty(self, bldr: &mut Builder)

Consume self and add a empty tag representation of element to a sidoc builder.

An empty/void tag comes is one which does not have a closing tag: <tagname foo="bar">.

Panics

If the extra-validation feature is enabled, panic if the tag name is not a known “void” element.

pub fn add_content(self, text: &str, bldr: &mut Builder)

Consume self and add a tag containing text content between the opening and closing tag to the supplied sidoc builder.

The supplied text is escaped as needed.

use sidoc_html5::Element;
let mut bldr = sidoc::Builder::new();
let elem = Element::new("textarea")
  .raw_attr("rows", 8)
  .raw_attr("cols", 32)
  .add_content("This is the text content", &mut bldr);

The example above should generate: <textarea rows="8" cols="32">This is the text content</textarea>

Panics

If the extra-validation feature is enabled, panic if the tag name is not a known “void” element.

pub fn add_raw_content(self, text: &str, bldr: &mut Builder)

Consume self and add a tag containing text content between the opening and closing tag to the supplied sidoc builder.

The supplied text is not escaped.

use sidoc_html5::Element;
let mut bldr = sidoc::Builder::new();
let elem = Element::new("button")
  .add_raw_content("Do Stuff", &mut bldr);

The example above should generate: <button>Do Stuff</button>

Panics

If the extra-validation feature is enabled, panic if the tag name is not a known “void” element.

pub fn add_opt_content<T>(self, text: &Option<T>, bldr: &mut Builder)

where T: AsRef<str>,

Panics

If the extra-validation feature is enabled, panic if the tag name is not a known “void” element.

pub fn add_scope(self, bldr: &mut Builder)

Panics

If the extra-validation feature is enabled, panic if the tag name is not a known “void” element.

pub fn scope<F>(self, bldr: &mut Builder, f: F)

where F: FnOnce(&mut Builder),

Add an Element to a new scope in a sidoc::Builder, and call a closure to allow child nodes to be added within the scope.

use std::sync::Arc;
use sidoc_html5::Element;

let mut bldr = sidoc::Builder::new();
let elem = Element::new("div")
  .scope(&mut bldr, |bldr| {
    let elem = Element::new("button")
      .add_raw_content("Do Stuff", bldr);
  });

let mut r = sidoc::RenderContext::new();
let doc = bldr.build().unwrap();
r.doc("root", Arc::new(doc));
let buf = r.render("root").unwrap();

// Output should be:
// <div>
//   <button>Do Stuff</button>
// </div>
assert_eq!(buf, "<div>\n  <button>Do Stuff</button>\n</div>\n");