标签: other
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.
Custom SVG Icon Sets
Oxygen includes 500 icons from FontAwesome and Linearicons.
More icons can be added to Oxygen by importing them from an SVG icon set exported by IcoMoon. Please note that you must include the SVG titles for the icon set to work correctly in Oxygen - see Step 3 below.
Creating a set with IcoMoon
Visit IcoMoon.io and click IcoMoon App at the top right. You are redirected to the web app.
Choose the icons to add to your icon set. You can upload your own icons by clicking Import Icons in the top bar.
Once you have finished, click Generate SVG & More, click Preferences at the top and select "Add
Please note that your symbol-defs.svg file must contain at least two icons.
Adding icons to Oxygen
Go to Oxygen > Settings in the WordPress admin panel.
Click on the SVG Sets tab.
Specify a name for the icon set.
Click Choose file, and then browse to the symbol-defs.svg file found in the .zip file downloaded from IcoMoon.
Click Submit.
The icons are now ready for use with Oxygen.
Using imported icons in Oxygen
You can use the imported icons in Oxygen just like the built-in ones. Follow these steps:
Add an Icon to your page by clicking +Add > Basics > Icon.
Select the set from the Icon Set list.
The icons are now ready to use in your project.
Connecting to Typekit
Adobe Typekit is an online library of fonts. To use Typekit fonts with Oxygen, you must have a Typekit account.
You can connect Oxygen to your Typekit account from the Oxygen -> Typekit page of your WordPress admin panel.
Generating a Typekit API Token
Login to your Typekit account.
Click your Account Avatar at the top right, then click API Tokens.
Click Make me a new API token to add a token.
Copy the API token.
Connecting Oxygen to Typekit
Go to Oxygen -> Typekit in your WordPress admin panel.
Paste in the API token and click Submit.
Select the kit you want to use with Oxygen, and click Submit again. Your domain name is automatically added to this kit. Note that it may take up to 5 minutes for Typekit's servers to update and the fonts to be available for use with Oxygen.
The fonts in this kit will now be available on all of Oxygen's Font Family dropdown lists.
Creating a Kit on Typekit
Once you are logged into your Typekit account, you need to choose the fonts you wish to use with Oxygen by adding them to a kit.
First, click Kits > Create new kit at the top right.
Then, type a name for the kit. You may also specify the domain it will be used on, though this is not necessary.
Click Continue twice, and then click Browse All Fonts.
Once you've found a font you wish to add to the kit, browse to the font page and click Add to Kit.
Then, select the kit from the list and click Publish.
Repeat these steps to add additional fonts to the kit.
Conditions
Conditions allow you selectively display any Oxygen element based on a condition or set of conditions, such as if a user is logged in, or if a user has a certain role or capability.
When an element's conditions evaluate to true, the element is shown. If the conditions evaluate to false, the element is hidden. By default, all of an element's conditions must evaluate to true in order for it to be shown, because the condition type defaults to AND. If you change the condition type to OR, only one of the conditions must evaluate to true for the element to be shown.
To set a condition for any element, select the element and click the condition icon at the top of the Properties Pane. If you wish to add a condition to a Shortcode element, you must wrap it in a Div and add the condition to the Div.
You'll then be presented with the condition menu.
Set Conditions
This button launches the Conditions Modal, where you can set the conditions for this element.
Condition Type
Choose whether the condition stack is evaluated as AND (all conditions must be true) or OR (one condition must be true).
In-Editor Behavior
Choose the visibility of the element in the builder preview. Choose Always Show to make the element always visible in the builder. Choose Always Hide to see what the design looks like when the element's conditions evaluate to false. To preview the element's visibility based on the actual evaluation of its conditions, choose Show/Hide Based on Conditions.
Conditions Modal
Clicking Set Conditions launches the Conditions Modal, where you can designate the conditions used for the element. To get started, click the Add your first condition button in the center of the Modal. Now, you'll be presented with three fields: Condition, Operator, and Value.
Use the left-most dropdown to choose your condition first. Oxygen includes a number of built-in conditions, but conditions registered via the Conditions API will also be listed here.
Once you've chosen a Condition, choose an Operator in the middle drop down field. Operators are used to evaluate some value (for example, the current post's ID) against the value you choose. There are a number of operators available depending on the chosen condition. Some operators, such as contains or does not contain are abstractions of string comparison functions, and work as their name implies. Some conditions may not need an operator, in which case the only available operator will be two dashes (--).
Finally, choose a value in the right hand field. This field may be a dropdown, an input field, or both, depending on the chosen condition. When inputting a custom value, be mindful of the type of data you're comparing. For example, you should not use a string, or text, as the value for a Post ID condition, since it's comparing your value to a number.
Once a condition has been set up on an element, you can see the condition indicator icon next to that element's name in the Structure Pane.
This icon will assist in locating elements that may be hidden by a condition in the builder preview.
Conditions API
The Conditions API allows you to register your own conditions for use within Oxygen. This can be done from a custom plugin or via the Code Snippets plugin.
To begin, it's important to first check if the oxygen_vsb_register_condition function exists before we use it.
if( function_exists('oxygen_vsb_register_condition') ) { }
This prevents errors that would result from Oxygen not being active and our code still trying to call the oxygen_vsb_register_condition_function.
Next, we need to use the oxygen_vsb_register_condition() function to register our condition. The oxygen_vsb_register_condition function accepts the following required arguments:
Condition Name
(string) The name of the condition as it will appear in the Conditions list in Oxygen.
Values
(array) The array of pre-set values the user can choose from. Use the options key to list default values. Set the custom key's value to true to allow users to input custom values. Example: array('options'=>array('option 1', 'option 2', 'true', 'false'), 'custom'=>true).
Operators
(array) Array of operators that can be used in the Condition. Example: array('==', '!=').
Callback Function
(string) Name of function that will be used to handle the condition.
Condition Category
(string) Name of the category under which the Condition will appear in the Conditions dropdown.
In this example, we'll register a condition that checks the current post's ID.
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '', 'array(), 'custom'=>true), array('==', '!=', '>=', '', '=") {
if ($current_post_id >= $value) {
return true;
} else {
return false;
}
} else if ($operator == "<=") {
if ($current_post_id ") {
if ($current_post_id > $value) {
return true;
} else {
return false;
}
} else if ($operator == "<") {
if ($current_post_id array(), 'custom'=>true), array('==', '!=', '>=', '', 'eval_int($current_post_id, $value, $operator);
}
}
If we were evaluating a string, we could use the $OxygenConditions->eval_string() function. To use either function, simply return the function after declaring the condition variables, and pass in the value we're comparing to ($current_post_id), the value the user has chosen ($value), and $operator.
Additionally, when registering Conditions, we can use the $oxy_condition_operators global variable to quickly insert common sets of operators for use in our condition.
if( function_exists('oxygen_vsb_register_condition') ) {
global $oxy_condition_operators;
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), $oxy_condition_operators['int'], 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
return oxy_condition_eval_int($current_post_id, $value, $operator);
}
}
First, we must make the $oxy_condition_operators variable available with the line global $oxy_condition_operators. Next, we replace our operators argument in oxygen_vsb_register_condition() with this variable, and target which set of operators from the array we want to use. There are three sets: int, string, and simple.
$oxy_condition_operators['int'] = array('==', '!=', '>=', '', '<')
$oxy_condition_operators['string'] = array('==','!=','contains','does not contain')
$oxy_condition_operators['simple'] = array('==','!=')
Client Control
Oxygen 3.6 introduces a new "Client Control" tab under Oxygen -> Settings in the WordPress admin panel. There, you'll find that we've consolidated the Role Manager and Post Type manager into this tab.
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 -> Client Control -> Role Manager in the WordPress admin area.
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.
Access Levels
Note: Edit Mode will only be available on sites activated with an Oxygen Agency license.
In the access level dropdown for roles & users, you'll find Full Access, No Access, and Edit Only options.
Full Access will grant the given role or user complete, unrestricted access to Oxygen.
No Access will restrict the given role or user from accessing Oxygen at all, including all admin settings pages.
When Edit Only is chosen for a role or user, several restrictions are imposed for that role or user:
The Oxygen meta box is hidden. Instead, you'll find an Oxygen icon button in Gutenberg or a blue "Edit with Oxygen" button at the top of post edit screens using the Classic Editor.
The "Oxygen" admin menu is replaced with a single "Templates" link.
The Manage button in the builder is hidden. Edit Only users cannot access global settings, stylesheets, or selectors.
The +Add button is hidden.
The Conditions, Link, Duplicate, and Delete icons in the Properties Pane are hidden.
The add class button in the Selector Dropdown is hidden.
The copy, clear, and delete icons in the Selector Dropdown are hidden.
The Advanced tab in the Properties Pane is hidden.
Code Blocks cannot be clicked or edited.
In the Structure Pane, the hamburger menu for elements is hidden.
In the Structure Pane, the delete icon for elements is hidden.
Drag & drop is disabled.
These restrictions make it safe to let a client into Oxygen as they can only change styling and content. There's no access to code, global styles or settings, deletion, or re-arranging of elements.
This, however, may be far too restrictive for some cases, so we've added some granular controls that appear once you've chosen "Edit Only" access for a role or user:
Enable Elements: Allows role/user access to insert, duplicate, and delete specified elements.
Enable Advanced Tab: Allows role/user to use the Advanced Tab in the Properties Pane. All Custom CSS and JavaScript tabs will still be hidden.
Enable Drag & Drop: Allows role/user to drag and drop elements in the builder.
Enable Reusable Parts: Allows role/user to add Reusable Parts.
Enable Design Library: Allows role/user to add elements from the Design Library.
Disable Classes: Prevents role/user from being able to modify a class that has been applied to an element.
In addition to these restrictions, you can also lock roles/users with Edit Only access completely out of Oxygen on specific posts using the new "Lock Post In Edit Mode" checkbox in the Oxygen meta box. This does not restrict the role/user's ability to access the WordPress editor for that post.
Per User Access
In addition to the Role Manager and Post Type manager controls, you'll also find a "Per User Access" control section that allows you to define access on a per-user basis. Settings defined here will override role-based settings for a given user.
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 via Oxygen -> Settings -> Client Control -> Post Type Manager in the WordPress admin area.
IMPORTANT SECURITY INFORMATION
Full access to Oxygen should only be granted to trusted users. This is because Oxygen provides the ability to execute PHP code, so any user granted access to Oxygen could execute code to make themselves an administrator.
Advanced Query Builder
In addition to the default, custom, and manual query options available for Easy Posts and Repeater elements, you can also choose the advanced option.
This query type allows you to visually build a query based off of WP_Query parameters and optionally, dynamic data from WordPress.
You can build virtually any type of query that WP_Query supports by using the advanced query option:
Related posts by taxonomy
Queries based on custom field values (e.g. ACF relationship fields)
Author archive queries
Child post queries
The advanced query option includes a few presets that cover some of these use-cases without having to manually configure the query.
Building Your Query
Note: advanced queries are an advanced topic and it's very helpful if you understand how WP_Query works. You can see a full list of WP_Query parameters, along with descriptions of their function, at https://www.billerickson.net/code/wp_query-arguments/.
To begin building your query, select your Easy Posts or Repeater element and navigate to the Query settings in the Properties Pane. Choose advanced and then, if you're not using a preset from the preset dropdown, click Edit Query.
You'll then see the Advanced Query modal. Begin building your query by clicking the blue Add Query Parameter button.
Next, choose the desired query parameter from the dropdown.
Once a parameter is chosen, click the Add Value button.
Depending on which parameter is chosen, you'll either be presented with a text input field or a dropdown. All text input fields in the Advanced Query modal can be populated with dynamic data by clicking the data button in a given field.
Some query parameters accept multiple values or multiple different types of values. One example of this is tax_query, which accepts an array of data to help identify the posts that should be returned.
Once array is chosen from the dropdown for the tax_query, you can then add values to the array itself to build the query.
As you can see from this example, it's possible to build very complex queries using the Advanced Query option. You can also add multiple query parameters to a query.
Examples
ACF Relationship Field
To use an ACF Relationship field, edit your Advanced Query and add the post__in parameter.
Next, add a value. Then click the data button in the parameter's value field.
In the Dynamic Data dialog, click Advanced Custom Field and then your ACF relationship field from the list of available fields.
On the next screen, make sure to put a single comma ( , ) in the separator field.
Next, click INSERT.
Now, close the Advanced Query dialog and click Apply Query Params button in the Properties Pane to see the result. Note that you must be previewing a post with a populated ACF relationship field in order to see the results as expected.
You can further narrow your query by adding post_type and other parameters to make it more efficient.