I run Boat Build Log, a free site where people building a boat at home keep a dated log of the work: a few paragraphs, a handful of photos, repeat for two years. It's a Laravel app with server-rendered Blade and small plain JavaScript files, no framework on the front end.
This post is about a feature that sounds like an afternoon's work: let a builder put the photos on an entry in order, and number them. It took three commits, one embarrassing CSS bug, and it only exists because an import went wrong.
Why the photos needed numbers
A builder moved his log over from his own website. On his old site every page was a column of photos with a caption under each one. After the import, each entry was one block of text followed by a grid of pictures. All the captions had run together and nothing said which note went with which photo.
He wrote to me, quite reasonably, and asked how a reader was supposed to know that "fitting the sheer clamps" was the fourth picture and not the fifth.
The cheap fix was a number. If every photo shows its position on its corner, the text can say 3. and mean one picture. The lightbox already counted photos ("3 of 9"), so the number on the page just had to match it.
Step 1: number what's already there
This part really was small. In the entry partial:
{{-- Numbered so the writing can point at a photo. The number is the photo's position, the same one the lightbox counts. --}} @if($photos->count() > 1) <span class="photo-num">{{ $loop->iteration }}</span> @endif A single photo gets no badge, since "photo 1" of one is just noise. The badge sits over the corner of the picture and not underneath it, so the grid doesn't grow a row:
.photo { position: relative; } .photo-num { position: absolute; top: 0.35rem; left: 0.35rem; z-index: 1; border-radius: 999px; background: rgba(12, 13, 15, 0.72); color: #fff; pointer-events: none; /* a tap still opens the lightbox */ } The site can also turn a log into a printed book, and the book had to use the same numbers or "see 3" would point at nothing on paper. There the photos get "Photo 1", "Photo 2" in the caption line. One numbering, three places: the page, the lightbox and the book.
I shipped that and felt pretty good for about four days.
The number was useless without a way to choose it
The position came from a sort_order column on the media table, and sort_order was set by whatever order the phone handed the files over. Usually that's the order they were taken. Sometimes it's the reverse. Sometimes it's the order you tapped them in the picker.
So a builder would write "1. dry fit, 2. glued up, 3. clamps off" and the page would show the clamps coming off first. A number is only worth having if the person writing the entry decides which photo gets it.
Step 2: one gesture, three grids
Photos show up in three places while you're writing:
| Where | What's in the grid | What "order" means |
|---|---|---|
| New entry composer | File objects not sent yet | The order they'll be uploaded |
| Edit form, "add photos" | File objects not sent yet | Same |
| Edit form, saved photos | Rows with ids | sort_order in the database |
I didn't want three implementations, so there's one small script, photo-order.js, that knows nothing about files or ids. You hand it a grid of <figure> elements and a callback. It adds a number and two arrow buttons to each figure, makes them draggable, and after every move it tells you the new order as a list of figures. What you do with that is your business.
The composer keeps a pending array of files, so its callback is one line:
window.bblPhotoOrder.decorate(preview, function (figs) { // pending follows the grid, so upload order = numbers on the page pending = figs.map(function (f) { return f._file; }).filter(Boolean); }); The saved-photos grid is even lazier. Each figure holds a hidden order[] input with the photo's id. Browsers submit inputs in document order, so once the figures have moved in the DOM, the form already carries the new order. The callback only has to reveal the Save button.
Arrows as well as drag
My first thought was drag and drop and nothing else. Then I remembered where entries get written: on a phone, in a garage, with epoxy on one glove. HTML drag and drop mostly doesn't exist on touch screens, and a keyboard user needs something to press too. So every photo gets an earlier and a later button, and drag is the extra for people with a mouse.
function move(grid, fig, delta, onChange) { var all = figures(grid); var i = all.indexOf(fig), j = i + delta; if (i < 0 || j < 0 || j >= all.length) return; if (delta < 0) grid.insertBefore(fig, all[j]); else grid.insertBefore(fig, all[j].nextSibling); renumber(grid); if (onChange) onChange(figures(grid)); // keep focus on the pressed button so you can walk a photo across var tools = fig.querySelector('.photo-tools'); (delta < 0 ? tools.children[0] : tools.children[1]).focus(); } That focus line matters more than it looks. Without it, moving a photo from ninth to second is eight separate hunts for the button.
Step 3: the server takes two shapes of request
The edit form also has to work with JavaScript off, so the Blade template renders real submit buttons inside each figure, name="move" value="412:up". When the script loads it swaps those for the in-place arrows. That leaves the controller accepting two shapes and producing one outcome:
public function reorderPhotos(Request $request, Entry $entry) { $this->authorize('update', $entry); $photos = $entry->media()->where('kind', 'image')->get(); $ids = $photos->pluck('id')->map(fn ($id) => (int) $id)->all(); if ($request->filled('move')) { // "412:up" from the no-JavaScript buttons: swap one step [$id, $direction] = array_pad(explode(':', (string) $request->input('move'), 2), 2, ''); $i = array_search((int) $id, $ids, true); // ...422 if it isn't this entry's photo, then swap $i with its neighbor } else { $order = array_map('intval', $request->validate([ 'order' => ['required', 'array'], 'order.*' => ['integer'], ])['order']); // every photo on this entry, once each, and nothing else if (count($order) !== count($ids) || array_diff($order, $ids) || count(array_unique($order)) !== count($order)) { abort(422, 'The order must list every photo on this entry, once each.'); } } // ...write sort_order 0..n in a transaction } The three-part check is the bit I'd point at. A partial list would leave the other photos with stale numbers and two pictures sharing one. A list with a stranger's media id in it would let someone renumber another builder's entry. A duplicated id does both. All three get the same 422.
One more wrinkle: an entry can carry a video embed, which lives in the same media table but isn't in the grid. Inside the transaction, anything that isn't an image is renumbered after the photos, in its existing order, so it keeps its place at the end.
What went wrong
Two things, both small, both mine.
Forms don't nest. Each saved photo already had its own little Remove form inside the figure. I wrapped the grid in the order form, and the browser quietly closed my outer form at the first inner one. The fix is the form attribute, which lets an input or button belong to a form it isn't inside (MDN has the details). The order form now sits outside the grid as a nearly empty element, and the hidden inputs and fallback buttons point at it by id.
hidden lost to my own CSS. The Save order button is supposed to stay out of sight until something moves. I set save.hidden = true and it showed anyway. My .btn class sets display, and an author display rule beats the browser's [hidden] default every time. The same-day follow-up commit switched to style.display = 'none' and left a comment so I don't do it again. It also moved the arrows directly under the picture, because on the first try they landed below the Remove button and looked like they belonged to it.
Was it worth it?
The tests cover eight cases, including the no-JavaScript swap and "only the owner may reorder", and the whole thing is about 140 lines of script. The builder who asked now writes entries that read like captioned pages again, and you can see numbered photos on most of the newer build logs.
If you have a photo grid of your own, feel free to borrow the shape: one script that only moves figures and reports the order, and let each caller decide what the order means. Just depends on what's in your grid. And if you happen to be building a boat, come and log it.
