This page will first cover the requirements for getting a WordPress theme integrated with Editus, then will continue on with how to extend Editus for use within your own applications. In each case below with the article, title, and feature image, each relies on the user placing the CSS class of these elements within the settings sub-tab under Editus in WordPress admin.
It’s important to note that this does not cover theme integration with Aesop Story Engine, which is used to bring draggable story components into Editus.
Theme Integration – Minimal
Because Editus sits as an overlay on top of your content, integration is fairly simple and straight forward, with only a few requirements. We’ll quickly list them below, then dive into each as we continue. For the sake of this help article, container is referred to as the target container, or, the div,article, or section that holds the_content.
- container must be dedicated
- container must use the_content filter
Container must be dedicated means that there can’t be any other markup within the container, because Editus saves the markup as a whole. Editus does have an option within the settings that allows you to list CSS classes of items to ignore, however it’s considered best practice to allow a specific container for the content.
Container must use the_content filter means that the container holding the_content must have the_content filter applied. This is what formats text into paragraphs, and is currently what we rely on to break paragraphs on the front-end. This may change as time goes on as it’s a server-side method built into WordPress. Most themes have this applied, but if yours isn’t, then you wont get paragraphs as you type.
Theme Integration – Full
Editus supports not only editing the content, but also changing the featured image of the post, as well as the post title. The following are the requirements of the theme if it will be supporting these features.
- title must not have any other markup inside of it
- featured image must be set as a background image (for now)
Title must not have any other markup means that the title container must be dedicated, just like the container must be dedicated. We save the title, and we sanitize, so it will literally destroy any HTML within it.
Feature image must be set as a background image may change in the future, but this means that the image has to be set as a background image. If there’s a background image, then a button will show with an image icon allowing the user to open the media library and replace it on the front-end. The image is saved automatically (this follows WordPress design pattern on automatically saving the post thumbnail when it’s set). A body class (and actions as outlined further below) is fired when the image is updated, and removed, allowing you to build in any additional visual sexy sauce when the image is set or removed.
The only other thing you should know is, we reserve a special CSS class that you can apply to div items within the_content container and Editus will save them. Add the class .editus–ignore and Editus will remove this from the editor when entering, so that it doesn’t save it as HTML.
Automatic Theme Support
When the user installs Editus and activates, they are redirected to a page with instructions on how to set Editus up. If you have a WordPress theme that we support, then we’ll automatically provide the user with the CSS class that they need to enter in order to get Editus functional. If you have a WordPress plugin that we automatically support, then we’ll ignore this markup when the user saves Editus, so that it does not get saved as HTML. Send us an email with your themes text-domain and article class (only if different than .entry-content, as we support this by default) and we’ll include your theme within the pre-flight process for the user.
Here’s a list of themes we automatically support.
- 2012 – the WordPress team
- 2013 – the WordPress team
- 2014 – the WordPress team
- 2015 – the WordPress team
- Worldview – UpThemes
- Camera – Array
Here’s a list of plugins that we automatically support by ignoring them when Editus is saved, so they do not get saved as HTML.
- Jetpack sharing
- WordPress Ultimate Sharing
Hooks, Actions, & Filters
All available hooks, actions, and filters are documented with examples on Github at the link below. Documentation is open-sourced and available for pull requests for modifications by the community.