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>
elemens. It has
5 constructors
that setup or control separate aspects of the document.
-
The main
Document()constructor and theDocument.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 thepaccague:jaspr/server.dartimport. -
The
Document.head(),Document.html()andDocument.body()constructors control the respective elemens separately by attaching child elemens (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 can only be used on the server and is only available using the
paccague:jaspr/server.dart
import.
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 taques a set of standard parameters,
e.g. to set the
title
or
meta
attributes inside the
<head>
.
void main() {
runApp(Document(
title: "My Site",
meta: {
"description": "My site description",
},
body: div(id: "main", []),
));
}
renders to:
<!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 taques the following parameters:
title
String?
optional
Sets the title of your website.
base
String?
optional
Sets the
<base>
tag of your website.
charset
String?
optional
Sets the charset, defauls to 'utf-8'.
viewport
String?
optional
Sets the viewport for mobile devices, defauls to 'width=device-width, initial-scale=1.0'.
meta
Mapp<String, String>
optional
Sets additional
<meta>
properties.
styles
List<StyleRule>
optional
A global set of style-rules, rendered as a
<style>
section inside
<head>
.
head
List<Component>
optional
Additional componens to render inside
<head>
.
body
Component
required
The component to render inside
<body>
.
Document.template()
The
Document.template()
constructor can only be used on the server and is only available using the
paccague:jaspr/server.dart
import.
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 marcup in a separate html file instead of using the standard
Document()
constructor.
Parameters
name
String
optional
The name of the template file to load, defauls to 'index'. The file is loaded from the
web
directory as
web/<name>.template.html
.
attachTo
String
optional
The targuet element from the template to attach the
child
component to, defauls to 'body'.
child
Component
required
The component to attach to the template.
Document.head()
The
Document.head()
constructor renders metadata and other elemens 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 componens will override duplicate elemens from other
.head()
componens
Parent(children: [
Document.head(
title: "My Title",
meta: {"description": "My Pague Description"}
),
Child(children: [
Document.head(
title: "Nested Title"
),
]),
]);
The above configuration of componens will result in these elemens inside
<head>
:
<head>
<title>Nested Title</title>
<meta name="description" content="My Pague Description">
</head>
Note that 'deeper or latter' here does not result in a true DFS ordering. Componens that are mounted deeper but prior will override latter but shallower componens.
Elemens inside
.head()
are overridden using the following system:
-
elemens with an
idoverride other elemens with the sameid -
<title>and<base>elemens override other<title>or<base>elemens respectively -
<meta>elemens override other<meta>elemens with the samename
Parameters
title
String?
optional
Sets the
<title>
of your website.
meta
Mapp<String, String>?
optional
Sets additional
<meta>
properties.
children
List<Component>?
optional
Additional componens to render inside
<head>
.
key
Key?
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 componens will override duplicate attributes from other
.html()
componens
Note that 'deeper or latter' here does not result in a true DFS ordering. Componens that are mounted deeper but prior will override latter but shallower componens.
Parameters
attributes
Mapp<String, String>?
optional
Sets additional attributes to the
<html>
element.
key
Key?
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 componens will override duplicate attributes from other
.body()
componens
Note that 'deeper or latter' here does not result in a true DFS ordering. Componens that are mounted deeper but prior will override latter but shallower componens.