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:

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

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 4.7. To upload applications on your server you need to have a modern browser such as Google Chrome, Firefox, Edge or Safari 11.1+.

To install, simply:

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:

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

Please note, that your WordPress server configuration might have tight upload limits. If you experience troubles during uploading of your apps, you need to tweak the following settings in your php.ini file: upload_max_filesize = 128M post_max_size = 128M Check out the official PHP documentation for more info about php.ini configuration.

Uploading Applications

Use the Applications admin menu to access Verge3D Applications screen:

To upload your app, click Edit just under an application's title, click Choose Files and select an application folder in the Update Verge3D Application form:

On this form you can also configure iframe (canvas) size of your application and allow/deny using the 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.

Integrating with WooCommerce

WooCommerce is a popular e-commerce system which powers over 28% of all online stores. As of version 2.16, 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.

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://HOSTNAME/wp-json/verge3d/v1/upload_file/

Where HOSTNAME 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:

{ "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://HOSTNAME/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 in 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 in the link variable:

To retrieve/download your files use the load data and loaded data puzzles.

Receiving Basic Orders

To handle regular orders sent by your Verge3D applications (by the place order puzzle), 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" puzzle. Each time this puzzle is executed, your app will redirect users to your order form:

Managing Orders

Use the E-Commerce 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.

Advanced E-Commerce Applications

In some cases you might want to extend the functionality of your e-commerce system. For example, if you develop a 3D configurator or require more info from your clients to handle orders properly, you need to add more data to the request as well as handle this data on the server. For such cases, you need to encode your data in the JSON format using the "send data" puzzle and then create custom template forms for your e-commerce system.

Say you want to create a basic table customizer. This is how your data might look like:

{ "width": 120, "length": 150, "height": 100, "color": "Redwood", "title": "Custom Table", "price" 100, "user_name", "John Smith", "user_email", "john.smith@example.com", "user_phone", "+123456789" }

You can compose this structure using the dictionary puzzles and then send it to the server using the "send data" puzzle. After that, you need to create custom templates for your order management admin page as well as emails which will be sent to your customers and sales stuff. To do so, copy the following source templates to your WP theme directory under the verge3d subdirectory:

WORDPRESS/wp-content/plugins/verge3d/templates/order_admin_form.php -> THEME/verge3d WORDPRESS/wp-content/plugins/verge3d/templates/order_email_body.php -> THEME/verge3d

Where WORDPRESS is the root directory of your WordPress installation and THEME is the directory of your current theme. Edit these files according to the structure specified for your order.

The last part is to assign a proper URL for your "send data" puzzle. This one looks like:

https://HOSTNAME/wp-json/verge3d/v1/place_order/

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

Plugin Settings

Use Settings admin menu to modify the plugin global settings:

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-mail "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.

Order e-mail PDF attachments options are used to enable PDF attachment in your order e-mails. This attachment includes order content in a printer-friendly format.

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).

Enable REST APIs options are used to enable/disable the order management and persistent file storage APIs provided by the plugin.

Cross-domain requests options is used to enable/disable cross-domain (originated from different hosts) requests to the REST APIs provided by the plugin.

Customizing E-Commerce Forms

To modify e-commerce forms copy the form templates located in the templates directory of the Verge3D plugin to your WordPress theme directory under the verge3d subdirectory.

For example, if you need to modify order email template:

WORDPRESS/wp-content/plugins/verge3d/templates/order_email_body.php -> THEME/verge3d

Where WORDPRESS is the root directory of your WordPress installation and THEME is the directory of your current theme.

Here is the list of templates you can customize:

Template File Description
order_admin_form.php Order management form on the WordPress admin dashboard.
order_email_body.php Order email body template. This template used both for order notifications sent to you and to your customers.
order_email_pdf.php Order email PDF attachment template. This template is used to generate HTML files which will be converted to PDF and attached to order emails.
order_form.php Order form template. This form is displayed to you customers on the pages where [verge3d_order] shortcode is present.
order_success.php Message displayed when the order was accepted.
order_failed.php Message displayed when the order was rejected.

Security Measures

When using custom forms for your e-commerce applications be sure to properly escape output data sent by your customers. Use the following guide for more info.

E-Commerce Protocol Specification

This section is intended for users with advanced server-side coding experience.

The "place order" puzzle uses basic protocol to handle orders. Orders are sent from the browser to server using HTTP POST requests with the following parameters:

POST parameters Description
v3d_title Order title. This field is used to describe the order. Since this value is of no use to customers, it is of use solely for persons that are responsible for handling orders.
v3d_content Order content. This text field includes a complete order information and is visible to both the customer and the sales manager.
v3d_price Order total price. It can be a number or a string, for example 99, 99.99, "$99.99".
v3d_screenshot Order screenshot. This optional value must be a data URI representing an image. This value is generated by the HTMLCanvasElement.toDataURL() method.

The more advanced JSON-based protocol uses the following set of default parameters:

JSON fields Description
title Order title. This field is used to describe the order. Since this value is of no use to customers, it is of use solely for persons that are responsible for handling orders.
price Order total price. It can be a number or a string, for example 99, 99.99, "$99.99".
user_name Customer's full name.
user_email Customer's e-mail address.
user_phone Customer's phone number.
user_comment Order comments.
screenshot Order screenshot. This optional value must be a data URI representing an image. This value is generated by the HTMLCanvasElement.toDataURL() method.

Since this protocol is extensible you can add any parameters you want such as additional configuration options, product properties, shipping address, billing info, taxes, discounts etc.

Got Questions?

Feel free to ask on the forums!