dreader-application/HTML_GENERATION.md

HTML Generation for dreader

This document describes how to use the HTML generation features in dreader to create UI for e-reader applications.

Overview

The dreader library now includes HTML generation capabilities that allow you to create complete user interfaces programmatically. This is designed to work with a Hardware Abstraction Layer (HAL) that handles the actual display rendering and input processing.

Architecture

┌─────────────────────────────────────┐
│  dreader Library                    │
│  ├─ EbookReader (book rendering)    │
│  ├─ html_generator (UI generation)  │
│  └─ book_utils (scanning/metadata)  │
└─────────────────────────────────────┘
          ↓ HTML strings
┌─────────────────────────────────────┐
│  HAL (Hardware Abstraction Layer)   │
│  - Receives HTML strings            │
│  - Renders to display               │
│  - Captures touch/button input      │
│  - Calls back to dreader            │
└─────────────────────────────────────┘

Page and Overlay Concept

The UI uses a page/overlay architecture:

• Page (background): The main book content rendered as an image
• Overlay (foreground): UI elements like settings, table of contents, bookmarks, etc.

Available Modules

1. html_generator

Functions for generating HTML strings:

• generate_library_html(books) - Grid view of all books with covers
• generate_reader_html(title, author, page_data) - Book reading view
• generate_settings_overlay() - Settings panel
• generate_toc_overlay(chapters) - Table of contents
• generate_bookmarks_overlay(bookmarks) - Bookmarks list

2. book_utils

Utilities for managing books:

• scan_book_directory(path) - Scan directory for EPUB files
• extract_book_metadata(epub_path) - Get title, author, cover
• get_chapter_list(reader) - Format chapters for TOC
• get_bookmark_list(reader) - Format bookmarks
• page_image_to_base64(image) - Convert page image to base64

Usage Example

from pathlib import Path
from dreader import create_ebook_reader
from dreader.html_generator import (
    generate_library_html,
    generate_reader_html,
    generate_toc_overlay
)
from dreader.book_utils import (
    scan_book_directory,
    get_chapter_list,
    page_image_to_base64
)

# 1. Show library view
books_dir = Path('books')
books = scan_book_directory(books_dir)
library_html = generate_library_html(books)
# Pass library_html to HAL for rendering

# 2. User selects a book
selected_book = books[0]
reader = create_ebook_reader(page_size=(800, 1000))
reader.load_epub(selected_book['path'])

# 3. Show reader view
page_image = reader.get_current_page()
page_base64 = page_image_to_base64(page_image)
reader_html = generate_reader_html(
    book_title=reader.book_title,
    book_author=reader.book_author,
    page_image_data=page_base64
)
# Pass reader_html to HAL for rendering

# 4. User presses "Contents" button - show TOC overlay
chapters = get_chapter_list(reader)
toc_html = generate_toc_overlay(chapters)
# Pass toc_html to HAL for rendering on top of page

HTML Structure

Library View

The library uses an HTML table for grid layout:

<table class="library-grid">
  <tr>
    <td class="book-item">
      <table>
        <tr><td class="cover-cell"><img src="..."></td></tr>
        <tr><td class="title-cell">Book Title</td></tr>
        <tr><td class="author-cell">Author Name</td></tr>
      </table>
    </td>
    <!-- More books... -->
  </tr>
</table>

Reader View

The reader view has three sections:

• Header: Book info + buttons (Library, Contents, Settings)
• Page container: Centered book page image
• Footer: Navigation buttons (Previous, Next)

Overlays

Overlays use:

• Semi-transparent background (rgba(0, 0, 0, 0.7))
• Centered white panel
• Close button
• Table-based layout for content

Button/Link Interaction

All interactive elements have:

• id attributes for buttons (e.g., id="btn-next")
• data-* attributes for dynamic content (e.g., data-chapter-index="5")
• CSS classes for styling (e.g., class="nav-button")

Your HAL should:

1. Parse the HTML to identify interactive elements
2. Map touch/click coordinates to elements
3. Call appropriate dreader methods
4. Regenerate and render updated HTML

Demo

Run the included demo to see all features:

source venv/bin/activate
python examples/html_generation_demo.py

This will generate example HTML files in the output/ directory that you can open in a browser to preview.

Integration with HAL

Your HAL should implement:

1. HTML Rendering: Parse and display HTML strings
2. Touch Input: Map touch coordinates to HTML elements
3. State Management: Maintain reader state between interactions
4. Re-rendering: Update display when state changes

Example HAL flow:

User touches screen
    ↓
HAL identifies touched element (e.g., "btn-next")
    ↓
HAL calls reader.next_page()
    ↓
HAL regenerates reader_html with new page
    ↓
HAL renders updated HTML

Styling

All HTML includes inline CSS for complete styling. The design is:

• Clean, minimal interface
• Dark theme for reader (reduces eye strain)
• Large touch targets for buttons
• Responsive layout using tables (widely supported)

Customization

To customize the UI:

1. Edit functions in dreader/html_generator.py
2. Modify CSS in the <style> blocks
3. Change layout structure in the HTML templates
4. Adjust colors, fonts, spacing as needed

Files

• dreader/html_generator.py - HTML generation functions
• dreader/book_utils.py - Book scanning and utilities
• examples/html_generation_demo.py - Complete demonstration
• output/ - Generated HTML examples (after running demo)