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 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 thepackage:jaspr/server.dartimport. -
The
Document.head(),Document.html()andDocument.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 can only be used on the server and is only available using the package: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 takes 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 takes the following parameters:
titleString?optionalSets the title of your website.
baseString?optionalSets the <base> tag of your website.
charsetString?optionalSets the charset, defaults to 'utf-8'.
viewportString?optionalSets the viewport for mobile devices, defaults to 'width=device-width, initial-scale=1.0'.
metaMap<String, String>optionalSets additional <meta> properties.
stylesList<StyleRule>optionalA global set of style-rules, rendered as a <style> section inside <head>.
headList<Component>optionalAdditional components to render inside <head>.
bodyComponentrequiredThe component to render inside <body>.
Document.template()
The Document.template() constructor can only be used on the server and is only available using the
package: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 markup in a separate html file instead of using the standard Document() constructor.
Parameters
nameStringoptionalThe name of the template file to load, defaults to 'index'. The file is loaded from the web directory as web/<name>.template.html.
attachToStringoptionalThe target element from the template to attach the child component to, defaults to 'body'.
childComponentrequiredThe 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.
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>:
<head>
<title>Nested Title</title>
<meta name="description" content="My Page Description">
</head>
Note that 'deeper or latter' here does not result in a true DFS ordering. Components that are mounted deeper but prior will override latter but shallower components.
Elements inside .head() are overridden using the following system:
- elements with an
idoverride other elements with the sameid <title>and<base>elements override other<title>or<base>elements respectively<meta>elements override other<meta>elements with the samename
Parameters
titleString?optionalSets the <title> of your website.
metaMap<String, String>?optionalSets additional <meta> properties.
childrenList<Component>?optionalAdditional components to render inside <head>.
keyKey?optionalA 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.
Note that 'deeper or latter' here does not result in a true DFS ordering. Components that are mounted deeper but prior will override latter but shallower components.
Parameters
attributesMap<String, String>?optionalSets additional attributes to the <html> element.
keyKey?optionalA 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.
Note that 'deeper or latter' here does not result in a true DFS ordering. Components that are mounted deeper but prior will override latter but shallower components.