# Template System Documentation

## Overview

The template system allows you to create reusable page layouts with placeholder blocks. Templates are saved as JSON files and can be applied to new or existing pages with flexible scaling options.

## Features

### 1. Save Page as Template
- Converts all images on the current page to placeholder blocks
- Preserves positions, sizes, and layouts
- Keeps text boxes and existing placeholders
- Saves template as JSON file

### 2. Create Page from Template
- Creates a new page with the template layout
- Automatically scales to match project page size
- All elements are placeholders ready for images

### 3. Apply Template to Existing Page
- Two modes:
  - **Replace**: Clears page and adds template placeholders
  - **Reflow**: Repositions existing images to fit template slots
- Three scaling options:
  - **Proportional**: Maintains aspect ratio (recommended)
  - **Stretch**: Stretches to fit entire page
  - **Center**: No scaling, centers template

## How to Use

### Creating a Template

1. Design a page with your desired layout (images, text, placeholders)
2. Go to **Layout** tab → **Templates** group
3. Click **Save as Template**
4. Enter a name and optional description
5. Template is saved to `~/.pyphotoalbum/templates/`

### Using a Template

**To create a new page:**
1. Click **New from Template**
2. Select a template from the list
3. New page is created with placeholder blocks
4. Drag and drop images onto placeholders

**To apply to current page:**
1. Click **Apply Template**
2. Select template and options:
   - Mode: Replace or Reflow
   - Scaling: Proportional, Stretch, or Center
3. Click Apply

## Template Storage

- **User templates**: `~/.pyphotoalbum/templates/` (your custom templates)
- **Built-in templates**: `pyPhotoAlbum/templates/` (shipped with app)
  - `Grid_2x2`: 2x2 grid layout
  - `Single_Large`: Single large image with title

## Template Format

Templates are JSON files with this structure:

```json
{
  "name": "Template Name",
  "description": "Description",
  "page_size_mm": [210, 297],
  "elements": [
    {
      "type": "placeholder",
      "position": [x, y],
      "size": [width, height],
      "rotation": 0,
      "z_index": 0,
      "placeholder_type": "image",
      "default_content": ""
    }
  ]
}
```

## Tips

- Templates scale automatically when page sizes differ
- Use **Proportional** scaling to prevent distortion
- **Reflow** mode is great for applying new layouts to existing content
- Create templates for common layouts you use frequently
- Built-in templates provide good starting points

## Workflow Example

1. Create a page with 4 images arranged in a grid
2. Save it as "My Grid" template
3. Later, create new page from "My Grid" template
4. Drag your photos onto the placeholder blocks
5. Repeat for multiple pages with consistent layout

## Advanced

### Scaling Behavior

When template and target page sizes differ:

- **Proportional**: `scale = min(width_ratio, height_ratio)`
  - Maintains aspect ratio
  - May leave empty space
  - Best for preserving design

- **Stretch**: `scale_x = width_ratio, scale_y = height_ratio`
  - Fills entire page
  - May distort layout
  - Good for flexible designs

- **Center**: No scaling
  - Template positioned at center
  - Original sizes preserved
  - May overflow or leave space
