# 03-Feb-2026 — add external album import from Flickr [ref: #147](https://github.com/nbarrett/ngx-ramblers/issues/147)

## [build 459](https://github.com/nbarrett/ngx-ramblers/actions/runs/21641819798) — [commit 7333a44](https://github.com/nbarrett/ngx-ramblers/commit/7333a4400b0742a1bb3793c4b22219605ce53b0d)

_____

## Overview

This release introduces two major features: **Flickr Album Import** for bringing external photo albums into the platform, and significant **Environment Setup Enhancements** for database-driven configuration. It also includes numerous code quality improvements and developer experience enhancements.

---

# User Guide

## New Features

### 1. Import Flickr Albums

You can now import photo albums directly from Flickr without copying images to S3. Images remain hosted on Flickr while the album is managed within the platform.

#### How to Access
Navigate to **Admin > System Settings > Image Migration > Import from External Sources**

#### Single Album Import
1. Select **Single Album** mode
2. Paste a Flickr album URL (e.g., `https://www.flickr.com/photos/username/albums/12345`)
3. Enter a target path for the new page (e.g., `gallery/2024/summer-walk`)
4. Optionally customise the album title and subtitle
5. Click **Import Album**
6. The system will:
   - Fetch all photos from the Flickr album
   - Extract photo titles and dates
   - Create a new album page at your specified path

#### Bulk Import (Multiple Albums)
1. Select **Bulk Import** mode
2. Enter a Flickr user ID or username
3. The system will fetch and display all albums for that user
4. Select the albums you wish to import using checkboxes
5. Set a base path (e.g., `gallery`) - albums will be created at `{base-path}/{album-name}`
6. Review the generated paths (you can modify them before import)
7. Click **Import Selected Albums**
8. Monitor progress in real-time as each album is imported

#### Album Splitting
For large albums with photos from different events, you can split them:
1. Enable **Split by Photo Title**
2. The system groups photos by their title patterns
3. Preview how photos will be split into separate albums
4. Choose which groups to include
5. Each group becomes its own album page

#### What Gets Imported
- Album title and description from Flickr
- All photo URLs (images remain on Flickr)
- Photo titles (displayed when "Show Titles" is enabled in grid view)
- Photo dates (for chronological ordering)
- Cover photo for album previews

#### Template Support
You can use an existing album page as a template:
1. Enable **Use Template**
2. Enter the path of an existing album page
3. The new album(s) will inherit the layout and grid settings from the template

---

### 2. Index Row Auto Title

Index rows now support automatic title generation from the page URL.

#### How It Works
- **Auto Title enabled (default)**: The index row automatically displays a title derived from the page URL/subtitle
- **Auto Title disabled**: You can enter custom markdown content for the title area

#### How to Use
1. Edit any page with an Index row
2. Find the **Auto Title** checkbox in the Index row settings
3. When enabled, the title updates automatically based on the page path
4. When disabled, a markdown editor appears for custom title content

This is useful for:
- Consistent titles across similar pages
- Quick setup of new index pages
- Override capability when you need a custom title

---

### 3. Improved CLI Tool

The command-line interface has been significantly enhanced for local development.

#### Starting the Application Locally
```bash
# Development mode (with hot reload)
ngx-cli local dev staging

# Production mode (build then run)
ngx-cli local prod staging
```

#### Available Environments
```bash
# List all configured environments
ngx-cli local list
```

The CLI will:
- Check port availability before starting
- Load secrets from the appropriate environment file
- Configure Chrome/Chromedriver for scraping features
- Show real-time logs from both frontend and backend

#### Log Files
Use the `--log-dir` flag to save logs:
```bash
ngx-cli local dev staging --log-dir ./logs --log-timestamp
```

---

### 4. Environment Configuration from Database

Environment configuration is now stored in the database rather than file-based configs. This provides:

- **Centralised Configuration**: All environment settings in one place
- **Real-time Updates**: Changes take effect without redeployment
- **Better Security**: Sensitive configuration stored in database, not files

The system will automatically use database configuration, with file-based fallback only as a last resort (you'll be prompted before this happens).

---

## Changes to Existing Features

### Album Grid View
- Photo titles now display correctly when "Show Titles" is enabled
- Photo dates are stored and can be used for sorting

### Template Selector
- New template selector component for reusing page layouts
- Available when creating albums from external sources

---

# Technical Changes

## GitHub Issue #147: Flickr Album Import - Completion Status

### Completed Requirements

| Requirement | Status |
|------------|--------|
| New "Import from External Sources" tab | ✅ Complete |
| Single album import with URL input | ✅ Complete |
| Bulk import from user albums | ✅ Complete |
| Multi-select album interface | ✅ Complete |
| Auto-generated paths from album names | ✅ Complete |
| PageContent creation with correct structure | ✅ Complete |
| ContentMetadata with Flickr URLs | ✅ Complete |
| Photo title extraction (text field) | ✅ Complete |
| Photo date extraction (date field) | ✅ Complete |
| Real-time progress via WebSocket | ✅ Complete |
| Error handling for invalid URLs | ✅ Complete |
| Album splitting by photo title | ✅ Complete |
| Template-based album creation | ✅ Complete |

### Pending Testing
- Albums display correctly in grid, gallery, and carousel views
- Photo titles display when `showTitles` is enabled

---

## GitHub Issue #146: Environment Setup - Changes in This Release

### Completed in This Release

| Enhancement | Status |
|------------|--------|
| Database-driven environment configuration | ✅ Complete |
| CLI database connection with explicit connect | ✅ Complete |
| Fallback prompt before using file-based config | ✅ Complete |
| Environment variable logging on CLI startup | ✅ Complete |
| Standardised debug logging with `envConfig.logNamespace()` | ✅ Complete |

---

## Bonus Features (Outside Original Scope)

### 1. External Album Import Framework
- Extensible provider architecture (`ExternalAlbumProvider` interface)
- Support for multiple sources (Flickr implemented, Google Photos/Instagram ready)
- Album summary and metadata interfaces for any external source

### 2. Album Splitting Feature
- Split large albums by photo title patterns
- Preview split results before importing
- Include/exclude specific groups

### 3. Template-Based Album Creation
- Use existing album pages as templates
- Inherit layout, grid options, and styling
- Template selector component for easy selection

### 4. Index Row Auto Title
- Automatic title generation from page URL
- Toggle between auto and manual markdown entry
- Defaults to enabled for new index rows

### 5. Enhanced CLI Local Development
- Port availability checking before starting servers
- Chrome/Chromedriver validation and configuration
- Log file output with timestamps
- Clean process shutdown handling

### 6. Real-Time Import Progress
- WebSocket-based progress updates
- Stage-by-stage progress reporting
- Activity logging during bulk imports

### 7. Code Quality Improvements
- Replaced all `Array<T>` with `T[]` syntax
- Standardised debug logger creation with `envConfig.logNamespace()`
- Cached environment variable validation (log once, not repeatedly)
- Explicit database connection in CLI commands

---

## Migration Notes

### For Administrators
- Environment configuration is now read from database by default
- File-based `configs.json` is only used as fallback (you'll be prompted)
- Ensure database connectivity before running CLI commands

### For Developers
- Use `envConfig.logNamespace("your-module")` for debug logging
- Use `T[]` instead of `Array<T>` for type definitions
- Database connection is now explicit in CLI context

---

## Testing Checklist

- [ ] Import single Flickr album and verify page creation
- [ ] Import multiple albums via bulk import
- [ ] Verify album splitting works correctly
- [ ] Verify template-based import inherits settings
- [ ] Test Index row auto title toggle
- [ ] Test CLI `local dev` and `local prod` commands
- [ ] Verify database configuration is loaded (not file-based)
- [ ] Check environment variable logging appears once only