0
# CSS Processing and Styling
1

2
Advanced CSS parsing, cascade processing, and style application system supporting CSS 2.1 and select CSS 3 features for precise document styling and layout control.
3

4
## Capabilities
5

6
### CSS Builder and Parser
7

8
Specialized CSS processing classes that handle CSS parsing, cascade resolution, and style application for PDF generation.
9

10
```python { .api }
11
class pisaCSSBuilder:
12
    """
13
    CSS builder specialized for xhtml2pdf PDF generation.
14
    
15
    Processes CSS rules and applies them to document elements,
16
    handling PDF-specific features like page rules and frames.
17
    """
18
    def atFontFace(self, declarations):
19
        """
20
        Process @font-face CSS rules for custom font loading.
21
        
22
        Args:
23
            declarations: CSS font-face declarations
24
        """
25
    
26
    def atPage(self):
27
        """
28
        Process @page CSS rules for page layout and margins.
29
        
30
        Handles page size, margins, headers, footers, and page breaks.
31
        """
32
    
33
    def atFrame(self, name, declarations):
34
        """
35
        Process @frame CSS rules for advanced page layout.
36
        
37
        Creates custom frames for complex multi-column layouts.
38
        
39
        Args:
40
            name (str): Frame name identifier
41
            declarations: CSS frame declarations
42
        
43
        Returns:
44
            tuple: Processed frame rules and data
45
        """
46

47
    def atPage(self, name, pseudopage, data, *, isLandscape, pageBorder):
48
        """
49
        Process @page CSS rules for page layout and margins.
50
        
51
        Handles page size, margins, headers, footers, and page breaks.
52
        
53
        Args:
54
            name (str): Page name or None for default
55
            pseudopage (str): Pseudo-page selector (:first, :left, :right)
56
            data (dict): Page rule declarations
57
            isLandscape (bool): Whether page is in landscape orientation
58
            pageBorder: Page border specifications
59
        
60
        Returns:
61
            tuple: Processed page rules and data
62
        """
63

64
    def get_background_context(data):
65
        """
66
        Process background context from CSS data.
67
        
68
        Args:
69
            data (dict): CSS background declarations
70
        
71
        Returns:
72
            dict: Processed background context with position, size, opacity
73
        """
74

75
class pisaCSSParser:
76
    """
77
    CSS parser for xhtml2pdf with external stylesheet support.
78
    
79
    Extends standard CSS parsing with PDF-specific features
80
    and external resource loading capabilities.
81
    """
82
    def parseExternal(self, cssResourceName):
83
        """
84
        Parse external CSS file and integrate with document styles.
85
        
86
        Args:
87
            cssResourceName (str): Path or URL to CSS file
88
        """
89
```
90

91
### Page Layout and Formatting
92

93
CSS support for PDF-specific page layout features including page sizes, margins, headers, footers, and page breaks.
94

95
```python { .api }
96
@page {
97
    size: A4 portrait;
98
    margin: 2cm;
99
    
100
    @top-center {
101
        content: "Document Title";
102
    }
103
    
104
    @bottom-right {
105
        content: counter(page);
106
    }
107
}
108

109
@page :first {
110
    margin-top: 5cm;
111
}
112

113
@page :left {
114
    margin-left: 3cm;
115
    margin-right: 2cm;
116
}
117

118
@page :right {
119
    margin-left: 2cm;
120
    margin-right: 3cm;
121
}
122
```
123

124
### Font Management
125

126
Comprehensive font handling system supporting custom fonts, font fallbacks, and international character sets.
127

128
```python { .api }
129
@font-face {
130
    font-family: "Custom Font";
131
    src: url("path/to/font.ttf");
132
    font-weight: normal;
133
    font-style: normal;
134
}
135

136
/* Usage in styles */
137
.custom-text {
138
    font-family: "Custom Font", Arial, sans-serif;
139
    font-size: 12pt;
140
}
141
```
142

143
### Supported CSS Features
144

145
#### CSS 2.1 Support
146
- **Box Model**: margins, padding, borders, dimensions
147
- **Typography**: font properties, text alignment, line height
148
- **Colors**: named colors, hex values, RGB/RGBA
149
- **Layout**: positioning, floats, display properties
150
- **Lists**: list-style properties and numbering
151
- **Tables**: table layout and styling
152

153
#### CSS 3 Features
154
- **Border Radius**: rounded corners for elements
155
- **Text Shadow**: text shadow effects
156
- **Background Images**: background image positioning and sizing
157
- **Web Fonts**: @font-face for custom fonts
158

159
#### PDF-Specific Extensions
160
- **Page Rules**: @page for page layout control
161
- **Frame Rules**: @frame for multi-column layouts
162
- **PDF Links**: automatic link generation from anchor elements
163
- **Page Breaks**: page-break-before/after properties
164

165
### CSS Integration Example
166

167
```python
168
from xhtml2pdf import pisa
169

170
# Custom CSS with PDF-specific features
171
css_content = """
172
@page {
173
    size: A4;
174
    margin: 1in;
175
    
176
    @top-center {
177
        content: "Report Header";
178
        font-size: 10pt;
179
        color: #666;
180
    }
181
}
182

183
@font-face {
184
    font-family: "Report Font";
185
    src: url("fonts/report.ttf");
186
}
187

188
body {
189
    font-family: "Report Font", Arial, sans-serif;
190
    font-size: 11pt;
191
    line-height: 1.4;
192
}
193

194
.header {
195
    background-color: #f0f0f0;
196
    padding: 10pt;
197
    border-bottom: 2pt solid #333;
198
    page-break-after: avoid;
199
}
200

201
.section {
202
    page-break-inside: avoid;
203
    margin-bottom: 20pt;
204
}
205

206
.footer {
207
    position: fixed;
208
    bottom: 0;
209
    width: 100%;
210
    text-align: center;
211
    font-size: 9pt;
212
    color: #999;
213
}
214
"""
215

216
html_content = """
217
<html>
218
    <head>
219
        <style>""" + css_content + """</style>
220
    </head>
221
    <body>
222
        <div class="header">
223
            <h1>Annual Report</h1>
224
        </div>
225
        
226
        <div class="section">
227
            <h2>Executive Summary</h2>
228
            <p>Content here...</p>
229
        </div>
230
        
231
        <div class="footer">
232
            Page <pdf:pagenumber>
233
        </div>
234
    </body>
235
</html>
236
"""
237

238
# Convert with integrated CSS
239
with open("styled_report.pdf", "wb") as dest:
240
    result = pisa.pisaDocument(html_content, dest)
241
```
242

243
## Types
244

245
```python { .api }
246
class pisaCSSBuilder:
247
    """
248
    CSS builder for PDF-specific style processing.
249
    
250
    Handles CSS rule parsing and application with support
251
    for PDF layout features and custom styling options.
252
    """
253

254
class pisaCSSParser:
255
    """
256
    CSS parser with external resource loading capabilities.
257
    
258
    Processes CSS files and integrates them with document
259
    styles while handling PDF-specific CSS extensions.
260
    """
261
```