Verge3D WordPress plugin — Soft8Soft
Description: How to setup and use the Verge3D WordPress plugin for the purposes of publishing and e-commerce.

# WordPress Plugin

Verge3D comes with a plugin for WordPress, the most popular content management system (CMS) in use (60+ million installations).

Verge3D for WordPress plugin offers the following features:

- WebGL application hosting and embedding (direct, via iframe, or shortcode).
- An easy-to-use widget for Elementor.
- Integration with WooCommerce system. You can embed Verge3D applications into product pages and make powerful 3D configurators with Puzzles.
- Proprietary e-commerce system alternative to WooCommerce.
- Persistent file storage.

These features can work independently on each other. For example, you might want just the embedding, or you can handle orders received from a Verge3D application hosted somewhere else (such as on Verge3D Network etc).

## Contents

- Plugin Sandbox
- Installation
- Uploading Applications
- Application Settings
- Elementor Widget
- Interacting with Buttons
- WooCommerce Integration
- Alternative E-Commerce System
  - Receiving Orders with Order Form
  - Managing Orders
  - Managing Products
  - Getting Info About Products
- Uploading Files
- Plugin Settings

#

## Plugin Sandbox

To try out the features of the plugin please check out the Verge3D for WordPress sandbox. It provides a safe environment that you can use to test your Verge3D apps.

#

## Installation

Before installing the plugin, make sure you have at least WordPress 5.0. To upload applications on your server you need to have a modern browser such as Google Chrome, Firefox, Edge or Safari.

To install, simply:

- Click Add New on the Plugins settings page from your WordPress admin dashboard.
- Find the Verge3D plugin in the official WordPress.org repository and install it.
- Activate the plugin. Verge3D menu should appear in the admin panel.

In some cases, you might need to install the plugin from the Verge3D distribution (for example, when you're going to try a new feature available in the pre-release version of Verge3D). To do so, follow these steps:

- Upload the plugin archive from verge3d/wordpress/verge3d.zip via WordPress admin interface.
- Activate the plugin in the Plugins menu. Verge3D menu should appear in the admin panel.

After activation, try to upload some of your apps or create a test order to verify that plugin works as expected.

#

## Uploading Applications

Use the Applications admin menu to access Verge3D Applications screen:

To upload new app, click Add New button, enter app name, then click Next. You'll see Manage Verge3D Application dialog. Click Choose Files, select an application folder, then click Upload:

On this form you can also configure iframe (canvas) size of your application and allow/deny fullscreen mode.

To embed Verge3D applications in your WordPress pages/posts use the following shortcode:

`[verge3d id="YOUR_APP_ID"]`

where YOUR_APP_ID is an ID of your application displayed in the table on the Verge3D Application screen.

If you use the Elementor plug-in, there is a widget which can make the things even simpler.

#

## Application Settings

On the Manage Verge3D Application screen you can find the following settings:

Title
  Application name. This value is used in WordPress admin interface only, e.g. to attach a Verge3D app to WooCommerce product page. In order to specify app title shown in the browser (or Google/Bing search) you need to edit the app HTML. Check out the following section to find out how to do this.
iframe width
  Width of the app canvas embedded in WordPress pages/posts/product pages (in pixels). Please note that the actual size can be affected by WordPress theme, layout, custom CSS code, etc.
iframe height
  Height of the app canvas embedded in WordPress pages/posts/product pages (in pixels). Please note that the actual size can be affected by WordPress theme, layout, custom CSS code, etc.
Allow fullscreen mode
  Allow/deny fullscreen mode. If unchecked, the app fullscreen button will be removed making it impossible to enter fullscreeen mode.
Allow AR/VR
  Allow/deny AR/VR sessions for the app.
Loading
  Loading strategy for the application. Set it to Lazy to defer loading when the app is off-screen. Use Eager to force the browser to load it immediately. Auto means the browser itself decides when to load the app.
App Image
  Application image. This image replaces the default 3D view button which is shown in the image gallery on the WooCommerce product page. See below for more info.

#

## Elementor Widget

This feature allows you to embed uploaded Verge3D applications to Elementor pages. Simply drag-and-drop the Verge3D widget from the General tab (or by using search):

and select the application you need on the Content panel:

You can set the size of the canvas and other app features in the application settings.

#

## Interacting with Buttons

With Puzzles, you can easily hook the buttons designed in WordPress (or other button-like elements) to the 3D scene. By clicking a button you can trigger various events in your scene, such as playing animation, doing material customizations, uploading textures, playing sounds, etc. Sometimes this is the most straightforward way to implement UI for your app without the need to develop a full-featured HTML UI.

Example of the page with a Verge3D app embedded, controlled by a button dropped from the Block Editor toolbox.

### Buttons from Built-In Editor (aka Block Editor)

To handle clicks for buttons added with the built-in WordPress editor, first assign a custom CSS class. You can do it by selecting the button and typing your CSS class name in the Block → Advanced → ADDITIONAL CSS CLASS(ES) panel:

Then use the on event of Puzzle to assign event listener on the button element. The element itself is retrieved with the query selector Puzzle:

Specify the CSS class assigned on the button as the first term of the selector (the dot prefix means "get element by a CSS class"), followed by the a for anchor tag:

`.my-button a`

Note, that since Verge3D application is embedded in an iframe, you must also enable in parent doc.

### Buttons from Elementor

Clicks from buttons created with Elementor are handled a bit differently. Instead of class name, you should assign custom ID for your button, which you can do inside the Edit Button → Content → Button ID panel:

Then use the on event of Puzzle to assign event listener on the button element. The element itself is retrieved with the query selector Puzzle:

Specify the element ID assigned on the button as the first term of the selector (the hash tag means "get element by ID"), followed by the a for anchor tag:

`#my-button a`

Note, that since Verge3D application is embedded in an iframe, you must also enable in parent doc.

#

## WooCommerce Integration

WooCommerce is a popular e-commerce system which powers over 28% of all online stores. Verge3D offers a seamless integration with WooCommerce via this WordPress plugin and e-commerce puzzles.

Please refer to this tutorial article for the info on how to use this feature. You may also check out the following video.

### Supported product types

The plugin supports the following product types:

- Simple
- Grouped
- External/Affiliate
- Variable
- Composite (requires the WooCommerce Composite Products extension)

Check out the Drink Shop and Simple Configurator demos from the Asset Store which show how these product types can be integrated with Verge3D.

### 3D only vs 2D gallery + 3D

You can choose between two methods of embedding your 3D app into WooCommerce product page. The first method is to replace the product image entirely:

Spinner product page in Verge3D Sandbox.

This method is especially suitable when your 3D visualization fully describes the look and feel of the product so no additional 2D images are required.

The second method is to add a 3D view button as an item to the gallery of 2D images:

Smart TV product page in Verge3D Sandbox.

To select which method to use, you can simply switch the Show as gallery item setting on the Product data panel (see below).

### Product Settings

For each product supported there is a set of plugin-specific settings located on the Verge3D tab of the Product data:

Application
  Verge3D application which will be displayed on the product page.
Show as gallery item
  Run application upon clicking on the 3D View button in the gallery, or entirely replace the product image by 3D visualization.
Switch to 3D on update
  When running a 3D app as gallery item, enable this setting to automatically slide to the 3D view upon product updates. This feature is useful mostly for configurable Grouped or Variable products. If disabled, WooCommerce would switch to the first 2D image when the user chooses something from the proposed configurations.

### Using Puzzles

With connect to WooCommerce and product info puzzles you can implement quite advanced applications (such as 3D configurators) by retrieving the data on the products or selected configurations from WooCommerce product page.

For usage example, check out the Spinner demo (source files available in the Asset Store).

### Prevent reloading when adding product to the cart

There is a minor gotcha when using the standard WooCommerce setup with Verge3D. Each time the customer adds some item to the product cart, the entire page is forced to reload causing the Verge3D application to reload as well, thus disrupting customer experience.

To overcome this, you can augment WooCommerce with a plugin to add products on a fly, such as AJAX Add to Cart.

#

## Alternative E-Commerce System

E-commerce system which comes with Verge3D for WordPress plug-in is a self-sufficient option alternative to WooCommerce. It allows:

- placing customer orders, submitted with the place order, place order+, or send data puzzles.
- sending notification emails to customers or sales staff.
- generating quotes and invoices, attaching these to emails.
- attaching various data to the orders: PDF, custom text, JSONs, images, sounds, or videos.
- processing payments via PayPal or cards.
- distributing downloadable products.

The system does not rely on any third-party plugins and can be easily customized with PHP to meet your needs.

#

### Receiving Orders with Order Form

To handle regular orders sent by your Verge3D applications (by the place order or place order+ puzzles), add an order form to some of your WordPress page/post using the following shortcode:

`[verge3d_order]`

Then specify the link to that page/post as the "send to" parameter of the place order/place order + puzzles. Each time this puzzle is executed, your app will redirect users to your order form:

For usage example, check out the Ring demo (source files available in the Asset Store).

#

### Managing Orders

Use the Orders admin menu to access E-Commerce Orders screen:

The orders in this list are created automatically upon receiveing requests from Verge3D applications. You can use this screen for reviewing and managing customer orders.

#

### Managing Products

Use the Products admin menu to access E-Commerce Products screen:

These products (could also be product parts) are to be used to compose orders generated by place order+ puzzle. They are not related to the actual products from WooCommerce or other e-commerce solutions.

Each product has the following fields:

Title
  Human-readable product title such as "Verge3D for Blender" or "Spinner". This field is mandatory.
SKU
  Product stock keeping unit. This value is used not only to manage orders by merchant, but primarily to reference product items in the place order + or send data puzzles. Basically, this value is used as product ID.
Price
  Product price. Can be set to zero.
Download link
  Optional link to a downloadable product.

#

### Getting Info About Products

This feature allows the users receive information about products stored on server.

To use it, execute the following REST API method:

`https://WP_HOST/wp-json/verge3d/v1/get_product_info/SKU`

Where WP_HOST is the host name of your WordPress server, such as sandbox.soft8soft.com, and SKU is the product SKU.

Upon success, this method returns the following JSON file with the product info:

`{ "status": "ok", "title": "Product Title", "sku": "SKU", "price": "Product price" "currency": "Currency symbol, such as $" }`

#### Using Puzzles

Use the load data and loaded data puzzles to get info about your products:

#

## Uploading Files

This feature allows the users to persistently store content created in Verge3D applications, such as taken screenshots, uploaded textures, and saved configurations.

To upload your file on the server use the following REST API method:

`https://WP_HOST/wp-json/verge3d/v1/upload_file/`

Where WP_HOST is the host name of your WordPress server, such as sandbox.soft8soft.com

Upon success this method returns the following JSON file with the info on the uploaded file:

`{ "status": "ok", "statusText": "Yay! File uploaded successfully.", "id": THE_ID_OF_THE_UPLOADED_FILE, "link": LINK_TO_THE_UPLOADED_FILE, "size": FILE_SIZE }`

Use the link provided in the request to retrieve your file or use the ID and get_file REST API method:

`https://WP_HOST/wp-json/verge3d/v1/get_file/ID`

### Using Puzzles

Use the send data and loaded data puzzles to upload your files. Parse the JSON fields of the API response by using the dict get key puzzle.

The example below uploads the user-selected file specified in the opened file puzzle to the Soft8Soft sandbox and then saves the web address to that file to the HTML link (`<a href="...">`) element.

To retrieve/download your files from the server you might also use the load data and loaded data puzzles.

For usage example, check out the Custom Image demo (source files available in the Asset Store).

#

## Plugin Settings

Use Settings admin menu to modify the plugin global settings:

Most of these settings are used for the e-commerce system which comes with the plug-in. You don't need these if you just want to use WooCommerce.

### General Tab

Currency
  Currency used to store/display prices.
Price decimals
  Number of decimal digits used to display prices.
Merchant info
  Merchant info: company/brand, address, contacts, logo etc.
Order form fields
  The fields your orders should include.
Order success text
  Text to display when order successfully placed.
Order failed text
  Text to display when order failed.

### Mail Tab

Order notification e-mail
  Option is used to specify an e-mail address of the person responsible for managing orders. When a customer places a new order, you will be notified about this order on this e-mail.
Order e-mails "From"
  Option is used to specify a name/e-mail of a person/organisation that is responsible for communicating with the customer. This can be a sales manager e-mail, some common address such as sales@yourcompany.com or just a no-reply address such as noreply@yourcompany.com.
New order notifications
  Use these options to configure to whom new order notification emails will be sent to as well as subject, content and attachments of such emails.
Updated order notifications
  Use these options to configure to whom order update notification emails will be sent to as well as subject, content and attachments of such emails.
Sales quotes
  Use these options to configure subject and content of quote emails sent to your customers.
Invoices
  Use these options to configure subject and content of invoice emails sent to your customers.

### Documents Tab

To use this feature properly you need to install Chrome/Chromium browser on your server. It will be operated in the so-called headless mode to convert HTML orders to PDF format. Specify the path to the Chrome/Chromium executable if you installed it in some custom directory or leave the path field blank if you installed it system-wide.

Please note, that it order to install Chrome system-wide you need to have admin access to the server. If you don't, download latest Chromium build, unpack it in some user-accessible directory on your server and then specify the path to the Chromium executable in the path field (e.g /home/ubuntu/chrome-linux/chrome).

PDF Generator
  Path to the Chrome/Chromium browser to perform PDF conversion. Leave blank if you installed it system-wide.
Quotes
  Additional content displayed in quote documents and time the quote is considered valid.
Invoices
  Additional content displayed in invoice documents.

### Payment Tab

Paid status
  Order status to set for successfull payments. For example, if you're selling physical goods, you might want to set the order status to Processing, that means that you're processing the order for shipment. If you're selling digital goods, you might want to set the status to Completed. In this case, the download link will be send to the customer by email.
PayPal
  PayPal payment method activation checker and app's client ID. Use the following page for instructions on how to optain it.

### Security Tab

To make your server more secure, always disable features you don't use.

Enable REST APIs
  Options are used to enable/disable the order management, persistent file storage, or product APIs provided by the plugin.
Cross-domain requests
  Option is used to enable/disable cross-domain (originated from different hosts) requests to the REST APIs provided by the plugin.
Custom products
  Allow receiving orders with custom product prices and/or SKUs.
Allowed MIME types

  Application file types allowed to be uploaded and hosted by the plugin. The default list contains most of the types you might ever require, still if you need something more specific, feel free to add MIME and the corresponding extension (separated by a space character) to the list. To find MIME for some file, you might use an online tool, such as this one.

  Uploading common image formats, such as JPEG, PNG, WebP etc., are always allowed by WordPress.

## Got Questions?

Feel free to ask on the forums!