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

```bash
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

![Page Rendering Example](../docs/images/example_01_page_rendering.png)

### 02. Text and Layout
**`02_text_and_layout.py`** - HTML parsing and text rendering

```bash
python 02_text_and_layout.py
```

Demonstrates:
- Parsing HTML content
- Text alignment options
- Font sizes and styles
- Document structure

![Text and Layout Example](../docs/images/example_02_text_and_layout.png)

### 03. Page Layouts
**`03_page_layouts.py`** - Different page configurations

```bash
python 03_page_layouts.py
```

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

![Page Layouts Example](../docs/images/example_03_page_layouts.png)

### 04. Table Rendering
**`04_table_rendering.py`** - HTML table rendering with styling

```bash
python 04_table_rendering.py
```

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

![Table Rendering Example](../docs/images/example_04_table_rendering.png)

### 05. Tables with Images
**`05_table_with_images.py`** - Tables containing images and mixed content

```bash
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

![Table with Images Example](../docs/images/example_05_table_with_images.png)

### 06. Functional Elements (Interactive)
**`06_functional_elements_demo.py`** - Interactive buttons and forms with callbacks

```bash
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

![Functional Elements Example](../docs/images/example_06_functional_elements.png)

---

## 🆕 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

```bash
python 08_pagination_demo.py
```

**Test Coverage:** [tests/examples/test_08_pagination_demo.py](../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!

![Pagination Example](../docs/images/example_08_pagination_explicit.png)

### 09. Link Navigation (NEW) ✅
**`09_link_navigation_demo.py`** - All link types and interactive navigation

```bash
python 09_link_navigation_demo.py
```

**Test Coverage:** [tests/examples/test_09_link_navigation_demo.py](../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!

![Link Navigation Example](../docs/images/example_09_link_navigation.png)

### 10. Comprehensive Forms (NEW) ✅
**`10_forms_demo.py`** - All 14 form field types with validation

```bash
python 10_forms_demo.py
```

**Test Coverage:** [tests/examples/test_10_forms_demo.py](../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!

![Comprehensive Forms Example](../docs/images/example_10_forms.png)

### 11. Table Text Wrapping (NEW) ✅
**`11_table_text_wrapping_demo.py`** - Automatic line wrapping in table cells

```bash
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

![Table Text Wrapping Example](../docs/images/example_11_table_text_wrapping.png)

---

## 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:

```bash
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:

```bash
# 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.