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:
String? title: Sets the title of your website.String? base: Sets the<base>tag of your website.String? charset: Sets the charset, defaults to 'utf-8'.String? viewport: Sets the viewport for mobile devices, defaults to 'width=device-width, initial-scale=1.0'.Map<String, String>? meta: Sets additional<meta>properties.List<StyleRule>? styles: A global set of style-rules, rendered as a<style>section inside<head>.List<Component> head: Additional components to render inside<head>.Component body: 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
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.
- The
nameparameter defines the file to load, e.g.name: 'index'(default) loads theweb/index.template.htmlfile. - The
attachToparameter defined which target element from the template thechildcomponent to attach to, e.g.attachTo: 'body'(default) attaches it to thebodyelement.
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
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.
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.