pyWebLayout/examples/README.md

PyWebLayout Examples

This directory contains example scripts demonstrating the pyWebLayout library.

Getting Started Examples

These examples demonstrate the core rendering capabilities of pyWebLayout:

01. Simple Page Rendering

01_simple_page_rendering.py - Introduction to the Page system

python 01_simple_page_rendering.py

Demonstrates:

• Creating pages with different styles
• Setting borders, padding, and backgrounds
• Understanding page layout structure
• Basic rendering to images

02. Text and Layout

02_text_and_layout.py - HTML parsing and text rendering

python 02_text_and_layout.py

Demonstrates:

• Parsing HTML content
• Text alignment options
• Font sizes and styles
• Document structure

03. Page Layouts

03_page_layouts.py - Different page configurations

python 03_page_layouts.py

Demonstrates:

• Various page sizes (portrait, landscape, square)
• Different aspect ratios
• Border and padding variations
• Color schemes

04. Table Rendering

04_table_rendering.py - HTML table rendering with styling

python 04_table_rendering.py

Demonstrates:

• Rendering HTML tables
• Table headers and body rows
• Cell borders and padding
• Caption support
• Custom table styling

05. Tables with Images

05_table_with_images.py - Tables containing images and mixed content

python 05_table_with_images.py

Demonstrates:

• Creating tables programmatically
• Adding images to table cells
• Book catalog and product showcase tables
• Mixed content (images and text) in cells
• Using cover images from test data

06. Functional Elements (Interactive)

06_functional_elements_demo.py - Interactive buttons and forms with callbacks

python 06_functional_elements_demo.py

Demonstrates:

• Creating interactive buttons
• Building forms with multiple field types
• Post-layout callback binding
• CallbackRegistry system for managing interactables
• Accessing application state from callbacks
• Batch callback operations
• Simulating user interactions

---

🆕 New Examples (2024-11)

These examples address critical coverage gaps and demonstrate advanced features:

08. Pagination with PageBreak (NEW) ✅

08_pagination_demo.py - Multi-page documents with explicit and automatic pagination

python 08_pagination_demo.py

Test Coverage: tests/examples/test_08_pagination_demo.py - 11 tests

Demonstrates:

• Using PageBreak to force content onto new pages
• Multi-page document layout with explicit breaks
• Automatic pagination when content overflows
• Page numbering functionality
• Document flow control
• Combining pages into vertical strips

Coverage Impact: Fills critical gap - PageBreak layouter had NO examples before this!

09. Link Navigation (NEW) ✅

09_link_navigation_demo.py - All link types and interactive navigation

python 09_link_navigation_demo.py

Test Coverage: tests/examples/test_09_link_navigation_demo.py - 10 tests

Demonstrates:

• Internal links - Document navigation (#section1, #section2)
• External links - Web URLs (https://example.com)
• API links - API endpoints (/api/settings, /api/save)
• Function links - Direct function calls (calculate(), process())
• Link styling (underlined, color-coded by type)
• Link callbacks and interactivity
• Mixed text and link paragraphs

Coverage Impact: Comprehensive - All 4 LinkType variations demonstrated!

10. Comprehensive Forms (NEW) ✅

10_forms_demo.py - All 14 form field types with validation

python 10_forms_demo.py

Test Coverage: tests/examples/test_10_forms_demo.py - 9 tests

Demonstrates all 14 FormFieldType variations:

Text-Based Fields:

• TEXT, EMAIL, PASSWORD, URL, TEXTAREA

Number/Date/Time Fields:

• NUMBER, DATE, TIME, RANGE, COLOR

Selection Fields:

• CHECKBOX, RADIO, SELECT, HIDDEN

Coverage Impact: Complete - All 14 field types across 4 practical form examples!

11. Table Text Wrapping (NEW) ✅

11_table_text_wrapping_demo.py - Automatic line wrapping in table cells

python 11_table_text_wrapping_demo.py

Simple Version: 11b_simple_table_wrapping.py - Quick demonstration

Demonstrates:

• Automatic line wrapping - Text wraps across multiple lines within cells
• Word hyphenation - Long words are intelligently hyphenated
• Narrow columns - Aggressive wrapping for tight spaces
• Mixed content - Both short and long text in the same table
• Technical documentation - API reference style tables
• News layouts - Article-style table content

Implementation: Uses the Line class from pyWebLayout.concrete.text with:

• Word-by-word fitting with intelligent spacing
• Pyphen-based dictionary hyphenation
• Brute-force splitting for edge cases
• Proper baseline alignment and metrics

---

Advanced Examples

HTML Rendering

These examples demonstrate rendering HTML content to multi-page layouts:

html_line_breaking_demo.py - Basic HTML line breaking demonstration html_multipage_simple.py - Simple single-page HTML rendering html_multipage_demo_final.py - Complete multi-page HTML rendering with headers/footers

For detailed information about HTML rendering, see README_HTML_MULTIPAGE.md.

Running the Examples

All examples can be run directly from the examples directory:

cd examples

# Getting Started
python 01_simple_page_rendering.py
python 02_text_and_layout.py
python 03_page_layouts.py
python 04_table_rendering.py
python 05_table_with_images.py
python 06_functional_elements_demo.py

# NEW: Advanced Features
python 08_pagination_demo.py       # Multi-page documents
python 09_link_navigation_demo.py  # All link types
python 10_forms_demo.py            # All form field types
python 11_table_text_wrapping_demo.py  # Table cell text wrapping
python 11b_simple_table_wrapping.py    # Simple wrapping demo

Output images are saved to the docs/images/ directory.

Running Tests

All new examples (08, 09, 10) include comprehensive test coverage:

# Run all example tests
python -m pytest tests/examples/ -v

# Run specific test file
python -m pytest tests/examples/test_08_pagination_demo.py -v
python -m pytest tests/examples/test_09_link_navigation_demo.py -v
python -m pytest tests/examples/test_10_forms_demo.py -v

Total Test Coverage: 30 tests (11 + 10 + 9), all passing ✅

Additional Documentation

• README_HTML_MULTIPAGE.md - HTML multi-page rendering guide
• ../ARCHITECTURE.md - Detailed explanation of the Abstract/Concrete architecture
• ../docs/images/README.md - Visual documentation index with all examples
• ../pyWebLayout/layout/README_EREADER_API.md - EbookReader API reference

Debug/Development Scripts

Low-level debug and rendering scripts have been moved to the scripts/ directory.