Gallery

Part of the IP4CMS portal. ← All module guides

What it's for — Gallery is where you publish photo albums for your community. You group photos into dated albums (a clean-up day, a year-end function, a sports event), upload the images, set their order and pick a cover, then publish so residents can browse them in the member portal. Albums are automatically organised by year, and the module also tracks how much storage your photos are using.

Where to find it — Main portal menu under Communications → Gallery (route /app/gallery, which opens the album list at /app/gallery/list). From an album you reach its detail/photo view at /app/gallery/:id/detail and the create/edit form at /app/gallery/new and /app/gallery/:id/edit.

Before you start

• Your tenant's licence must include the gallery module, or the Gallery menu and all gallery pages return a "not available" response and won't appear.
• You need a gallery permission to see anything: the menu requires gallery:read:all or gallery:manage:all. To actually create, edit, upload, reorder or delete you need gallery:manage:all — read-only access lets you view albums but not change them (see Permissions & access).
• Albums are scoped to a location. The list and the create form use the location currently selected in your portal (selectedLocationId); a new album is created against that location, or against the tenant (no location) if none is selected. Switch your location before creating if you want the album to belong somewhere specific.

Key tasks

Create an album

1. Go to Gallery. The list opens grouped by year. Click Create Album (opens a modal) — or navigate to New Album (/app/gallery/new).
2. Fill in the album fields:

• Album Name (required) — e.g. "Summer Fun Day 2026". Max 255 characters.
• Album Date (required) — defaults to today. This date is important: it is what the year grouping is derived from (the year is extracted from this date), and albums sort newest-date first. Format is a calendar date (YYYY-MM-DD).
• Description — optional summary shown with the album. Max 2000 characters.
• Event — optional. Link the album to an Event from the Events module (the dropdown lists your recent events). Lets residents tie photos to an event.
• Published — defaults to on. When on, the album is visible to residents in the member portal; when off it is a draft, visible to portal operators only.
• Sort Order — optional number used to order albums that share the same date (lower first).
• Cover image — optional when creating. If you attach one, it is uploaded as the album's first photo and set as the cover after the album saves.

1. Click Save. A new album opens at its detail page so you can add photos; an edited album returns to where you were.

If you don't set a cover, the first photo you upload automatically becomes the album cover.

Upload photos

1. Open an album (click it in the list to reach its detail page), or use Add Photos from the album detail screen.
2. Add images one of two ways:

• Drag and drop image files onto the upload zone, or
• Click to browse and select one or more files.

1. Only image files are accepted — non-image files are ignored automatically. You can select many at once (up to 50 per batch).
2. Each file uploads with a progress indicator, then is confirmed and attached to the album. On success you'll see a "photo(s) uploaded" confirmation and the grid refreshes. Image width/height are read from the file and stored automatically.

Uploads go through the portal API to your tenant's object storage. A file must finish uploading before it can be confirmed — if you see "Upload not found in storage", let the upload complete and try again.

Order photos

Photos display in the order you set (then by upload time). To rearrange them:

1. Open the album detail page.
2. Drag a photo thumbnail and drop it onto the position you want. The grid reorders immediately and the new order is saved.

New uploads are always appended to the end of the album, so reorder after uploading if you need a specific sequence.

Set or change the cover

The first photo becomes the cover automatically. To change it, the cover is tied to the album's cover image reference — reorder so your preferred image is first, or delete-and-reorder, and the album cover follows the first remaining photo. (If you delete the current cover photo, the cover automatically resets to the first remaining image.)

View photos (lightbox)

On the album detail page, click any thumbnail to open it full-size in a lightbox. Use the previous/next controls to step through the album. If a photo's file is missing from storage you'll get a "re-upload it to view" warning instead of a broken image.

Edit album details

1. Open the album and choose Edit Album (modal) — or go to /app/gallery/:id/edit.
2. Change the Name, Date, Description, Event, Published state or Sort Order, then Save. Changing the Album Date moves the album to a different year group.

Delete a photo

On the album detail (or edit) screen, use the delete control on a photo and confirm. The photo and its stored file (and thumbnail) are removed. Deletion is permanent.

Delete an album

1. In the album list, click the delete control on an album card and confirm.
2. This permanently deletes the album and all photos in it — the warning spells this out. The image files are cleaned up from storage in the background.

Organise and find albums by year

The list automatically groups albums into year sections (newest year first), based on each album's Album Date.

• Use the Year filter to show only one year's albums.
• Use the Status filter to show All, Published, or Draft albums.
• Use the search box to filter albums by name.
• Use the Clear action to reset all filters.

Check storage usage

The list view shows total gallery storage used for your tenant (e.g. KB / MB / GB), summed across all gallery photos. Use it to keep an eye on how much space your albums consume; deleting photos or albums reduces it.

How the data connects

• What you enter — album metadata (name, date, description, event link, published flag, sort order) is stored in the gallery_album table, scoped by tenant and location. Each album records the year via its album date.
• The photos you upload — image files are streamed through the portal API into your tenant's object storage (the storage key is namespaced as tenant/gallery/album/…). A gallery_image row records each photo's filename, file size, dimensions, sort order, and storage keys. Thumbnails are generated in the background after upload (a queued job), so display stays fast.
• Display — the portal never links residents straight to raw storage URLs. Images are served back through an authenticated proxy endpoint (full image and a thumb variant), which keeps access controlled and CORS-safe.
• What it feeds — published albums and their photos appear in the member portal gallery for residents, scoped to their location, grouped by year, with cover images and per-album photo counts. Draft (unpublished) albums never reach residents. An album linked to an Event ties those photos to that event.
• Storage usage is computed live by summing the recorded file sizes of all your gallery images.

Permissions & access

• Licence module — the whole module is gated by the gallery licence module. Without it, the menu and every gallery endpoint are unavailable.
• gallery:read:all — lets a user see the Gallery menu and browse albums and photos. This is enough to view, but not to change anything.
• gallery:manage:all — required for every management action: creating/editing/deleting albums, the admin album list (which includes drafts), uploading, confirming, reordering and deleting photos, and viewing storage usage. Operators without this permission won't be able to create or modify albums.
• Member visibility — residents see only published albums, scoped to their location. Unpublished (draft) albums are visible only to portal operators via the admin list. Newest albums (by date) appear first, grouped by year.

Tips & gotchas

• File size limit — individual uploads are capped at 50 MB per file by the upload endpoint. Larger files are rejected.
• Batch limit — you can upload/confirm up to 50 images per batch. Drop more than that in one go and split them across batches.
• Image files only — the upload zone silently ignores anything that isn't an image, so a mixed drag-and-drop will only pick up the images.
• The album date drives the year, not the upload date. If an album shows up under the wrong year, edit its Album Date.
• First photo = cover unless you set one. To change the cover, make your preferred image the first photo (reorder), since deleting the current cover resets it to the new first image.
• Thumbnails are generated asynchronously. Immediately after upload a photo may briefly fall back to the full image for display until its thumbnail job finishes.
• Deletes are permanent and cascade. Deleting an album removes every photo in it; file cleanup from storage happens in the background and isn't undoable.
• Storage usage reflects originals. It sums the stored file size of each image, so the headline figure tracks the photos you keep — prune albums to bring it down.
• Location scoping matters. A new album is created against your currently selected location. If an album seems "missing", check you're viewing the same location it was created under.