Selector Detector is an advanced utility tool that helps you to detect CSS selectors for HTML output displayed inside Oxygen. It is most commonly used to create styles for plugin output like contact forms inside of Oxygen.
Selector Detector is available for Widgets, Shortcodes, Code Blocks, and some other Oxygen elements that output nested HTML.
Enabling Selector Detector
Selector Detector must be enabled before it can be used. To enable it, from the WordPress admin panel, go to Oxygen -> Settings and check the Enable Selector Detector checkbox.
Detecting CSS Selectors
To find a selector using the Selector Detector, click the Widget, Shortcode, Code Block or other element you wish to detect selectors for. If Selector Detector is available for this element, a Style Output button will appear at the bottom of the left panel.
Click Style Output, then click any content inside of the active element to detect selectors for it.
Security Considerations
Shortcode Signing
At Oxygen -> Settings -> Security you can choose to prevent Oxygen from executing its shortcodes if they lack a valid signature by selecting "Check Oxygen's shortcodes for a valid signature before executing". As of Oxygen v3.2, an invalid signature warning will only be shown in the WordPress admin area and not on the front-end of the site.
To harden Oxygen against potential attacks, it is highly recommend you enable this option. It is enabled by default for new installs of Oxygen 2.1 and up.
If you wish to show the invalid signature warning on the front-end of the site, you can enable "Show invalid shortcode signature warnings on the front end" via Oxygen -> Settings -> Security.
Shortcode Signing Explained
Oxygen stores the elements on your page as WordPress shortcodes. At runtime, those shortcodes are compiled into PHP, HTML, CSS, and JavaScript.
If another plugin on your site has a security hole which lets unauthorized users execute shortcodes, they could execute Oxygen's shortcodes. Since Oxygen's shortcodes allow for the execution of PHP, they could run any arbitrary PHP code they want on your site - in other words, change your admin password, steal all your user data, or do literally anything else.
Of course, this attack would require another plugin to be present on your site with a security flaw that allows unauthorized users to execute shortcodes. But since it is likely many of these plugins are floating around, it is highly recommended you enable this option.
The only way to generate a valid signature is to have access to the signing keys, which are unique and randomly generated when you install Oxygen. These are stored in your wp_options table, so only a site admin or an attacker who could otherwise read data from your database could get the keys and sign a shortcode.
Further reading: http://www.pritect.net/blog/wordpress-shortcode-injection-attack-vector
WordPress Multisite
By giving users on a multisite network access to Oxygen, you』re giving them the ability to write PHP code from within Oxygen using elements like Code Block or Easy Posts.
Obviously, this means they could they could execute any arbitrary PHP code - just like if you gave them the privilege to install plugins or edit theme PHP files.
Role Manager
By default, access to Oxygen is only available to administrators. Access to Oxygen can be granted to other user roles at Oxygen -> Settings -> Role Manager in the WordPress admin.
Oxygen's role manager works with the WordPress default user roles, any additional user roles added by custom code, and any additional user roles added by 3rd party plugins such as User Role Editor.
Important Security Information
Access to Oxygen should only be granted to trusted users. Because Oxygen provides the ability to execute PHP code, any user granted access to Oxygen could run PHP code to make themselves an administrator.
Revisions System
Note: It is very important to keep regular backups of your site. There are certain scenarios where the Oxygen revisions system cannot help you, and a backup will be the only way to recover your designs.
Oxygen's revisions system grants some redundancy and recoverability to your designs. You can access the revisions for any post or template by clicking the +Revisions link at the bottom of the Oxygen meta box.
Revisions are created every time you click Save in the Oxygen builder, as long as the design has been saved at least once.
To preview a revision, click the "Preview" link in the revision list. This will launch that version of your design in a new tab.
Once you have found the revision you'd like to restore, click the "Restore" link and that version of your design will be restored. The design that was active before you restored will also be saved as a new revision. You can now see which revision of your design you are using by looking for the (current) indicator in the revision list.
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.
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.
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.
Multilingual with WPML or Polylang
Oxygen has rudimentary support for WPML and Polylang.
This is not an official feature of Oxygen and no support will be provided via official support channels.
Note that the Oxygen and WPML teams have been in contact and are jointly investigating official compatibility. This does not mean that WPML compatibility is planned or guaranteed at this time.
Information on translating content created in Oxygen can be found on WPML's website.
Caveats that we're aware of:
Template translation doesn't work for logged out users. As such, you will need to use one template, duplicate your content, translate it within the same template and then use Conditions to show/hide the content based on the language string in the URL.
You can find the Condition code for WPML here and for Polylang here.
WPML and Polylang usually prevent you from being able to save changes to Reusable parts.
Please report issues on GitHub.
Multi-User Editing & Edit Locking
Because of the way Oxygen saves global styles, classes, and settings, multi-user or multi-tab editing with Oxygen is highly discouraged.
We recommend using a single tab when working with Oxygen to avoid issues where one tab is saving older data than another, resulting in overwriting your new changes. The same scenario can occur when two or more users are working in Oxygen at the same time.
To make it easier for teams to collaborate and to prevent this type of issue, Oxygen has built-in automatic Edit Locking.
When Oxygen is open, the following will occur:
The "Edit with Oxygen" button will be replaced with a warning that Oxygen is already open. This change occurs globally across all posts.
The WordPress "Update" button on the specific post being edited with Oxygen will be disabled.
Note: When the edit lock warning is shown, there is an option to open the builder anyway. This should only be done if you are very confident that you understand the consequences of working with Oxygen in multiple locations, or if you believe the edit locking should not be active.
When Oxygen is locked, it is safe to edit the WordPress or ACF content of posts not currently being edited in Oxygen.
Importing & Exporting
To copy an entire WordPress install with all of your content, plugins, settings, and everything else, you can use a plugin like All-in-One WP Migration.
Once you've created a .wpress package with All-in-One WP Migration, import the package on the target site and do the following:
Save your permalinks twice via Settings > Permalinks
Resign your shortcodes via Oxygen > Settings > Security
Regenerate your CSS cache via Oxygen > Settings > CSS Cache
Check to verify that everything looks & works as you expect
You may also need to open each template in the admin area and click the Update button on the right-hand side, but this is rare if you have followed the above steps.
If you just want to copy Oxygen settings or some page designs, use the methods below.
Regardless of the migration method used, you may need to re-sign your site's shortcodes for all elements to render properly once it is moved. See "Re-Signing Oxygen Shortcodes" below for instructions.
Copying Oxygen Settings
You may easily copy Oxygen's settings (global styles, classes, custom selectors, and style sheets) from one install to another. Follow these steps:
On the original install, select Oxygen > Export & Import in the WordPress admin panel.
Copy the text from the Export box.
On the new install, select Oxygen > Export & Import in the WordPress admin panel.
Paste the text into the Import box.
If you want to import Global Colors, tick the Import Global Colors checkbox below the Import box. This will overwrite all currently present Global Colors on the target site.
Click Submit.
Copying Individual Page & Template Designs
To move a Template, Page, Post, or any custom post type, browse to the Edit screen for that post, then click [+] Shortcodes.
Copy the shortcodes.
Then, create a new Template or Page on the new website, and paste the shortcodes into the same [+] Shortcodes box.
Note that if your design relies on any of Oxygen's settings, you must also copy those to the new site, as per Copying Oxygen Settings above.
Moving All Templates & Other Site Content At One Time
To move all content and templates from one site to another, you should use the built-in WordPress import and export tools.
First, on the original install, select Tools > Export in the WordPress admin panel and follow the process.
Now, on the new install, select Tools > Import and follow the process.
Note that it is usually necessary to copy your Oxygen settings to the new install, otherwise your page designs will be missing your global styles, classes, etc.
Re-Signing 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.