DVIDS Image Finder WordPress Plugin

A WordPress plugin that interfaces with the DVIDS (Defense Visual Information Distribution Service) Search and Asset APIs to find images by keyword and unit name, then inserts them into your articles.

Features

• Search DVIDS images by keyword and unit name
• Configurable API key and default unit name
• Customizable thumbnail dimensions and quality
• Easy insertion into WordPress posts via sidebar meta box
• Gutenberg Featured Image panel integration — search and set featured images directly from the Featured Image sidebar
• Support for both Gutenberg and Classic editors
• Automatic sideloading of DVIDS images into the WordPress media library when setting featured images
• Dynamic thumbnail URL generation based on DVIDS specifications

Installation

1. Upload the plugin:

   • Download or clone this repository
   • Upload the dvids-wordpress-image-plugin folder to your WordPress /wp-content/plugins/ directory
   • Or zip the folder and upload via WordPress admin (Plugins → Add New → Upload Plugin)

2. Activate the plugin:

   • Go to WordPress admin → Plugins
   • Find "DVIDS Image Finder" and click Activate

3. Configure settings:

   • Go to Settings → DVIDS Image Finder
   • Enter your DVIDS API key (required)
   • Optionally set a default unit name
   • Configure thumbnail dimensions and quality (defaults: 500px width, 95 quality)

Configuration

API Configuration

• API Key (required): Your DVIDS API key from https://api.dvidshub.net
• Default Unit Name (optional): The default military unit to filter searches by

Thumbnail Configuration

The plugin uses DVIDS dynamic thumbnail specifications:

• Thumbnail Width: Width in pixels (max 2000). If only width is specified, height auto-scales to preserve aspect ratio.
• Thumbnail Height: Height in pixels (optional). If both width and height are specified, the image will be cropped to exact dimensions.
• JPEG Quality: Quality from 1-100 (default: 95). Note: This is ignored when the browser accepts WebP format.

Thumbnail Format Examples

• Width only (e.g., 500px width): Image scales proportionally
• Width and height (e.g., 500x400): Image crops to exact dimensions
• Quality parameter applies only to JPEG; WebP is served automatically to supporting browsers

Usage

Inserting Images into Post Content

1. Create or edit a post:

   • Go to Posts → Add New or edit an existing post

2. Open the DVIDS Image Finder:

   • Look for the "DVIDS Image Finder" meta box in the right sidebar

3. Search for images:

   • Enter a keyword (e.g., "headshot", "training", "deployment")
   • Optionally override the default unit name
   • Click "Search Images"

4. Insert an image:

   • Browse the search results
   • Click "Insert Image" on the image you want to add
   • The thumbnail will be inserted at your cursor position (or at the end of the post)

Setting a Featured Image from DVIDS

1. Open the Featured Image panel in the Gutenberg editor sidebar (under Post settings)
2. Scroll below the standard featured image controls to find the "DVIDS Image Search" section
3. Search by keyword and optional unit name, then click "Search DVIDS"
4. Click "Set as Featured Image" on any result — the image is automatically imported into your media library and assigned as the post's featured image

API Endpoints Used

The plugin interfaces with two DVIDS API endpoints:

1. Search API:

   GET https://api.dvidshub.net/search?q={keyword}&type=image&api_key={api_key}&unit_name={unit_name}&sort=publishdate&sortdir=desc

2. Asset API:

   GET https://api.dvidshub.net/asset?id={image_id}&api_key={api_key}

Technical Details

File Structure

dvids-wordpress-image-plugin/
├── dvids-image-finder.php        # Main plugin file
├── js/
│   ├── dvids-admin.js            # Meta box JavaScript (block/classic editor insertion)
│   └── dvids-featured-image.js   # Gutenberg Featured Image panel integration
├── css/
│   └── dvids-admin.css           # Admin styles
└── README.md                     # This file

Filters and Hooks

The plugin uses standard WordPress hooks:

• admin_menu - Adds settings page
• admin_init - Registers settings
• add_meta_boxes - Adds image finder to post editor
• admin_enqueue_scripts - Loads JavaScript and CSS
• wp_ajax_* - AJAX handlers for search, asset retrieval, and image sideloading
• editor.PostFeaturedImage - Gutenberg filter to extend the Featured Image panel

Security

• All inputs are sanitized using WordPress functions
• AJAX requests use WordPress nonces for verification
• API key is stored securely in WordPress options
• Remote requests use wp_remote_get() with timeouts

Requirements

• WordPress 5.0 or higher
• PHP 7.0 or higher
• Valid DVIDS API key
• Internet connection to access DVIDS APIs

Changelog

Version 1.1.0

• Added Gutenberg Featured Image panel integration via editor.PostFeaturedImage filter
• Added image sideloading — DVIDS images are imported into the media library when set as featured images
• New dvids-featured-image.js for the Featured Image panel UI

Version 1.0.0

• Initial release
• Search functionality with keyword and unit name
• Asset detail retrieval
• Configurable thumbnail parameters
• Support for Gutenberg and Classic editors

Support

For issues, questions, or contributions, please visit the plugin repository or contact the developer.

License

GPL v2 or later - https://www.gnu.org/licenses/gpl-2.0.html

Credits

• Built for integration with DVIDS API - https://api.dvidshub.net
• DVIDS is operated by the U.S. Department of Defense