LanternWP Companion

By lanternwp

0+ active installationsVersion 1.0.1

Import a complete demo store and add swatches, quick view, back-in-stock emails and 13 more store features to the LanternWP theme for WooCommerce.

Description

LanternWP Companion is the plugin of LanternWP, a block theme for WooCommerce (https://wordpress.org/themes/lanternwp/). With it, your store gets:

  • A complete store to start from: one of six LanternWP demo stores, with its products, photos, pages, menus and look, imported while your store keeps its own settings.
  • 16 store features as blocks that extend WooCommerce’s own: on product cards, on the product page, in the cart and around the store.
  • One screen for all of them, Appearance → LanternWP → Features, with each feature’s switch, whether it works and where it is set.

Every feature and every public demo is free. There is no paid version and no license key.

Companion is made for the LanternWP theme, or a child theme of it, and tested with it; the demo import needs it. The theme works without Companion as a complete store; Companion adds what belongs in a plugin rather than a theme. It needs WooCommerce 11.1 or later: install and activate WooCommerce first, since WordPress does not activate Companion without it.

Demo stores

Each demo is a complete WooCommerce store: products with photos, categories, pages, menus, a journal, a customer with orders, and the store’s look.

  • Common Goods: everyday goods in natural materials, made in short runs. Its look is the theme’s own.
  • Voltline: electronics for the desk and the road, on a dark storefront.
  • Kilowatt: electronics and appliances, with departments, deals and store pickup.
  • Halden: skincare, one good cream and a short routine around it.
  • Tessel: basics for women and men, in the weights and fits you wear every day.
  • Transom: furniture made to fit the room you have, with fabrics, finishes and sizes to choose.

Import one in Appearance → LanternWP → Demos:

  • Your store keeps its own settings (name, currency, address, units, taxes, payments, shipping); when the import is done it lists what is still to set up, with links.
  • The progress shows stage by stage, in short steps, so a host with tight limits can import too.
  • Undo last import puts back the homepage, header, footer, menus, Styles and features the last import changed; the demo’s products and pages stay. Update to version N brings a newer version of the demo.
  • The demo’s look goes into Styles, so it stays without the plugin; Use the look only takes the look without the content.
  • The demos’ photographs are released under CC0 1.0: keep them, change them or use them elsewhere.
  • The same import from WP-CLI: wp lanternwp demo import base.

On product cards

  • Product badges: Bestseller and New badges, set on the product or by rules.
  • Product swatches: a product’s colors as swatches on its card.
  • Second photo on hover: a product’s second photo on its card while the pointer rests on it.
  • Quick view: a product’s photos, options and Add to cart over the catalog.

On the product page

  • Size & option guides: a link beside a product option, such as Size, that opens its guide.
  • How it fits: the cut and the model’s height and size, under a product’s sizes.
  • Fit in reviews: the review form asks how it fits, and the product page shows what reviewers say.
  • Back-in-stock emails: shoppers ask to hear when a sold-out product or option is back.
  • Lowest price before a discount: the lowest price of the 30 days before a sale, as the EU’s Omnibus Directive requires.
  • Dimensions: a product’s size in an in/cm table with its drawing.
  • Samples: fabric or finish samples of an attribute’s values, ordered from the product page.
  • Shipping times: how long a product takes to ship, from its shipping class.

In the cart and around the store

  • Product sets: products that go together, with a shoppable photo, added to the cart together.
  • Free shipping progress: how far the cart is from free shipping.
  • Contact form: messages kept under WooCommerce → Messages and emailed to the store.
  • Bot protection: Cloudflare Turnstile on sign-in, registration and forms.

With the LanternWP theme, the plugin also keeps Store pages (Settings → Reading), Store phone (WooCommerce → Settings → General) and a post’s Shop the story products. WooCommerce’s sale badge reads the discount (−20%) instead of Sale.

Each feature has its page in the LanternWP handbook, with every setting and where it is: https://lanternwp.com/docs/

External services

The demo import downloads LanternWP demo stores from the demo store at lanternwp.com, run by LanternWP (Testica Iga Małłek, Poland). Nothing reaches lanternwp.com until a site administrator selects Show the demos from lanternwp.com in Appearance → LanternWP → Demos, which says first what that means; Stop loading from lanternwp.com on the same screen withdraws it. From then on, the plugin asks it for the list of demos when an administrator opens Demos (kept for an hour), and for a demo’s list of versions and files and the files themselves when an administrator runs an import or uses a demo’s look there, only its manifest for a look (https://lanternwp.com/api/demos/), which it checks against their checksums; the administrator’s browser also loads each demo’s logo or screenshot from lanternwp.com on the Demos screen. The WP-CLI commands wp lanternwp demo import (and look) and wp lanternwp account ask lanternwp.com when someone runs them, as their own request, without the screen’s yes, and do not give it. The requests carry what every request from WordPress carries: the site’s IP address and WordPress’s user agent, which names the WordPress version and the site’s address. Nothing else is sent for the public demos.

A site can also be connected to a lanternwp.com account, to list and import the private demos made for that store; this happens only when a site administrator selects Connect to lanternwp.com in Demos, which shows it only once the demos are allowed there, or runs wp lanternwp account connect. Connecting sends the administrator’s browser to lanternwp.com (https://lanternwp.com/connect/authorize) with the address lanternwp.com answers to (the site’s admin-post.php), a random state and a PKCE code challenge; the administrator signs in and allows the connection there. The site then sends lanternwp.com the code it got back, its PKCE verifier and the same address (https://lanternwp.com/api/connect/token) and keeps the connection token, the account’s e-mail address and the connection’s name it receives. While the site is connected and the demos are allowed, the Demos screen sends that token, in the Authorization header, to lanternwp.com’s account routes (https://lanternwp.com/api/account/) to fetch the account’s demos (kept for an hour, and not asked for while an import step keeps the site busy for longer than ten seconds) and their logos and screenshots, which the site passes on to the administrator’s browser, and an import or a look of one of those demos sends it to fetch the demo’s versions and files; no request for a public demo carries it. WP-CLI’s wp lanternwp account connect sends the token to fetch the account and connection it belongs to, and wp lanternwp demo sends it only when the public routes say there is no such demo (not a version of a demo they have), while the site is connected to an account of the server it names: to fetch the account’s demos, once, then that demo’s versions and files if the account has it. Disconnecting asks lanternwp.com once to end the connection, unless the site’s address changed since it connected (the token may then be another site’s), and the site forgets it whatever lanternwp.com answers; when lanternwp.com could not be told, the screen and WP-CLI say so, and the account ends it in its settings. Every request with the token is sent only while it is still the site’s connection and, from the Demos screen, while the demos are still allowed; the request that ends the connection is sent without the yes. Until the demos are allowed on the Demos screen, the screen sends nothing for a connection made with WP-CLI: it shows the account and the site’s name in it from what the site keeps, neither Connect nor Disconnect, and Forget this connection, which deletes it from the site and sends nothing. Stop loading from lanternwp.com withdraws the yes at once, then disconnects a connected site as Disconnect does; while an import step keeps the site busy for longer than a quarter of a minute, the connection stays, and the screen says so and offers to forget it. When lanternwp.com asks the site to wait (429), a step of the Demos screen’s import is tried again up to five times, each no sooner than lanternwp.com asks, and WP-CLI asks an account route up to three times, waiting as long as lanternwp.com asks when that is two minutes or less (the account’s list for a demo the public routes do not have, and Disconnect, are asked once). A copy of the site at another address does not use the connection; a copy at the same address cannot be told from the site and uses it. The token goes to no other address, no request with it follows a redirect, and each checks lanternwp.com’s certificate. As with every request WordPress sends, another plugin’s HTTP filters on the site can read the request’s headers, the token among them. Nothing else is sent. Privacy policy: https://lanternwp.com/privacy, terms of use: https://lanternwp.com/terms

Bot protection, while a store has turned it on, uses Cloudflare Turnstile, run by Cloudflare, Inc. The visitor’s browser loads Turnstile’s script (https://challenges.cloudflare.com/turnstile/v0/api.js) on a page with a protected form (for back-in-stock requests, once their form shows), and Turnstile reads information about the browser and device to tell a person from a bot. When the form is sent, the site sends Cloudflare the form’s token, the store’s secret key and the visitor’s IP address to check it (https://challenges.cloudflare.com/turnstile/v0/siteverify); saving the settings sends the secret key with a test token. Once a site key is saved, opening Bot protection’s details in Appearance → LanternWP → Features also loads Turnstile’s script in the administrator’s browser, with that key, to check that Cloudflare accepts it before shoppers meet it, also while Bot protection is still off. Terms: https://www.cloudflare.com/website-terms/, privacy policy: https://www.cloudflare.com/privacypolicy/

The demo photographs are licensed under CC0 1.0.

Source code and build

The complete TypeScript and CSS sources are included in resources/, with the shared editor components in resources/editor-ui/. PHP and block stylesheets are used directly. The JavaScript and admin stylesheets in build/ are compiled from these sources with @wordpress/scripts (webpack).

Installation

  1. Install and activate WooCommerce 11.1 or later.
  2. Install and activate the LanternWP theme in Appearance → Themes.
  3. Install and activate LanternWP Companion in Plugins → Add Plugin.
  4. Go to Appearance → LanternWP → Demos, select Show the demos from lanternwp.com, and import a demo, or start from your own products.
  5. Turn features on or off in Appearance → LanternWP → Features.

FAQ

Do I need the LanternWP theme?

Yes. Companion is made for the LanternWP theme, or a child theme of it, and tested with it, and the demo import needs it. The theme works without Companion as a complete store: Companion adds the demo stores and the features above.

Do I need WooCommerce?

Yes, 11.1 or later. WordPress does not activate Companion without WooCommerce. With an older WooCommerce, Plugins and Companion’s screens say which version the site has, with Update WooCommerce.

What does importing a demo change in my store?

The demo replaces the store’s look, the frame of product photos, the header, footer, homepage and menus, and adds its products, posts, pages, author and customer accounts, and orders. Your own products, posts and pages stay, and so do your store’s name, settings and the logo you chose.

Before you confirm, the import dialog says what changes and what stays. A header, footer or template you changed in the Site Editor goes to the trash, and the dialog names it. If you changed Styles, you choose whether the demo’s look replaces your changes or waits in Browse styles.

Can I undo an import?

Yes, the last import, once. Undo last import, under the demo in Appearance → LanternWP → Demos, puts back the homepage, policy pages, logo and site icon, your header, footer and template designs, the checkout page, the menus, Styles and the features the import turned on. The demo’s products, posts, pages, images, accounts and orders stay; you can delete them in Products, Posts, Pages, Media, Users and Orders.

To try a demo’s colors and fonts without its content, use Use the look only instead of Import.

What does Companion send to lanternwp.com?

Nothing until a site administrator selects Show the demos from lanternwp.com in Appearance → LanternWP → Demos, which says first what that means, or someone runs Companion’s WP-CLI commands for demos or the account. From then on, the Demos screen loads the list of demos from lanternwp.com, and an import downloads the demo’s files. The requests carry what every request from WordPress carries: the site’s IP address, its address and its WordPress version. Connecting the site to a lanternwp.com account, for a demo made for your store, is a choice of its own. The store features send nothing to lanternwp.com. The External services section below says every detail.

Is there a paid version?

No. Every feature and every public demo is free, with no Pro version and no license key. A demo LanternWP made for one store is in that store’s lanternwp.com account and is imported the same way.

Where do I get help?

The LanternWP handbook has a page for every feature and for the demo import: https://lanternwp.com/docs/. Ask in this plugin’s support forum or write to hello@lanternwp.com. Security issues go privately to security@lanternwp.com.

Screenshots

Changelog

1.0.1

A demo import keeps your store’s settings, and a site connected to lanternwp.com imports the demos made for its store.
* New: Your demos in Demos: Connect to lanternwp.com connects the site to your lanternwp.com account, once the demos are allowed, to list and import the demos made for your store; Disconnect ends the connection, and what you imported stays. The same from WP-CLI: wp lanternwp account connect, status and disconnect.
* New: When an import is done, Still to set up lists what your store still needs for the demo to work as shown, such as a payment method, a shipping zone for your store’s country or a feature’s setup, each with a link to where it is set.
* Improved: A demo import keeps your store’s settings: its name and tagline, currency and price format, country and address, store phone, units, time zone and date format, the sender of store emails, taxes, checkout account options, payment methods, local pickup and shipping. The import dialog no longer asks which store settings to change.
* Improved: The demo’s logo and site icon are used only where your store has none of its own, each on its own, and the demo’s product weights and dimensions are converted into your store’s units.
* Improved: Undo of an import made with Companion 1.0.0 still puts back the store’s name, settings and shipping zones that import changed, and the dialog says so.
* Improved: Activated on its own from Plugins in a store without a demo, Companion opens Appearance → LanternWP → Demos once.
* Improved: The Privacy policy and Terms of use links on Demos open in a new tab, so the screen where you allow the demos stays open.
* Fixed: A size filter’s range shows exactly the products its count promises, also for sizes with three decimal places, such as in a store that measures in meters.
* Fixed: A back-in-stock form for a sold-out choice is in place as the product page loads, and Notify me can be pressed once the page is ready.
* Developers: The --keep-settings option of wp lanternwp demo import is deprecated: the command still accepts it, prints a warning and ignores it, since the import keeps every store setting. A later version may remove it.

1.0.0

The first version in the WordPress.org plugin directory: demos load from lanternwp.com only once you allow it.
* New: Demos asks before anything is loaded from lanternwp.com: it says what the requests carry, Show the demos from lanternwp.com allows them, and Stop loading from lanternwp.com withdraws that.
* New: Plugins, Features and Demos say when WooCommerce is older than the 11.1 Companion needs, with a link to update it.
* Improved: Compatible with WooCommerce’s High-Performance Order Storage, and declared so.
* Improved: Works on servers without PHP’s mbstring extension.
* Improved: A demo import leaves WooCommerce’s own product sync in place and syncs the demo’s products once more when it finishes.
* Fixed: Without WooCommerce, the blocks that need it are not registered, so the editor shows no warnings about them and no failed block preview.
* Fixed: Page scrolling is locked only under Companion’s own dialogs, not under another plugin’s.
* Fixed: Features and a post’s Shop the story panel no longer log warnings in the browser console.
* Improved: Product sets, size and option guides, samples and back-in-stock requests show and accept only the products the signed-in account may see: another author’s private or draft product stays hidden, in the admin and in the editor.
* Improved: A product added to a post’s Shop the story must be one that the account saving the post may see.
* Improved: Deleting the plugin also removes the features’ settings, the state of a demo import with its working folder and, while WooCommerce is active, its waiting jobs. Caches kept per product expire within a day, and the store’s content stays.
* Improved: An attribute’s edit screen opened from an old address says that LanternWP’s fields are not on it, with a link that opens it again.
* Improved: Bot protection loads Cloudflare’s script again for a form after it failed to load, so one failed load does not stop the page’s other forms.
* Improved: How reviewers say a product fits is counted from its latest 500 answers and kept with the product, instead of counted on every page.
* Improved: Lowest price before a discount loads its stylesheet only on pages that show the line.
* Fixed: A back-in-stock confirmation link shows nothing of a product taken out of the store since the request.
* Fixed: Saving an attribute keeps its samples product when the field’s list no longer holds that product.
* Fixed: A demo import that cannot add a changed image leaves the store the image it had.
* Fixed: Appearance → LanternWP → Features opens while WooCommerce is inactive.
* Fixed: The set editor, the list of sets and a product’s Sets tab have their own styles back, and show prices without the text meant for screen readers.
* Fixed: Quick view keeps its product summary’s spacing in every look.

0.7.1

  • Fixed: A demo import that lost its turn to a newer one stops, instead of overwriting the newer import.
  • Fixed: Starting a demo you are not allowed to import no longer removes the files of that demo’s unfinished import.

0.7.0

A Product Set Hero block, and clearer feature details in Features.
* New: Product Set Hero block: one product set with its photo in a page’s hero; Product Sets shows several sets.
* Improved: An import gives the store its product photo shape, so a demo’s packshots are not cropped twice.
* Improved: Translations come from translate.wordpress.org; the plugin ships no translation files of its own.
* Improved: After activation no screen opens by itself; a notice you can dismiss points to Demos until the store has a demo.
* Improved: The contact form’s button turns on once its script is ready, so a message cannot be lost to a script that failed.
* Improved: The back-in-stock confirmation page is a template of its own, Back-in-Stock Confirmation in the Site Editor, between your header and footer with their blocks intact.
* Improved: A contact message about an order adds a note that says it came and links to it, and no longer copies the message into the order, so deleting the message deletes all of it.
* Improved: The Contact message received email starts with Hello, and does not repeat the name the sender typed.
* Improved: The import dialog says that a demo adds author and customer accounts.
* Improved: Bot protection checks the saved site key with Cloudflare when you open its details in Appearance → LanternWP → Features: a key Cloudflare refuses shows an error under its field, the feature says Needs setup, and forms are not checked until the key works, so a mistyped key does not lock shoppers out. The message names the missing key, and Forms it checks says which of them the store does not show.
* Improved: Product swatches says for each attribute what is missing (no color, a single color, terms without a color), names WooCommerce’s Color swatches for attributes setting only while no attribute has the Color / image type, with a link straight to it, and Products → Attributes says why an attribute has no Type field.
* Improved: Free shipping progress shows its amount in Features (Free shipping over $50, or the lowest and highest across shipping zones) with a link to Shipping zones, says when every order ships free, and says Needs setup when zones have different amounts and the customer’s default location is empty; the shipping zone screens link back to Features.
* Improved: Contact form has details in Features: the contact page, the block’s heading and topics, Messages with the number of new ones, both emails, how long messages are kept and bot protection. The Contact Form block’s Heading is beside its Topics, Send a message by default, and the emails’ preview and test email show a sample message.
* Improved: WooCommerce → Messages lists the date received and an Order column with the number the shopper typed, and a message is New until someone opens it, with a count beside Messages in the menu.
* Improved: Products → Back-in-stock requests filters by product, with the number of requests for each product or option, says Not confirmed yet instead of Pending, and links to the feature’s details and to both emails, which link back to the list.
* Fixed: A contact form sent empty right after the page loads says which fields it needs, instead of being refused as too fast.