Light logoJaspr

Document

The Document component sets up and controls the basic document structure.

The Document component helps you with the basic document structure of your website, the <html>, <head> and <body> elements. It has 5 constructors that setup or control separate aspects of the document.

  • The main Document() constructor and the Document.template() constructor setup the full document structure using either a set of child parameters or a template file respectively. These are only available on the server using the package:jaspr/server.dart import.

  • The Document.head(), Document.html() and Document.body() constructors control the respective elements separately by attaching child elements (for .head()) or setting attributes (for .html() and .body()). These can be used both on the server and on the client.

Document()

The Document() constructor helps you to set up a basic document structure at the root of your app. It renders the main <html>, <head> and <body> tags and takes a set of standard parameters, e.g. to set the title or meta attributes inside the <head>.

dart
lib/main.server.dart
void main() {
  runApp(Document(
    title: "My Site",
    meta: {
      "description": "My site description",
    },
    body: div(id: "main", []),
  ));
}

renders to:

html
index.html
&lt;!DOCTYPE html>
<html>
  <head>
    <base href="/"/>
    <meta charset="utf-8"/>
    <title>My Site</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <meta name="description" content="My site description"/>
  </head>
  <body>
    <div id="main"></div>
  </body>
</html>

Parameters

It takes the following parameters:

titleString?optional

Sets the title of your website.

baseString?optional

Sets the <base> tag of your website.

charsetString?optional

Sets the charset, defaults to 'utf-8'.

viewportString?optional

Sets the viewport for mobile devices, defaults to 'width=device-width, initial-scale=1.0'.

metaMap<String, String>optional

Sets additional <meta> properties.

stylesList<StyleRule>optional

A global set of style-rules, rendered as a <style> section inside <head>.

headList<Component>optional

Additional components to render inside <head>.

bodyComponentrequired

The component to render inside <body>.

Document.template()

The Document.template() constructor loads an external .template.html file from the filesystem and attaches the provided child component to that template.

It allows you to define the document markup in a separate html file instead of using the standard Document() constructor.

Parameters

nameStringoptional

The name of the template file to load, defaults to 'index'. The file is loaded from the web directory as web/<name>.template.html.

attachToStringoptional

The target element from the template to attach the child component to, defaults to 'body'.

childComponentrequired

The component to attach to the template.

Document.head()

The Document.head() constructor renders metadata and other elements inside the <head> of the document.

Any children are pulled out of the normal rendering tree of the application and rendered instead inside a special section of the <head> element of the document. This is supported both on the server during pre-rendering and on the client.

The .head() component can be used multiple times in an application where deeper or latter mounted components will override duplicate elements from other .head() components.

dart
Parent(children: [
  Document.head(
    title: "My Title",
    meta: {"description": "My Page Description"}
  ),
  Child(children: [
    Document.head(
      title: "Nested Title"
    ),
  ]),
]);

The above configuration of components will result in these elements inside <head>:

html
<head>
  <title>Nested Title</title>
  <meta name="description" content="My Page Description">
</head>

Elements inside .head() are overridden using the following system:

  • elements with an id override other elements with the same id
  • <title> and <base> elements override other <title> or <base> elements respectively
  • <meta> elements override other <meta> elements with the same name

Parameters

titleString?optional

Sets the <title> of your website.

metaMap<String, String>?optional

Sets additional <meta> properties.

childrenList<Component>?optional

Additional components to render inside <head>.

keyKey?optional

A key for this component.

Document.html()

The Document.html() constructor attaches a set of attributes to the <html> element.

This can be used at any point in the component tree and is supported both on the server during pre-rendering and on the client.

The .html() component can be used multiple times in an application where deeper or latter mounted components will override duplicate attributes from other .html() components.

Parameters

attributesMap<String, String>?optional

Sets additional attributes to the <html> element.

keyKey?optional

A key for this component.

Document.body()

The Document.body() constructor attaches a set of attributes to the <body> element.

This can be used at any point in the component tree and is supported both on the server during pre-rendering and on the client.

The .body() component can be used multiple times in an application where deeper or latter mounted components will override duplicate attributes from other .body() components.

Parameters

attributesMap<String, String>?optional

Sets additional attributes to the <body> element.

keyKey?optional

A key for this component.

🧹 Linting
RawText

On this page