0
# Document Management
1
2
Complete HTML document creation and management with automatic structure generation, metadata handling, and content organization.
3
4
## Capabilities
5
6
### Document Class
7
8
Creates a complete HTML document with proper DOCTYPE, head, and body structure. Automatically sets up common sections (header, main, footer) and provides direct access to document components.
9
10
```python { .api }
11
class document(html):
12
def __init__(self, title='Dominate', doctype='<!DOCTYPE html>', *a, **kw):
13
"""
14
Create a new HTML document.
15
16
Parameters:
17
- title (str): Document title, defaults to 'Dominate'
18
- doctype (str): DOCTYPE declaration, defaults to '<!DOCTYPE html>'
19
- *a: Additional child elements
20
- **kw: Additional attributes
21
"""
22
```
23
24
#### Usage Example
25
26
```python
27
from dominate import document
28
from dominate.tags import *
29
30
# Create document with custom title
31
doc = document(title='My Website')
32
33
# Access document components
34
print(doc.title) # 'My Website'
35
print(doc.head) # <head> element
36
print(doc.body) # <body> element
37
38
# Document automatically includes header, main, footer containers
39
print(doc.header) # container for header content
40
print(doc.main) # container for main content
41
print(doc.footer) # container for footer content
42
```
43
44
### Title Management
45
46
Get and set the document title with automatic HTML element management.
47
48
```python { .api }
49
@property
50
def title(self) -> str:
51
"""Get the document title text."""
52
53
@title.setter
54
def title(self, value: str | html_tag):
55
"""
56
Set the document title.
57
58
Parameters:
59
- value: String for simple title, or html_tag for complex title element
60
"""
61
```
62
63
#### Usage Example
64
65
```python
66
doc = document()
67
68
# Get title
69
current_title = doc.title
70
71
# Set simple title
72
doc.title = 'New Title'
73
74
# Set complex title with custom element
75
doc.title = title('Complex Title', lang='en')
76
```
77
78
### Content Addition
79
80
Add content directly to the document body or to specific sections.
81
82
```python { .api }
83
def add(self, *args):
84
"""
85
Add elements to the document body (main section by default).
86
87
Parameters:
88
- *args: Elements to add to the document
89
90
Returns:
91
- Added elements (single element if one arg, tuple if multiple)
92
"""
93
```
94
95
#### Usage Example
96
97
```python
98
doc = document(title='My Site')
99
100
# Add content to main section (default)
101
doc.add(h1('Welcome'))
102
doc.add(p('This is the main content.'))
103
104
# Add to specific sections
105
with doc.header:
106
nav(ul(li(a('Home', href='/'))))
107
108
with doc.footer:
109
p('© 2023 My Company')
110
111
# Multiple elements at once
112
heading, content = doc.add(h2('Section'), div(cls='content'))
113
```
114
115
### Document Rendering
116
117
Render the complete document with DOCTYPE and proper HTML structure.
118
119
```python { .api }
120
def _render(self, sb, *args, **kwargs):
121
"""
122
Render the complete document including DOCTYPE.
123
124
Parameters:
125
- sb: String buffer for output
126
- *args: Rendering arguments
127
- **kwargs: Rendering options (pretty, indent, xhtml)
128
129
Returns:
130
- String buffer with rendered document
131
"""
132
```
133
134
#### Usage Example
135
136
```python
137
doc = document(title='Example')
138
doc.add(h1('Hello World'))
139
140
# Render complete document
141
html_output = str(doc)
142
# Output:
143
# <!DOCTYPE html>
144
# <html>
145
# <head>
146
# <title>Example</title>
147
# </head>
148
# <body>
149
# <div> <!-- header container -->
150
# </div>
151
# <div> <!-- main container -->
152
# <h1>Hello World</h1>
153
# </div>
154
# <div> <!-- footer container -->
155
# </div>
156
# </body>
157
# </html>
158
159
# Custom rendering options
160
compact_html = doc.render(pretty=False)
161
custom_indent = doc.render(indent='\t')
162
xhtml_output = doc.render(xhtml=True)
163
```
164
165
### Document Representation
166
167
Get string representation of the document for debugging.
168
169
```python { .api }
170
def __repr__(self):
171
"""
172
Return string representation showing document title.
173
174
Returns:
175
- str: Representation in format '<dominate.document "title">'
176
"""
177
```
178
179
#### Usage Example
180
181
```python
182
doc = document(title='My Website')
183
print(repr(doc)) # <dominate.document "My Website">
184
```
185
186
## Complete Example
187
188
```python
189
import dominate
190
from dominate.tags import *
191
192
# Create document
193
doc = dominate.document(title='Complete Example')
194
195
# Add metadata
196
with doc.head:
197
meta(charset='utf-8')
198
meta(name='viewport', content='width=device-width, initial-scale=1')
199
link(rel='stylesheet', href='style.css')
200
201
# Add header
202
with doc.header:
203
nav(
204
ul(
205
li(a('Home', href='/')),
206
li(a('About', href='/about')),
207
li(a('Services', href='/services')),
208
li(a('Contact', href='/contact'))
209
),
210
cls='main-nav'
211
)
212
213
# Add main content
214
with doc.main:
215
section(
216
h1('Welcome to Our Website'),
217
p('This is the main content area with important information.'),
218
div(
219
h2('Our Services'),
220
ul(
221
li('Web Development'),
222
li('Design Services'),
223
li('Consulting')
224
)
225
),
226
cls='hero-section'
227
)
228
229
# Add footer
230
with doc.footer:
231
p('© 2023 Our Company. All rights reserved.')
232
p('Contact us at info@example.com')
233
234
# Output the complete document
235
print(doc)
236
```