Skip to content

External Apps Hook Parameters

Complete reference for all available parameters in BBDrop's External Apps hooks system.

Parameter Categories

  • %N - Gallery name
  • %T - Tab name (e.g., "Main", "Favorites")
  • %p - Gallery folder path (e.g., "C:\Images\MyGallery")
  • %C - Image count (number of images in gallery)
  • %s - Gallery size in bytes
  • %t - Template name used for BBCode generation

Artifacts (Completed Events Only)

  • %g - Gallery ID (from image host)
  • %j - JSON artifact file path
  • %b - BBCode artifact file path
  • %z - ZIP archive path (auto-created if needed)

Database Fields

Ext Fields (populated by external apps): - %e1 - ext1 field value - %e2 - ext2 field value - %e3 - ext3 field value - %e4 - ext4 field value

Custom Fields (user-editable): - %c1 - custom1 field value - %c2 - custom2 field value - %c3 - custom3 field value - %c4 - custom4 field value

Hook Event Types

Triggered when a gallery is added to the queue.

Available parameters: 

%N, %T, %p, %C, %s, %t, %e1-%e4, %c1-%c4

Example command: 

python notify.py "Added: %N (%C images, %s bytes)"

Triggered when a gallery upload begins.

Available parameters: 

%N, %T, %p, %C, %s, %t, %e1-%e4, %c1-%c4

Example command: 

python logger.py --event start --gallery "%N" --path "%p"

Triggered when a gallery upload finishes successfully.

Available parameters: 

%N, %T, %p, %C, %s, %t, %g, %j, %b, %z, %e1-%e4, %c1-%c4

Example command: 

python multi_host_uploader.py gofile "%z" --metadata "%N (%s bytes)"

Usage Examples

Upload to File Host with Metadata

python uploader.py --file "%z" --name "%N" --size "%s" --template "%t"

Conditional Processing Based on Size

python process.py "%p" --large-mode --size %s --quality high

Chain Ext Fields

# First hook populates ext1 with download URL
python multi_host_uploader.py gofile "%z"

# Second hook can read ext1 and add more data
python metadata_sync.py --url "%e1" --gallery "%N" --id "%g"

Custom Workflow with All Fields

python workflow.py \
  --name "%N" \
  --path "%p" \
  --count %C \
  --size %s \
  --template "%t" \
  --gallery-id "%g" \
  --json "%j" \
  --bbcode "%b" \
  --ext1 "%e1" \
  --custom1 "%c1"

Technical Details

Multi-Character Variables

Multi-character parameters (%e1, %c1, etc.) are processed using longest-match-first substitution:

# Variables are sorted by length (descending) before substitution
# This prevents %e1 from being partially matched as %e + "1"

Order: %e1, %e2, %c1, %c2 ... %N, %T, %p, %C, %s, %t, %g

Empty Values

  • Empty fields are substituted with empty strings
  • Use quotes around parameters to handle empty values: 
    python script.py "%e1"  # Safe even if e1 is empty
python script.py %e1    # May cause parsing errors if empty

Path Quoting

Always quote paths to handle spaces: 

python uploader.py "%p"              # Correct
python uploader.py %p                # Wrong (breaks with spaces)

Field Value Flow

Ext Fields (%e1-%e4)

  1. External program outputs JSON: 

    {
  "url": "https://example.com/file",
  "file_id": "abc123",
  "status": "success"
}

  2. Map in "Configure & Test" dialog:

  3. ext1 <- "url"
  4. ext2 <- "file_id"

  5. ext3 <- "status"

  6. Values appear in database and templates: 

    Download: #ext1#
File ID: #ext2#
Status: #ext3#

  7. Available in subsequent hooks as %e1, %e2, %e3

Custom Fields (%c1-%c4)

  • User-editable in table (right-click header to show columns)
  • Persist across sessions
  • Can be set manually or by external programs
  • Available in templates as #custom1#-#custom4#

Real-World Workflows

Multi-Host Upload with Tracking

# Completed hook command:
python multi_host_uploader.py gofile "%z" && \
python backup.py --source "%p" --metadata "%N|%s|%t"

Result: - Uploads ZIP to GoFile - Returns download URL in ext1 - Backs up original with metadata - All info available in template

# Use size parameter to choose upload destination:
python smart_uploader.py "%z" --size %s --auto-select-host

Logic: - < 100MB -> Transfer.sh (fast, temporary) - 100MB-1GB -> GoFile (free, permanent) - > 1GB -> pCloud (requires account)

Template-Specific Processing

# Different processing based on template:
python processor.py "%p" --template "%t" --optimize

Behavior: - "High Quality" template -> No compression - "Web Optimized" template -> JPEG compression - "Archive" template -> ZIP with metadata

Automatic ZIP Creation

When using %z parameter, BBDrop automatically:

  1. Detects if command contains %z
  2. Creates temporary ZIP in system temp folder
  3. Uses store mode (no compression) for speed
  4. Executes external program with ZIP path
  5. Deletes temporary ZIP after completion

Performance: - Store mode is 10-50x faster than compression - No disk space wasted after execution - Works transparently with any host

Additional Resources

  • Multi-Host Uploader: See multi_host_uploader.py for 44-host support
  • Keep2Share Uploader: See up3_windows.py for K2S integration
  • Hook System: See src/processing/hooks_executor.py for implementation

Debugging

Test Your Command

  1. Open Settings -> External Apps
  2. Click "Configure & Test..." for any hook
  3. See live preview with all substitutions
  4. Click "Run Test Command" to verify output
  5. View both parsed JSON and raw output

Common Issues

Problem: Parameters not substituted 

# Wrong - no quotes
python script.py %N
# Right - with quotes
python script.py "%N"

Problem: Multi-char variable conflict 

# If you define both %e and %e1, longest match wins
# %e1 is processed first, then %e
# This is handled automatically

Problem: Empty ext/custom fields 

# Fields may be empty - always quote them
python script.py "%e1" "%c1"  # Safe