Toolkit: Bedroom Showcase

Bedroom Showcase builds a photo card for every bedroom straight from your synced property data, so the section always matches what is actually at the property, without anyone touching the page.

---

What it does #

Bedroom cards, one per room, with a photo, the bed types, and a short description, are one of the sections sites end up hand-building in a page builder: a static grid, laid out once when the property is first set up. The problem is that nothing about that grid knows about your property management system. Add a bedroom, change a bed from a queen to two singles, or swap in a new photo, and someone has to go find that grid item and edit it by hand, on every property, every time.

Bedroom Showcase removes that step. It builds the cards from what you already maintain: the room list that syncs from your property management system (which rooms exist and what beds are in them), the photo and description you fill into each bedroom’s custom fields, and, for a bedroom whose photo field is empty, the listing’s own photos. Whichever of those changes, the cards update the next time the page loads. Nobody edits a template.

A bedroom’s photos come from the first of these sources that has something to give:

1. The bedroom’s own photo field, when it is filled in. A filled photo field always wins.
2. The PMS room map: the photos assigned to that bedroom in your property management system. This is the same room data Photo Gallery uses to group photos by room. On by default.
3. Caption matching: listing photos whose captions name the room. Off by default.

A photo the room map places on one bedroom leaves the caption pool, so caption matching can never hand it to a different bedroom.

The module also handles a case that trips up hand-built grids: properties where the bedrooms are not numbered cleanly, for example a Bedroom 1 and a Bedroom 3 with no Bedroom 2. Bedroom Showcase reads the numbers in your room names when every room gives it a distinct one, and otherwise matches rooms to their photo and description fields in sync order instead, so a gap in the numbering never shifts a photo onto the wrong card. If a property has no synced room list at all (for example, a system that does not sync it), the showcase falls back to reading directly from the numbered bedroom photo and description fields you have filled in, so the section still renders.

What guests and operators see:

• One card per real bedroom: a photo, the bed types and counts (for example, “Queen Bed: 1, Single Bed: 2”), and a short description.
• A bedroom photo field can hold one photo or several, entered one per line, comma-separated, or even pasted together with no separator at all. A room with more than one photo gets an in-card slideshow: arrows, a dot per photo, and a counter, always visible and never advancing on its own. Guests step through it with the arrows, the dots, the keyboard, or by dragging the photo sideways with a finger, a pen, or a mouse. The photo follows the drag; a short drag springs back, and a longer one (or a quick flick) moves to the next photo.
• Tapping or clicking a photo opens it full-size in a lightbox guests can page through with next and previous controls or the arrow keys. To close it, guests use the close button, click outside the photo, or drag the photo downward. A short downward drag springs back. Every photo in a slideshow opens the lightbox the same way. If you set Photo tap to Photo Gallery, a tap opens the Photo Gallery‘s full-screen photo view instead, scrolled to the photo the guest tapped, so they keep browsing the whole home (see step 8).
• With the PMS room map on (it is on by default), a bedroom whose photo field is empty shows the photos assigned to that room in your property management system, in your listing’s own photo order, each with its caption. Two bedrooms that share a name stay apart, because the room number tells them apart. A bedroom the toolkit cannot place with certainty gets no photos from this source: a wrong room’s photos are worse than none.
• A bedroom with no photo, no description, and no bed data yet simply does not get a card. Bedroom Showcase never shows an empty one.
• Descriptions keep their basic formatting: paragraphs, line breaks, bold and italic text, bullet or numbered lists, and links come through. Anything an operator pastes in from another tool, such as inline styling or icon markup, is stripped down to that plain structure so the description always matches the rest of the card instead of carrying in a stray font or color.
• If those photo and description fields are managed through the toolkit’s External Custom Fields (Google Sheets) sync instead of directly in your PMS, Bedroom Showcase reads from there automatically, no extra setup required.
• With the optional caption matching setting on, a bedroom whose photo field is empty and that the room map did not fill can still get a card: it takes every listing photo whose caption names the room, in your listing’s own photo order, and each photo keeps its full caption. A photo captioned “Primary Bedroom 3rd Floor – King Bed” lands on the Primary Bedroom card; one captioned “Bathroom 4” joins Bedroom 4’s card too, since an ensuite caption is understood to belong with its bedroom.

How to turn it on #

1. In the HomeRunner Toolkit Hub, switch on Bedroom Showcase. #

2. Place the shortcode #

Add [hrtk_bedrooms] to the property page template, wherever the bedroom section belongs, whether that is in your page builder, a template, or post content. It reads live from the property it is placed on, so the same shortcode works unchanged across every property page.

If you want more control over the layout, a developer can add options to the shortcode: how many columns the grid uses (three by default), the photo’s aspect ratio (4:3 by default), whether the bed list, description, or photo shows at all, a cap on how many cards appear, whether that one placement fills empty bedrooms from the PMS room map or from photo captions, which transition a multi-photo slideshow uses for that placement, and what a tap on a photo opens for that placement.

3. Optional: turn on the automatic Rooms and Beds replacement #

If you would rather not touch a template at all, open the Bedroom Showcase settings in the Hub and switch on Replace the Rooms and Beds section. On single property pages, this finds the existing “Rooms and Beds” (or “Rooms & Beds”) heading and swaps the content under it for the showcase automatically. If a template already places [hrtk_bedrooms] itself, or a property has no rooms to show, the page is left exactly as it is.

4. Check the PMS room map setting #

Fill empty bedrooms from the PMS room map is already on when you switch the module on. If your property management system assigns photos to rooms, a bedroom whose photo field is empty shows the photos assigned to it, with their captions, and there is nothing else to set up. On a listing whose photos carry no room data, the setting does nothing, and the bedroom falls through to caption matching (if on) and the photo fields. Switch it off if you want bedroom cards to show only the photos you fill into the fields yourself.

Today this works for Guesty, which stores which room each listing photo belongs to, and HomeRunner turns the room sync on for each account. If your bedroom cards show no room-map photos, ask HomeRunner support to check that room sync is on for your account. Other property management systems do not send room assignments yet, so for them the setting does nothing and bedrooms fall through to caption matching and the photo fields.

5. Optional: fill empty bedrooms from photo captions #

If some bedrooms have no dedicated photo filled in and no room assignment in your PMS, but you caption your listing photos by room (“Bedroom 4 – 2 Twins Over 2 Full Beds”), switch on Fill empty bedrooms from photo captions in the Bedroom Showcase settings. Any bedroom with an empty photo field then pulls in every listing photo whose caption names it, keeping the caption as the photo’s own label. A bedroom that already has a photo filled in, or that the room map already filled, keeps what it has; this only fills in the gaps.

6. Optional: match your PMS’s field names #

If the custom fields holding each bedroom’s photo and description are not named the standard way, enter your own pattern in the Bedroom Showcase settings so the module knows where to look.

7. Optional: choose the slideshow transition #

For a bedroom whose photo field holds several photos, pick how the slideshow changes between them: Fade, Slide, or None (instant). This applies everywhere the shortcode appears unless a specific placement overrides it.

8. Optional: choose what a photo tap opens #

Photo tap controls what happens when a guest taps a bedroom photo. Bedroom viewer (the default) opens the showcase’s own viewer with that room’s photos. Photo Gallery, scrolled to the room opens the Photo Gallery‘s full-screen photo view, scrolled to the photo that was tapped, so guests keep browsing the whole home. If that exact photo is not in the gallery but the room is one of its photo tour sections, it scrolls to that room’s section instead.

The Photo Gallery choice needs Photo Gallery switched on and placed on the same page, for the same property. When it cannot open (the gallery is missing, it belongs to a different property, or nothing in it matches the photo), the bedroom viewer opens instead, so a tap always shows the guest something. A single placement can override the setting with the shortcode’s tap attribute, set to viewer or tour.

Settings #

Setting	What it controls
Replace the Rooms and Beds section	Off by default. When on, the default Rooms and Beds section content on single property pages is swapped for the Bedroom Showcase cards automatically, no template editing needed. Leaves the page untouched if a template already places [hrtk_bedrooms], or if a property has no rooms to show.
Bedroom photo field	Default bedroom{n}image. The name of the PMS custom field holding each bedroom’s photo, with {n} standing in for the bedroom number. The field can hold one photo or several. Matching ignores case, spaces, and dashes, so bedroom{n}image also finds a field named “Bedroom {n} Image.” Leave blank to use the default.
Fill empty bedrooms from the PMS room map	On by default. When on, a bedroom whose photo field is empty takes the photos assigned to that bedroom in your property management system, in your listing’s own photo order, keeping each photo’s caption. It only works on listings whose photos carry room data; anywhere else it does nothing. It runs before caption matching, and a photo it places is never reused by caption matching. Two bedrooms with the same name stay apart, and a bedroom that cannot be placed with certainty gets no photos from here. A shortcode’s match_rooms attribute (yes or no) can override this for one placement.
Fill empty bedrooms from photo captions	Off by default. When on, a bedroom whose photo field is empty (and that the room map did not fill) takes every listing photo whose caption names that bedroom, in your listing’s own photo order, keeping each photo’s full caption. Matching ignores case and punctuation but needs the whole room name, so Bedroom 1 never picks up Bedroom 10, and a bathroom caption for the same room (“Primary Bathroom,” “Bathroom 4”) joins its bedroom’s card. A shortcode’s match_captions attribute (yes or no) can override this for one placement.
Bedroom details field	Default bedroom{n}details. Same idea, for the field holding each bedroom’s description.
Photo slideshow transition	Default Fade. How photos change in a bedroom card’s slideshow when it has more than one photo: Fade, Slide, or None (instant). Nothing ever advances on its own.
Photo tap	Default Bedroom viewer. What a tap on a bedroom photo opens: the bedroom viewer with that room’s photos, or the Photo Gallery’s full-screen photo view scrolled to the tapped photo. Photo Gallery needs to be on the same page for the same property; otherwise the bedroom viewer opens. A shortcode’s tap attribute (viewer or tour) can override this for one placement.

Tips #

• Pair it with Bathroom Display if you also want full and half baths broken out clearly instead of collapsing into a single count.
• The PMS room map is the same room data Photo Gallery uses to group its “Show all photos” view by room, and the Rooms list in the Photo Gallery settings is a quick way to see whether your newest listings carry room data at all. If that list reports no room data yet, the room map setting has nothing to work with, and empty bedrooms fall through to caption matching and the photo fields.
• If a bedroom the room map should fill stays empty, compare the room’s name in your PMS photo assignments with the bedroom’s synced name. The toolkit only places photos when the names agree (and, where two bedrooms share a name, when the room numbers line up). Rather than guess, it leaves that bedroom to the other sources.
• If the page also uses Property Section Nav for its sticky section menu, Rooms is one of the stops it links to, so guests can jump straight down to your bedroom cards.
• If Photo tap is set to Photo Gallery but a tap still opens the bedroom viewer, check that Photo Gallery is on the same page for the same property. Right after you change the setting, also clear your site’s page cache, since a page saved in the cache before the change keeps behaving the old way until it refreshes.
• If a property shows nothing at all, check that at least one bedroom has a photo in its field, a room assignment in the PMS, a caption-matched photo, or a description filled in. A property with no synced room list and nothing else populated renders an empty section on purpose, rather than a row of blank cards.
• A field name pattern must include {n} for the bedroom number (for example, bedroom{n}image). A pattern that leaves it out, is left blank, or is unreasonably long is ignored, and Bedroom Showcase falls back to the default field names.
• If the automatic Rooms and Beds replacement does not seem to run on a page, confirm that page actually has a “Rooms and Beds” heading. The swap looks for that heading specifically and stands down quietly if the template does not have one.
• Pasting a large photo gallery into a bedroom’s photo field is fine. Bedroom Showcase keeps the first 20 photos it finds and ignores the rest, so one bedroom card can never balloon into an unusably long slideshow. The same cap applies to photos gathered by caption matching. Photos placed by the PMS room map are not capped: a bedroom shows every photo assigned to it there, so keep those assignments tidy in your PMS.
• Caption matching and the room map only fill bedrooms whose photo field is empty. A bedroom with its own photo already filled in keeps that photo, but its assigned and captioned listing photos still count toward matching, so they are never handed to a different bedroom by mistake.