PhotoFlow Gallery Documentation

Getting Started

PhotoFlow Gallery is a modern, high-performance image gallery extension for Joomla 4, 5 & 6. It provides automatic image optimization, multiple display modes, and advanced security features out of the box.

System Requirements

Key Features

Installation

Installing PhotoFlow Gallery is straightforward using Joomla's extension installer.

Standard Installation

1. Download the PhotoFlow Gallery package (pkg_photoflow_X.X.X.zip)
2. Log in to your Joomla administrator panel
3. Navigate to System → Install → Extensions
4. Click the Upload Package File tab
5. Select the downloaded ZIP file and click Upload & Install
6. Wait for the installation to complete

Post-Installation Steps

1. Create Image Directories: PhotoFlow automatically creates:
   • images/photoflow/originals/ - Original uploaded images
   • images/photoflow/detail/ - Detail view images
   • images/photoflow/thumbs/ - Thumbnail images
2. Configure Permissions: Ensure directories are writable (755 or 775)
3. Enable the Plugin: Navigate to System → Plugins and enable the PhotoFlow plugin
4. Create a Menu Item: Set up a menu item pointing to PhotoFlow Gallery

Upgrading from Previous Version

To upgrade PhotoFlow, simply install the new version over the existing installation. Joomla will automatically handle the upgrade process and run any necessary database updates.

// Database updates are automatic
// Old images and settings are preserved
// No manual migration required

Configuration

PhotoFlow offers comprehensive configuration options accessible from Components → PhotoFlow → Options.

Gallery Display Settings

Card Style Settings

Customize the appearance of image cards in your gallery:

• Hover Effect: None, Zoom, Lift, or Overlay
• Show Title: Display image titles on cards
• Show Description: Show descriptions on hover
• Show Stats: Display view and download counts
• Corner Radius: Border radius for cards (0-32px)
• Shadow Intensity: Card shadow strength

Categories & Albums

Category Configuration

• Category Layout: Override global display mode per category
• Show Category Description: Display category description above images
• Show Subcategories: Display child categories
• Subcategory Style: Cards or compact list
• Ordering: Custom, alphabetical, date created, or date modified

Upload Settings

Security Configuration

Password Protection

• Global Password: Set a password for all images
• Per-Image Passwords: Individual passwords for specific images
• Pattern-Based Passwords: Dynamic passwords using date/time patterns
• Lockout Protection: Limit failed password attempts (default: 5)
• Lockout Duration: How long users are locked out (minutes)

Access Control

Performance Optimization

CDN Settings

Configure Content Delivery Network integration for faster image delivery:

• Enable CDN: Use CDN for image delivery
• CDN URL: Your CDN base URL
• CDN Path: Path to PhotoFlow images on CDN
• Use for Thumbnails: Serve thumbnails via CDN
• Use for Detail Images: Serve detail images via CDN
• Use for Originals: Serve original images via CDN

Image Management

PhotoFlow provides powerful tools for managing your image library efficiently.

Uploading Images

Single Image Upload

1. Navigate to Components → PhotoFlow → Images
2. Click the New button
3. Fill in the image details:
   • Title: Image title (required)
   • Alias: URL-friendly name (auto-generated if empty)
   • Description: Image description
   • Category: Select a category
   • Access Level: Who can view this image
4. Select the image file using the file picker
5. Click Save & Close

Bulk Import

Import thousands of images from an existing directory on your server.

1. Upload images to a directory on your server (e.g., images/import/)
2. Go to Components → PhotoFlow → Import
3. Enter the source directory path
4. Configure import settings:
   • Target Category: Category for imported images
   • Default Access: Access level for all imports
   • Use Filename as Title: Auto-generate titles
   • Skip Duplicates: Check for existing files
   • Delete After Import: Remove source files
5. Click Start Import
6. Monitor the progress bar

// Example import directory structure
images/import/
├── vacation-2024/
│   ├── beach-sunset.jpg
│   ├── mountain-view.jpg
│   └── city-lights.jpg
└── portfolio/
    ├── portrait-1.jpg
    └── landscape-1.jpg

Thumbnail Management

PhotoFlow automatically manages image versions, but you can also regenerate them manually:

Regenerate Single Image

1. Go to Components → PhotoFlow → Images
2. Select the image
3. Click Actions → Regenerate Thumbnails

Regenerate All Images

1. Navigate to Components → PhotoFlow → Maintenance
2. Click Regenerate All Thumbnails
3. Confirm the action
4. Wait for batch processing to complete

Image Metadata

PhotoFlow automatically tracks important metadata for each image:

• File Information: Filename, size, dimensions, MIME type
• Statistics: View count, download count
• Timestamps: Upload date, last modified date
• User Data: Uploaded by, modified by
• EXIF Data: Camera info, GPS coordinates (if available)

Maintenance Tools

Keep your gallery optimized with built-in maintenance tools:

Display Modes

PhotoFlow offers four distinct display modes, each optimized for different use cases and aesthetics.

Grid Mode

Classic grid layout with uniform image cards arranged in responsive columns.

Grid Configuration

Best for: Portfolio sites, product galleries, general image collections

List Mode

Horizontal layout showing images in a single column with metadata alongside.

List Features

• Thumbnail on left, details on right (or reversed)
• Full description and metadata display
• Compact view for easy browsing
• Sortable columns

Best for: Document libraries, image archives, searchable galleries

Masonry Mode

Pinterest-style layout where images maintain their aspect ratios in a flowing grid.

Masonry Configuration

Best for: Photography portfolios, inspiration boards, mixed aspect ratio collections

Carousel Mode

Slideshow-style presentation with navigation controls and autoplay options.

Carousel Features

• Navigation: Arrow buttons, thumbnails, or dots
• Autoplay: Configurable interval and pause on hover
• Transitions: Slide, fade, or zoom effects
• Looping: Infinite or one-way cycling
• Thumbnails: Optional thumbnail strip
• Keyboard: Arrow key navigation support
• Touch: Swipe gestures on mobile

Carousel Configuration

Best for: Featured images, hero sections, product showcases

Security Features

PhotoFlow includes enterprise-grade security features to protect your images and control access.

Password Protection

Protect individual images or entire categories with passwords.

Setting Up Image Passwords

1. Edit an image or category
2. Enable Password Protected
3. Enter a password
4. Save the changes

Password Types

Pattern Password Examples

// Date-based patterns
{Y}{m}{d}        → 20240315 (changes daily)
{Y}{W}           → 202411 (changes weekly)
week{W}          → week11 (readable format)

// Time-based patterns
{Y}{m}{d}{H}     → 2024031514 (changes hourly)
day{d}hour{H}    → day15hour14

// Custom patterns
photo{Y}{m}      → photo202403
gallery_{W}      → gallery_11

Access Control Lists (ACL)

PhotoFlow fully integrates with Joomla's ACL system for granular permission control.

Available Permissions

Direct Link Only Mode

Hide images from gallery listings, making them accessible only via direct URL.

Use Cases

• Private Sharing: Share specific images without exposing the full gallery
• Email Campaigns: Include unique image links in emails
• API Integration: Serve images to external applications
• Temporary Access: Grant limited-time access via URL

Lockout Protection

Prevent brute-force password attacks with automatic lockout after failed attempts.

Lockout Configuration

• Max Attempts: Number of failed tries before lockout (default: 5)
• Lockout Duration: How long to block access (default: 30 minutes)
• Track By: IP address or session
• Admin Notification: Email alerts for lockout events

Download Security

Control how users can download your images:

• Disable Right-Click: Prevent context menu access
• Watermarking: Add watermarks to downloaded images
• Download Tracking: Log all download activities
• Rate Limiting: Limit downloads per user/IP
• Hotlink Protection: Prevent embedding on external sites

API Reference

PhotoFlow provides a RESTful JSON API for programmatic access to gallery data.

Authentication

API requests use Joomla's standard authentication system:

// Using Joomla API Token
GET /index.php?option=com_photoflow&view=gallery&format=json
Authorization: Bearer YOUR_JOOMLA_API_TOKEN

// For public endpoints (no auth required)
GET /index.php?option=com_photoflow&view=gallery&format=json

Endpoints

Get Gallery Images

Retrieve a list of images from the gallery.

GET /index.php?option=com_photoflow&view=gallery&format=json

// Parameters
?limit=12           // Images per page
&offset=0           // Pagination offset
&category=5         // Filter by category ID
&ordering=created   // Sort field (created, title, hits, downloads)
&direction=DESC     // Sort direction (ASC or DESC)

Response Format

{
  "success": true,
  "data": {
    "images": [
      {
        "id": 1,
        "title": "Sunset Beach",
        "alias": "sunset-beach",
        "description": "Beautiful sunset...",
        "filename": "sunset-beach.jpg",
        "thumbnail": "/images/photoflow/thumbs/sunset-beach.jpg",
        "detail": "/images/photoflow/detail/sunset-beach.jpg",
        "hits": 142,
        "downloads": 23,
        "created": "2024-03-15 14:30:00",
        "category_id": 5,
        "category_title": "Landscapes"
      }
    ],
    "pagination": {
      "total": 48,
      "limit": 12,
      "offset": 0,
      "pages": 4
    }
  }
}

Get Single Image

GET /index.php?option=com_photoflow&view=image&id=1&format=json

// Response
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Sunset Beach",
    "alias": "sunset-beach",
    "description": "Beautiful sunset over calm waters",
    "filename": "sunset-beach.jpg",
    "thumbnail": "/images/photoflow/thumbs/sunset-beach.jpg",
    "detail": "/images/photoflow/detail/sunset-beach.jpg",
    "original": "/images/photoflow/originals/sunset-beach.jpg",
    "filesize": 2458624,
    "width": 1920,
    "height": 1080,
    "mime_type": "image/jpeg",
    "hits": 142,
    "downloads": 23,
    "created": "2024-03-15 14:30:00",
    "modified": "2024-03-15 14:30:00",
    "created_by": "John Doe",
    "category": {
      "id": 5,
      "title": "Landscapes",
      "alias": "landscapes"
    }
  }
}

Get Categories

GET /index.php?option=com_photoflow&view=categories&format=json

// Response
{
  "success": true,
  "data": {
    "categories": [
      {
        "id": 1,
        "title": "Landscapes",
        "alias": "landscapes",
        "description": "Beautiful landscape photography",
        "parent_id": 0,
        "image_count": 24,
        "path": "landscapes"
      }
    ]
  }
}

Download Image

GET /index.php?option=com_photoflow&task=image.download&id=1

// Returns the original image file
// Increments download counter
// Requires download permission

Error Handling

All API responses include a success field. On error:

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Image not found"
  }
}

Common Error Codes

JavaScript Integration

Example using fetch API:

// Fetch gallery images
async function loadGallery() {
  try {
    const response = await fetch(
      '/index.php?option=com_photoflow&view=gallery&format=json&limit=12'
    );
    const data = await response.json();

    if (data.success) {
      displayImages(data.data.images);
    } else {
      console.error('API Error:', data.error);
    }
  } catch (error) {
    console.error('Network Error:', error);
  }
}

// Display images
function displayImages(images) {
  const gallery = document.getElementById('gallery');

  images.forEach(image => {
    const card = document.createElement('div');
    card.className = 'image-card';
    card.innerHTML = `
      <img src="${image.thumbnail}" alt="${image.title}">
      <h3>${image.title}</h3>
      <p>${image.description}</p>
    `;
    gallery.appendChild(card);
  });
}

Rate Limiting

API requests are rate-limited to prevent abuse:

• Anonymous Users: 60 requests per hour
• Authenticated Users: 300 requests per hour
• API Token: 1000 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1615825200

Support & Resources