Listing Albums for Listeo: Developer Guide
Technical guide for album database tables, REST routes, shortcodes, package meta, collaborative uploads, moderation hooks, and safe overrides.
Architecture overview
The plugin adds a structured media layer on top of Listeo listings. It stores album records in custom tables, links images to WordPress attachment IDs, integrates with listing package metadata, and exposes admin/frontend AJAX handlers plus REST routes.
[listeo_albums] and [listeo_albums_moderation].listeo_albums_init fires after plugin initialization.listeo-albums/v1.Database tables
The plugin creates custom tables through dbDelta(). Do not write raw SQL against these tables from templates. Use plugin APIs or well-contained service code so future schema changes remain manageable.
| Table area | Purpose |
|---|---|
listeo_albums | Album records connected to listings. |
listeo_album_images | Image records, ordering, and attachment relationships. |
listeo_album_permissions | Contributor permissions for collaborative uploads. |
listeo_album_pending and pending upload tables | Moderation queue and pending collaborative media state. |
Package meta
Albums are controlled with package-level metadata. If you build custom package screens or import packages, include these keys.
| Meta key | Purpose |
|---|---|
_package_option_albums | Enables album support for the package. |
_lla_package_albums_limit | Maximum albums per listing. |
_lla_package_images_limit | Maximum images per album. |
_lla_package_total_images_limit | Total album images allowed across the listing. |
_lla_collaborative_uploads | Enables collaborative uploads. |
_lla_collaborative_daily_limit | Daily contributor upload cap. |
_lla_collaborative_require_approval | Requires moderation before publication. |
_lla_exclude_collaborative_from_total | Controls whether collaborative uploads count against total image limits. |
REST routes
The plugin registers routes under listeo-albums/v1 for listing album retrieval and album CRUD operations. Use WordPress REST authentication and permissions. Do not expose write routes to anonymous visitors.
| Route pattern | Purpose |
|---|---|
GET /listings/{listing_id}/albums | Retrieve albums for a listing. |
GET /albums/{album_id} | Retrieve one album. |
POST /albums | Create an album. |
PUT/PATCH /albums/{album_id} | Update an album. |
DELETE /albums/{album_id} | Delete an album. |
AJAX actions
| Area | Actions |
|---|---|
| Albums | listeo_albums_create, listeo_albums_update, listeo_albums_delete, listeo_albums_update_order |
| Images | listeo_albums_add_image, listeo_albums_remove_image |
| Collaboration | listeo_albums_collaborative_upload, listeo_albums_collaborative_upload_file, listeo_albums_save_permissions, listeo_albums_add_contributor, listeo_albums_remove_contributor, listeo_albums_search_users |
| Moderation | listeo_albums_approve_upload, listeo_albums_reject_upload, listeo_albums_bulk_approve, listeo_albums_bulk_reject, listeo_albums_get_pending_uploads |
Hooks
Useful action hooks include listeo_albums_new_pending_upload, listeo_albums_collaborative_upload_added, listeo_albums_upload_approved, and listeo_albums_upload_rejected. Use them for notifications, audit logs, analytics, or external media review workflows.
Safe customization patterns
- Override visual styling in a child theme or custom plugin using scoped CSS.
- Use shortcodes in custom templates instead of editing plugin templates directly.
- Build reports by reading album tables with prepared queries.
- Add notifications through moderation hooks instead of editing core moderation methods.
- Keep license and update classes untouched.
Test checklist
- Album create, update, delete, and ordering work from admin and frontend contexts.
- Package album limits block correctly and display understandable errors.
- Collaborative uploads obey daily limits and contributor permissions.
- Approval and rejection hooks fire once per moderation action.
- Public album display remains responsive on mobile.