User Guide

Contents

A guide for shop owners. Version 0.26.1.

A tag such as v1.3 beside a heading shows the version that feature arrived in.

What it does

A product photo can’t answer the two questions that stop people buying art: does this suit my room, and what would several of these look like together?

A shopper photographs their own wall. Your prints appear on it, to scale, against their paint, their furniture, their light. They can hang several, drag them around, line them up and space them evenly, and add the whole wall to the cart in one go.

That second part matters for gallery walls. Picking six prints that work together is hard from a grid of thumbnails, and buying them one at a time is worse.

What it can’t do

It isn’t a photorealistic mockup. Prints are drawn flat on the wall, with no frame, no glass and no shadow, so it shows the art in the space rather than the finished, framed result.

Sizes are close, not exact. The scale comes from four corners the shopper places by eye and one thing they measure. Close enough to tell a 16×20 from a 24×36 in their own room, not a replacement for a tape measure. The plugin says so on screen, and you can change that wording.

It doesn’t make room photos. Shoppers use their own, or ones you supply.

What you need

  • WordPress 6.7 or later
  • WooCommerce 10.0 or later
  • PHP 8.3 or later
  • Variable products with a size attribute, for anything shown to scale

1. Install

Your download is a package. Upload the zip inside the plugin folder, not the package itself. Upload the package and WordPress says “The package could not be installed. No valid plugins were found.”

Plugins → Add New → Upload Plugin, choose that zip, install, activate.

Activate WooCommerce first. WordPress won’t activate In Situ without it.

2. License v0.19

Your key is on your receipt, and in your account at paperpixelstudio.com.

WooCommerce → In Situ → License

A new install opens here and stays here. Until you activate a key, the other tabs stay hidden and the preview shows nothing on your shop. Shoppers see blank space, not an error. Only people who can manage the shop see why.

Paste the key and click Activate. You’ll get Active on this site and the date updates run to.

Moving to another site

Your license covers a set number of sites, and each activation is tied to one address.

Retiring a site, or changing domain? Click Release this site first. That frees the activation to use elsewhere.

Forget, and the new site tells you: This key has no activations left. Release it from another site first.

Local development sites don’t normally use one up.

Check again

Check again asks the store about your key right now instead of waiting for the next automatic check. It also clears what this site remembers about available versions.

Use it after renewing, after releasing a site, or when you know there’s a new version and this site hasn’t noticed.

When a license expires

The plugin keeps working. Settings, rooms, products, all untouched. Shoppers see no difference. Only updates stop.

You get one reminder in the admin, with Renew, License settings and Remind me later. Dismiss it and it’s quiet for three months.

Renew, click Check again, and updates come back.

If the store can’t be reached

Nothing happens. An outage or a firewall won’t switch your plugin off. Only a real answer from the store changes anything.

What the messages mean

It says What to do
This key has no activations left Release it on a site you no longer use
That key belongs to a different product It’s for something else from the same store
The store does not recognize that key Check for a typo, then check your receipt
This key has been disabled or revoked Get in touch
The store could not confirm this key Usually a network blip. Try Check again later

3. Make the preview page

The preview is a shortcode, so it can go on any page.

  1. WooCommerce → In Situ → Preview page
  2. Use the builder to pick a starting artwork and room, if you want one. Leaving both empty is normal: the shopper chooses.
  3. Copy the shortcode into a page and publish it.
  4. Back on Preview page, choose that page under Product page link, and save. v0.16

Step 4 is what puts a link on each product, opening the preview with that artwork already hanging. Skip it and no link appears.

The shortcode

[in_situ_preview]
Attribute What it does
art Opens with this artwork. An attachment ID, or a URL on your own site.
room Opens with this room photo. Same.
art_w The print’s width in inches, if it can’t be read from the product.
art_h The print’s height in inches.

All optional. The builder writes them for you.

4. Turn on a product

Edit a variable product and open the In Situ tab in the Product data box.

  • Room preview switches it on. Off by default.
  • Default artwork is the flat artwork file, not a framed mockup. Every size uses this unless you give it its own.
  • Below those, one row per variation: its Size, the Image it uses, and the Crop needed to fit.

Sizes and cropping

Prints crop from the center to fill the paper. A 3:4 image loses a little at 5×7 and a lot at a square size. The Crop column shows how much.

Losing too much? Give that size its own image. Hover the row, click Choose, and pick a file cropped for that shape. Reset puts it back to the default artwork.

Sizes that can’t be read

The plugin reads each size from the variation’s attribute. “8×10”, “16 x 20” and “11×14 in” all work. Anything it can’t read shows in red and won’t be offered to scale. Rename the attribute, or set the size by hand on the variation.

Seeing everything at once v0.17

WooCommerce → In Situ → Artwork lists every product with the preview switched on and the sizes each one offers. It’s read-only. The settings live on the products.

Products you’ve hidden from the catalog appear here marked Hidden from the catalog, but shoppers are never offered them. Catalog visibility is under Publish → Catalog visibility on the product. Shop and search results and Shop only count as being in the catalog. Search results only and Hidden don’t.

5. Rooms you supply

WooCommerce → In Situ → Rooms

Rooms you add here are offered to everyone, signed in or not. Worth adding even though shoppers can use their own photos: it lets someone try the preview straight away instead of going to find one.

  1. Add a room and choose a photograph. Clear, empty wall works best. A slight angle is fine.
  2. Name it. Shoppers pick from the list by name.
  3. Drag the four points to the wall’s corners, where the ceiling and floor meet its side edges.
  4. Click the ruler and measure something on the wall: a door frame, a window, a light switch. On the wall, not a table in front of it.
  5. Enter the real distance, then Save this room.

The toolbox tells you what’s still missing, and shows the wall’s measured size once you can save.

6. What a shopper does

  1. Chooses a room, or a photo of their own.
  2. Drags the four points to the corners of the wall.
  3. Measures one object on that wall and enters its real size.
  4. Picks artwork and a size, which appears at that scale.
  5. Hangs more, drags them around, aligns and spaces them.
  6. Adds the whole wall to the cart at once.

All of it works from the keyboard, including dragging, aligning and spacing.

What reaches the order

Adding a wall to the cart saves the arrangement with the order, so you can see what they were looking at. If a print has left your shop since, the rest is kept and the customer is told how many dropped off.

Saved rooms v0.12

Signed-in customers can keep 6 rooms, with the wall position and measurement, and come back to them later.

Shoppers who aren’t signed in

They can still use their own photo. It’s read in their browser and never sent to your shop, and they’re told that. One at a time: a new photo replaces the old one, and it’s gone when they close the page. The 8 MB limit applies even though nothing is uploaded.

They’re also offered a link to create an account and keep the room. That link only shows if your shop accepts registrations. Both sentences are editable under Customize text, which is where you’d say whether an account is free.

Photos a customer keeps

Largest file accepted 8 MB
Stored at 2000 px on the longest edge
Kept for 90 days after last use

Uploads are re-encoded, which strips anything hidden in the file. They’re stored outside the media library, and no other customer can see them.

7. Change the wording

WooCommerce → In Situ → Customize text

Every sentence a shopper sees can be replaced. Leave a box empty for the default. Clear a box to go back to it.

Some sentences use tokens, filled in when the sentence is shown. Keep the braces.

Token Becomes
{w} the print’s width in inches
{h} the print’s height in inches
{n} the number of prints

8. Translating

No translations ship with the plugin. The template is languages/in-situ-for-woocommerce.pot, inside the plugin folder.

  1. Open it in Poedit or any PO editor.
  2. Translate, and save as in-situ-for-woocommerce-{locale}.mo. For example, in-situ-for-woocommerce-fr_FR.mo.
  3. Put the .mo in wp-content/languages/plugins/. Create the folder if it isn’t there.

Don’t put it in the plugin’s own folder. Updates replace that folder and your translation goes with it. WordPress checks wp-content/languages/plugins/ first, so a file there survives updates and wins.

9. Clean-up v0.24

WooCommerce → In Situ → Clean-up

One box, unticked: Remove everything from the database when this plugin is deleted.

Leave it unticked if you’re reinstalling or moving hosts. Your settings, rooms, wording and product setup survive, and installing again picks up where you left off.

Tick it only when you’re finished with In Situ for good. Deleting the plugin then also clears your settings, your rooms, your wording, which products were switched on, the artwork chosen for each size, customers’ saved rooms and uploaded photos, and the license key.

Neither option hands the license back. Use Release this site on the License tab for that.

Troubleshooting

The preview page is blank, or shows a licensing message. Customers see nothing at all; that message is only for people who can manage the shop. Check the License tab.

A product has no preview link. All three have to be true: Room preview is on, the product has Default artwork, and a page is set under Preview page → Product page link.

A size is red and says it can’t be shown to scale. Its size attribute couldn’t be read. Rename it to something like 16x20, or set the size by hand on the variation.

A shopper’s wall measurement looks wrong. Nearly always the four points aren’t on the wall’s corners, or they measured something that isn’t on the wall. Anything closer to the camera than the wall reads as bigger than it is, and shrinks everything else.

Toolbar controls look wrong on my theme. The plugin defends its controls against theme styling, but a theme can always go further. Report it and include the theme name.

Getting help

hello@paperpixelstudio.com

Tell us your WordPress, WooCommerce and PHP versions, your theme, and what you were doing. Tools → Site Health → Info lists the versions.

Scroll to Top