WordPress Advanced Guide — Soft8Soft
Description: How to send forms and orders in background and customize Verge3D for WordPress plugin with JavaScript.

# WordPress Advanced Guide

This guide includes more in-depth topics on how to use Verge3D with WordPress. It describes how to send orders and forms in background and customize the plugin. Also you'll find the formal e-commerce protocol specification here. For basic topics please refer to the WordPress Plugin section of the User Manual.

## Contents

- Receiving Orders in Background via REST API
  - Submitting Orders with Form Data
  - Submitting Orders with JSON
- Sending Forms to Email
- Customizing E-Commerce Forms
- E-commerce Protocol Specification

#

## Receiving Orders in Background via REST API

In some cases you might want to create custom experience for placing orders instead of redirecting users to the order page.

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

`{ "user_name": "John Smith", "user_email": "john.smith@example.com", "user_phone": "+123456789" "items": [ { "sku": "table_top_white", "quantity": 1 }, { "sku": "table_leg_brown", "quantity": 4 }, ] }`

You have two options to make an order based on this data:

1. By using POST request with regular form data (version v1)
2. By using POST request with JSON (version v2)

#

### Submitting Orders with Form Data

To do this, you might compose an HTML form with the fields specified above and then submit it directly or via send data puzzle to the following address:

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

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

With puzzles, the form fields which require user input (i.e. "user_name", "user_email", "user_phone") can be created as follows:

While order items with product SKUs can be composed with hidden form inputs:

The form can be submitted without reloading the entire page as follows:

#

### Submitting Orders with JSON

You can compose this structure by creating a JavaScript object and then send it to the server via JavaScript fetch() call, however using dictionary along with send data puzzle might be easier.

The URL address for submitting orders in JSON format is:

`https://WP_HOST/wp-json/verge3d/v2/place_order/`

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

For example, use the following puzzles to compose the order specified above:

The order item puzzle from the E-Commerce tab might save you some time when composing order items.

#

## Sending Forms to Email

Verge3D for WordPress offers a feature which allows you to send data obtained from custom HTML forms to an email address specified in admin settings. For example, you can use this to receive inquiries or support questions for your products or services, implementing preorders, obtaining customer's contact info, etc.

The URL address for submitting custom forms is:

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

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

The form itself can be implemented with HTML/CSS, Puzzles, or a website builder, like Webflow. See here for more info on creating HTML-based UI. Form submission is performed directly, by clicking on the "Submit" button, or indirectly, via JavaScript/Puzzles (to avoid page reload).

For example, by using Puzzles, you can send the form without reloading the page like that (actual form construction is not shown):

The Inquiry Form library can simplify things a lot. Use it as a basis for your own form solutions.

#

## 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_email_body.php | Order email body template. This template used both for order notifications sent to you and to your customers.
order_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 (e.g. quotes and invoices).
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.
payment_paypal.php | Page for PayPal payment processing.
send_form_email_body.php | Email template for forms generated by REST API.

### 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

The place order and place order + puzzles use the following protocol to handle orders. Orders are sent from the browser to server using HTTP POST requests with the following parameters:

POST parameters | Description
--- | ---
v3d_items | Order items. A JSON-encoded array with order items.
v3d_attachments[] | Order attachments. This optional value must be an array of Data URLs representing order attachments.

The order item has one of the following formats, depending on the puzzle you use. For place order:

Fields | Description
--- | ---
title | Order item title.
price | Order item price.
quantity | Order item quantity: number of units, weight, length, etc.

For place order +:

Fields | Description
--- | ---
sku | Order item SKU (stock keeping unit). This SKU is used as an ID to retrieve information about the product from the server.
quantity | Order item quantity: number of units, weight, length, etc.

The more advanced protocol based on REST API uses the following set of parameters:

JSON fields | Description
--- | ---
user_name | Customer's full name (also used as billing name).
user_email | Customer's e-mail address.
user_phone | Customer's phone number.
user_comment | Optional order comments.
items | Order items. An array with order items.
attachments | Order attachments. This optional value must be an array of Data URLs representing order attachments.
user_address1 | Billing address — line 1. In order to use this field, activate the Billing address option on the General tab.
user_address2 | Billing address — line 2. In order to use this field, activate the Billing address option on the General tab.
user_city | Billing address — city. In order to use this field, activate the Billing address option on the General tab.
user_state | Billing address — state, county, or province. In order to use this field, activate the Billing address option on the General tab.
user_country | Billing address — country. In order to use this field, activate the Billing address option on the General tab.
user_postcode | Billing address — postcode/ZIP. In order to use this field, activate the Billing address option on the General tab.
shipping_address1 | Shipping address — line 1. In order to use this field, activate the Shipping address option on the General tab.
shipping_address2 | Shipping address — line 2. In order to use this field, activate the Shipping address option on the General tab.
shipping_city | Shipping address — city. In order to use this field, activate the Shipping address option on the General tab.
shipping_state | Shipping address — state, county, or province. In order to use this field, activate the Shipping address option on the General tab.
shipping_country | Shipping address — country. In order to use this field, activate the Shipping address option on the General tab.
shipping_postcode | Shipping address — postcode/ZIP. In order to use this field, activate the Shipping address option on the General tab.

## Got Questions?

Feel free to ask on the forums!