Author 诗语

Singular & Archive Templates

Singular & Archive Templates

Singular templates display one item at a time - for example one post, one page, or one instance of a custom post type.
For example, a Singular template would be used to display the following:

A blog post
A page
A WooCommerce product

Archive templates are used to display many items on the same page.
For example, an Archive template would be used to display the following:

A paginated list of all your blog posts
A paginated list of all your WooCommerce products
A paginated list of all your blog posts in a particular category

Singular Templates
On the Oxygen -> Templates -> Edit screen, the options for Singular templates are in the Singular subsection under Where Does This Template Apply?
You can apply the template to:

All Post Types
Posts
Pages
Any Custom Post Types present on your site

Filtering Options

only apply if taxonomized as all of the following - instead of applying the template to all instances of the checked post types, it will only be applied to instances taxonomized as specified
only apply if parent ID is one of the following - instead of applying the template to all instances of the checked post types, it will only be applied if the instance's parent ID matches one of the specified IDs

Archive Templates
On the Oxygen -> Templates -> Edit screen, the options for Archive templates are in the Archive subsection under Where Does This Template Apply?
You can apply the template to:

All archives
Taxonomy archives for the specified taxonomies
Post Type archives for the specified post types
Author archives for the specified authors
Date archives

Further Reading
What is a custom post type?
WordPress can store and display numerous types of content - blog posts, pages, products, and much more. The two main post types that are default with WordPress are Post, and Page. Additional post types can be added to your site by you and the plugins that you install. For example, the WooCommerce plugin adds a Product custom post type. Plugins for real estate listings often add a Property Listing custom post type.
https://codex.wordpress.org/Post_Types
What is a taxonomy?
Taxonomies are ways of categorizing or tagging content. For example, you may have a shoe store with multiple product categories, e.g. men's shoes, women's shoes, boys shoes, girls shoes. You may have a real estate website with multiple listing types, e.g. for rent, for sale, off market, foreclosure. You may have a car dealership website with cars categorized by their condition: new or used.
Product categories, list types, and car condition are all examples of taxonomies.
https://codex.wordpress.org/Taxonomies
Oxygen replaces the WordPress template hierarchy
Normal WordPress themes rely on template files placed in /wp-content/themes/ to display the content on your site. Oxygen simply provides a visual replacement for the normal WordPress template hierarchy, allowing you to design every part of your site visually, inside WordPress, without requiring a theme or any theme files.

Template Hierarchy

Templating Overview

Templating Overview

Templates are designs created in Oxygen that are applied to multiple places on your website. They can be managed inside the WP admin from Oxygen > Templates.
You can create templates that apply to pages, blog posts, WooCommerce products, member portals, bbPress, search results, custom post type archives, and every other part of your site.
Creating a Template & Applying It To Content

Select Oxygen > Templates in the WordPress admin panel, then click Add New Template.
Enter a name for the template, and then click Publish.
Specify where the template applies using the options under WHERE DOES THIS TEMPLATE APPLY?, then click Update to save your changes.
Click Edit with Oxygen to design the template.

Inner Content
Display the content that your template applies to using the Inner Content element.
To add an Inner Content element to a template, click +Add > Basics > Other > Inner Content.
The area covered by the Inner Content will be editable with Oxygen for each item the template is applied to.
If no inner content is created with Oxygen, the WordPress content will be used instead - whether it is a post, page, WooCommerce product, bbPress forum topic, or anything else created within WordPress.
For example, when you apply a template containing a header, Inner Content, and a footer to all pages of your site, the Inner Content area is editable on all pages. You can then use Oxygen to design the Inner Content area for each page or post, while the header and footer will remain the same.
Dynamic Data
Dynamic Data is used to link the design elements within your template to live data from from your WordPress database.
For example, you can link a Heading element in your blog post template to the Post Title in the database. Each blog post displayed with the template will have its title placed in the Heading element. Similarly, you can link a Text element to your post content, link an image or section background to your post's featured image, and much more.
Inheritable Templates
Templates containing an Inner Content element can be inherited by other templates.
Select the template you wish to inherit from Inherit design from other template list. Then save the template.
The editable area of the inheriting template will be nested inside the Inner Content area of the template which is being inherited.
For example, you may have a "Main Template" with a header, Inner Content, and footer. You now want to create a "Blog Post Template" which uses the same header and footer.
Set the "Blog Post Template" to inherit the "Main Template", and it will pull in the header and footer from the "Main Template", and the area editable on the "Blog Post Template" will be the Inner Content area.
Template Priority
When your template settings mean multiple templates could apply to the same content, the template with the highest priority number is used.
To set the priority, specify the Template priority number.
Previewing Content The Template Is Applied To
When editing a template which has been applied to content at Oxygen -> Templates -> Edit, you can preview the content which the template is applied to directly inside Oxygen's visual editor.
Choose the content you wish to preview from the Previewing dropdown menu.
Note: this dropdown may be blank if you haven't yet applied the template to any available content.
Manually Applying Templates
You can manually apply a template to any individual post, page, or custom post type.
To apply the Oxygen template to a specific item on your site, follow these steps:

In the WordPress admin panel, go to the Edit screen for the post/page/CPT you wish to apply the template to.
Select the template from Render page using template list, then save the page.

Example Template Structure
Here is an example structure which could be found on a site with pages, blog posts, and WooCommerce products.

Main template - has header, footer, and Inner Content area. Applies everywhere using Other -> Catch All.
Page template - inherits Main template, has Inner Content area. Applies to all Pages using Singular -> Page.
Blog Post template - inherits Main template, applies to all Posts using Singular -> Post. Instead of an Inner Content area, this template uses Dynamic Data to display post title and content.
Generic Archive template - inherits Main template, applies to all archives using Archives -> All Archives. Instead of an Inner Content area, this template uses an Easy Posts element to list all the posts displayed by the archive.
WooCommerce Product template - inherits Main template, uses Inner Content area to display the WooCommerce product. Applies to all Products using Singular -> Products.
WooCommerce Shop/Archive template - inherits Main template, applies to the WooCommerce shop page which is an archive, and all WooCommerce categories, using Archive -> Post Types -> Products and Archive -> Taxonomies -> Product Categories. Because the Generic Archive template already applies to all archives, this template must have a higher priority number to override it.

Toolset

Toolset

Oxygen integrates with Toolset.
If Toolset is installed and fields are present for the item being edited or previewed, fields created in Toolset will integrate with Oxygen's dynamic data functionality and automatically appear in the Insert Dynamic Data dialog.
Once the Insert Dynamic Data dialog is open, click Toolset to see the available fields.
Toolset Views
To insert a Toolset View, use the Toolset View element that appears at +Add -> WordPress when Toolset is installed, or use the shortcode element.

Migrating An Oxygen Site

Migrating An Oxygen Site

Migrating Full Sites
After migrating an Oxygen site or changing the domain in your hosting, you must follow these steps in order:

Run a search and replace on the database to update the old domain to the new domain (the Better Search Replace plugin is good for this). This isn't needed if you have used a migration plugin that runs a search and replace for you, such as All In One Migration
Save your permalinks twice via Settings > Permalinks
Resign your shortcodes via Oxygen > Settings > Security
Regenerate your CSS cache via Oxygen > Settings > CSS Cache
Re-save your licence key via Oxygen > Settings > License so that your site can use one-click updates when a new version is available

You may also need to open each template in the admin area and click the Update button on the right-hand side but I've only found that to be required on a handful of sites.
If you have any caching plugins installed you will also need to clear the caches.
Migrating Individual Pages or Templates
Manually Copy & Pasting
If you've not used any classes/selectors in your design, you can copy your page/template shortcodes to another site by clicking +Shortcodes below the "Edit with Oxygen" button, copying those shortcodes and pasting them into the same location on a new site.
If you have used classes/selectors, then you would need to copy Oxygen's Export JSON first, as that contains all your Global settings, Classes, Selectors & Stylesheets. You can find it via Oxygen > Export & Import.
Utilising Oxygen's User Design Library
It's possible to make your site a design set that can then be accessed by other sites. There's more information on this here: https://oxygenbuilder.com/documentation/design-library/user-design-library/.
Using a Plugin
The paid, third-party plugin, Hydrogen Pack allows you to copy and paste designs between sites: https://www.cleanplugins.com/products/hydrogen-pack/.

Troubleshooting Guide

Troubleshooting Guide

Most problems and errors you encounter while using Oxygen can be solved using this troubleshooting guide.
If you are getting a 500 error, check your server's error_log file to see the exact error message. Your web hosting provider can help you with this. This error is almost always caused by a misconfigured server or rogue plugin.
Plugin Conflict Test
Improperly coded or misconfigured plugins, especially misconfigured caching plugins, can break Oxygen and your website.
To run a plugin conflict test, disable all active plugins on your site except for Oxygen, and check to see if the problem is solved.
If so, you know the culprit was one of your active plugins. you can then re-enable your plugins one at a time and check for the problem after re-enabling each plugin to find the one causing the conflict.
Caching plugins should generally be configured to not affect the WordPress admin panel, logged in users, or Oxygen's visual editor, which loads JavaScript and CSS files from /wp-content/plugins/oxygen/. Caching plugins that modify these files can break Oxygen.
Check Your Error Log File
If you get an error message in Oxygen, check your server's error_log file for an error message that is logged at the same time you see the error message in Oxygen.
Your web hosting provider can assist you with reading the error_log file.
Many times this error will have meaningful information about the cause of the problem.
Ensure a Modern PHP Version
Oxygen requires PHP v7. Please note that Oxygen isn't yet compatible with PHP v8.
If your host has provided you with an ancient version of PHP and you're not able to update it, you should switch hosts.
Clear All Caches
Clear your browser cache.
If your web hosting provider has caching enabled, clear that cache too. Your web hosting provider can provide assistance with this.
Check & Resave Your Permalinks
Go to the Settings > Permalinks page and change your permalink settings to the default.
Does this fix the problem?
If so, now go to the Settings > Permalinks page and set the permalinks page back to your desired settings.
Check to see if the problem still takes place.
If so, contact your web hosting provider.
If not, it simply means the permalinks needed to be resaved for some reason.
Re-Sign Oxygen Shortcodes
If parts of your design are missing after migrating a site, you will need to re-sign your Oxygen shortcodes.
Before proceeding, perform a full backup of your site.
Once your site has been backed up, go to Oxygen > Settings > Security in the WordPress admin panel and ensure that the "Check Oxygen's shortcodes for a valid signature before executing" checkbox is checked. If it's not, check it and then click Save Changes.
Next, click the "Sign All Shortcodes" link just below the Save Changes button.
Now, check the "I have made a complete backup of my site" box and the boxes for each post type on which you'd like to re-sign the shortcodes. Usually, you'll want to re-sign shortcodes on ct_template, page, and post.
Click the Start shortcodes signing process. You'll be able to watch the progress and see when the re-signing of Oxygen shortcodes has been completed.
Once the process has finished, check the posts or templates that were missing elements and those elements should be visible and editable again.
Regenerate Oxygen's CSS Cache
If your site has been migrated, you will likely need to regenerate Oxygen's CSS cache via Oxygen > Settings > CSS Cache.
500 Error
The most common cause of a 500 error on an Oxygen site is that your site has run out of memory. If the error is only occurring when you try to edit a template, the issue may be caused by the number of items that are being previewed by the template. You can reduce the number of items in the preview dropdown box by setting the Preview Dropdown Limit to something like 10 via Oxygen > Settings > General.
Database Collation
An unsupported database collation can cause Oxygen's shortcodes to be created incorrectly. You will need to make sure that your database and tables are encoded with utf8mb4_general_ci or utf8_general_ci. If the database is set to UTF8 encoding and not utf8mb4_general_ci, 4 byte characters (aka Emojis) in the post meta will prevent anything from being saved.
If you're not sure how to change the database collation on your site, please contact your web host.
Other
The Apache ModEvasive module can prevent the builder from loading as it may incorrectly think that the site is being attacked.

Performance Optimization Options

Performance Optimization Options

Bloat Eliminator
Oxygen』s Bloat Eliminator settings are located at Oxygen -> Settings under the Bloat Eliminator tab.
These settings allow you to disable some third party scripts and functionalities that are not necessary on every site, allowing you to further optimize your Oxygen site.

Disable WP Emojis - Disables built-in WordPress JavaScript for rendering Emojis.
Disable jQuery Migrate - Disables the ability to run deprecated jQuery code on the current jQuery version.
Disable Embeds - Disables the automatic embedding of some content such as YouTube videos, Tweets, etc., when pasting the URL into your blog posts.
Disable Google Fonts - Completely disables Google Fonts for your site.
Disable Webfont.js - Forces Google Fonts to be included using a pure CSS method rather than relying on Webfont.js.

Image Srcset
Srcset is an attribute of image elements that allows the browser to intelligently load the most appropriate size of the image for display based on viewport size. To use srcset, you must use an Image element from +Add -> Basics.

Select the Image element.
In the Properties Pane, choose Media Library.
In the ID field, click the browse button.
Upload or choose the image you』d like to use and click Select Image.
Next, use the Size dropdown to choose the size of your image that you』d like to use.

By loading the image in this way, as long as you haven't chosen the smallest size in the Size dropdown, the image will use the srcset attribute to determine which version to load depending on the viewport size, thus improving page load times.
Further reading: https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
Google Fonts Weight/Italic Picker
By default, if you use a Google Font in Oxygen, all font weights are available and are loaded as long as they are used somewhere on the page or post that you're currently viewing.
The new Google Fonts Weight/Italic Picker allows you to specify the exact weights (and whether to load Italics) you'd like to use, and only ever load those weights regardless of the weights chosen for text elements on your site. To use the Google Fonts Weight/Italic Picker:

Go to Manage -> Settings -> Global Styles -> Fonts.
Choose a Google Font for one of the existing font options or add a new one.
Once you』ve chosen a Google Font, click the weights » link under the dropdown.
Tick the checkboxes for each weight/italic that you』d like to load on your site.

By ticking these checkboxes, you're telling Oxygen to only ever load the weights selected. In this way, if a text element has been set to 400 weight, but you've only chosen 300 and 700 weights in the Google Fonts Weight/Italic Picker, the browser will load the nearest available weight (in this example, 300) when rendering that text element.
Additionally, by choosing italics in the Google Fonts Weight/Italic Picker, your site will load true italics from Google. If italics are not chosen, the browser will render text set to Italic (under Advanced -> Typography) with faux italics by skewing the font.

Post Type Manager

Post Type Manager

By default, Oxygen's metabox appears on the Edit screens for all post types.
You can hide the Oxygen metabox from post types where you do not need it at Oxygen -> Settings -> Post Type Manager in the WordPress admin.

Rebuilding Live Sites

Rebuilding Live Sites

Once Oxygen is activated, it disables the active theme on the site, which means that anything created or rendered by the theme will also be disabled. As such, it's not recommended to install Oxygen on live sites.
There are two methods that can be used to rebuild existing sites; the method you need to choose will depend on if the site is static or active.
Static Sites
If the site is static and doesn't have users logging in or purchasing products then you can create a fresh WordPress install, install Oxygen and rebuild the site from scratch. Once you're happy with it, you can follow these steps to make it live:

Take a full backup of the live site in case you need to revert your changes
Export the new site using All In One Migration and import it to the new site: https://en-gb.wordpress.org/plugins/all-in-one-wp-migration/

Once the site has imported, you will need to:

Save your permalinks twice via Settings > Permalinks
Resign your shortcodes via Oxygen > Settings > Security
Regenerate your CSS cache via Oxygen > Settings > CSS Cache

Live Sites
If the site is active and not static, you can do something like this:

Clone the site to a development/staging environment
Install Oxygen on the site clone
Create templates to display your content and rebuild your pages using Oxygen

Once you're happy with the design and that everything is functioning correctly, you need to merge the changes with your live site:

Put the live site into Maintenance mode
Take a full backup of the live site in case you need to revert your changes
Install Oxygen
Export Oxygen's settings from the development site and import them to the live site via Oxygen > Export & Import
Create all of your templates on the live site. Copy the shortcodes for the templates from the development site to the live site by clicking +Shortcodes below the Edit with Oxygen button
If you've added any pages or modified existing pages using Oxygen, you will also need to copy the shortcodes for those pages from the development site to the live site

Once everything is in place, you will need to:

Save your permalinks twice via Settings > Permalinks
Resign your shortcodes via Oxygen > Settings > Shortcodes
Regenerate your CSS cache via Oxygen > Settings > CSS Cache

If you have any caching plugins installed, you will also need to clear the caches.