Writing HTML

How to write concise html markup in Jaspr.

With jaspr, you write html as part of your component tree. Each html tag (like div, p, img, etc.) has an assigned method you can use (reps. div(), p(), img(), etc.).

Let's look at the following html snippet:

<div>
  <h1>This is a title</h1>
  <p>Hello <b>World!</b></p>
</div>

Within a jaspr component, this can be represented as such:

div([
  h1([text('This is a title')]),
  p([text('Hello '), b([text('World!')])]),
]);

The special text() method does not add a html tag but renders plain text inside other elements.

HTML utilities

There exist methods for the most common html tags, like div, a, p, img as well as more special tags like video, form, input and others.

Each method has the following signature:

Component <tagname>(List<Component> children, {
  Key? key,
  String? id,
  String? classes,
  Styles? styles,
  Map<String, String>? attributes,
  Map<String, EventCallback>? events,
});

In addition to these parameters some methods have tag-specific attributes, like img(src: "...") or a(href: "...").

For readability, it is recommended to put the list of child components last in the parameter list: div(id: "main", [text('Hello World')]) is more readable than div([text('Hello World')], id: "main"). In case of no children specify an empty list ([]). Some tags also omit this parameter, like img.

Try it out on JasprPad

Finally, here are some more examples of this syntax. You can switch between the dart code and rendered html output.

  p([text('This is some '),b([text('html')]),text(' content.')])

  <p>This is some <b>html</b> content.</p>

h1(styles: Styles.text(color: Colors.blue), [text('Hello Jaspr!')])

<h1 style="color: blue;">Hello Jaspr!</h1>

  a(href: "https://github.com/schultek/jaspr", target: Target.blank, [
    img(src: "https://jasprpad.schultek.de/jaspr-192.png"),
  ])

  <a href="https://github.com/schultek/jaspr" target="_blank">
    <img src="https://jasprpad.schultek.de/jaspr-192.png" />
  </a>

  select([
    option(value: 'test', [text('Select me!')]),
    option(value: 'other', selected: true, [text('Or me!')])
  ])

  <select>
    <option value="test">Select me!</option>
    <option value="other" selected>Or me!</option>
  </select>

progress(value: 85, max: 100, [])

<progress value="85" max="100"></progress>

Lower-Level Components

DomComponent

Under the hood, every html element in jaspr is represented by a DomComponent, which is a special component that takes a tag, some other parameters and a list of children, which can again be other DomComponents.

If you want to, you can write DomComponents manually instead of using the utility methods. This gives you great low-level control over your html structure, but is more verbose.

  var component = DomComponent(
    tag: 'div',
    id: 'my-id',
    classes: 'class-a class-b',
    styles: Styles.text(color: Colors.black),
    attributes: {'my-attribute': 'my-value'},
    events: {'click': (e) => print('clicked')},
    children: [
      /* ... */
    ],
  );

Using this component would render the following html:

<div id="my-id" style="color: red" class="class-a class-b" my-attribute="my-value">
  ...
</div>

Text

A simple component that renders a text node. The text() method simply returns a Text component.

A text node in html is just some standalone string that is placed inside another html element. Therefore the Text component also only receives a single string to render to the page.

  var text = Text('Hello World!');

As usual for web, styling is done through a combination of CSS attributes, either in a Stylesheet or inline though the styles attribute of the parent elements.