Change log

On-Site Editor (OSE) PRO

The On-Site Editor allows admin users to manage designated content from the front-end of the website in a more streamlined and intuitive manner.

Managing content via the OSE provides a simplified editing experience, removing the clutter of the admin environment and focusing only on the content modules and specific properties that have been designated for the OSE. This provides a high level of control for the content you allow to be edited via the OSE.

In addition, Admin User Roles can be configured to allow or disallow certain admin users from accessing OSE as well as configuring admins as OSE editors only, who will then only have access via the OSE and no access to the admin.

Supported Content Types for OSE

The On-Site Editor is compatible with, and can be individually enabled for, the following content types and modules:

  • Site Information (per group)
  • Pages (Page Folders and Pages)
  • Blogs (Blogs and Posts)
  • Events (Groups and Items)
  • Banners (Groups and Items)
  • Galleries/Sliders (Groups and Items)
  • FAQs (Groups and Items)
  • Authors
  • Products/Catalogs
  • Custom Modules

Enabling OSE

The OSE PRO is available as a site extension and can therefore be enabled from your reseller Portal, via the site instance settings, under the ‘Extensions’ tab.

Installing the extension to your site will enable the below options for further configuration.

Site Information

You can enable any Site Information groups to be accessible via the OSE by checking the “Enable On-Site Editor” checkbox in the group settings.

Enable On-Site Editor for Site Information Group

Once enabled, the properties within the enabled groups will display as editable fields in the OSE sidebar when viewing any page of the website.

nICE Text Styling UI

Content Modules

By default, there are no content modules enabled for the On-Site Editor. Each module must be configured as needed to allow OSE access.

1
Enable Module Properties

In the modules settings (under the “ EDIT SETTINGS” option on the modules home screen), navigate to “On-Site Editor Settings”. Move, from left to right, the desired properties (data fields) to make them available for the OSE interface.

2
Define Module Item Wrappers

Data attributes will need to be added to the HTML wrappers/list item layouts to allow the OSE to detect where to allow editing capabilities.

The HTML element that wraps each item (in your ‘List’ and/or ‘Detail’ layouts) should include the following data attribute:

data-cms_ose_item_id="{{this['Id']}}"

For example, in your list/detail layout:

<div data-cms_ose_item_id="{{this['Id']}}">
    <!-- YOUR LAYOUT CONTENT -->
</div>

(since we are working in the module’s layout we can use Liquid to populate the item’s ID for this data attribute)

Other Attributes

Additionally, there is an optional data attribute, that can be added to the item’s wrapper, which forces the OSE to reload the page after any edits are made:

data-cms_ose_reload_page="true"

Why might you use this attribute?
By default, the OSE uses AJAX to dynamically update the edited items directly on the page, without needing to reload the whole page (as a page reload can be detrimental to the admin user’s experience - particularly on slower connections and/or heavy site pages).

However, if an edited item contains other dynamically controlled content or DOM manipulations - such as with many javascript/jQuery plugins, like image sliders and other interactive elements - those plugins can often break with the AJAX reload and that particular site content can become unusable or no longer as easily editable.

Forcing the OSE to reload the page allows the javascript/jQuery to reinitiate the plugins and load the page correctly.

If you are experiencing this issue with your modules, but a forced page reload is not desirable, there is another option to listen for a javascript event which will fire after any edit is made. For further details see the section below “Javascript Events”.

Automatically Added Attributes

The list item's parent HTML element (usually the wrapper for the module layout) will also automatically have the following data attribute added (you do not need to add this manually):

data-cms_ose_module_id="1234"

(where ‘1234’ is the module’s ID)

For example:

<div data-cms_ose_module_id="1234">
    {% component source: "My Module", layout: "List", type: "module" %}
</div>

This data attribute allows the module to be listed in the OSE sidebar and to track and display any item drafts pending publishing.

3
Include Editor Buttons

To interact with the enabled items some buttons need to be added to the layout so we can initiate editing when in OSE mode.

There is no pre-defined, default layout for these buttons. You are free to include these in any way that suits your requirements.

There are two buttons available, one for editing the item and one for deleting the item. Both are optional.

To configure an element (in the item’s layout) to be used as one of these buttons, add either of the following data attributes:

Add New Item button:

data-cms_ose_add_new_item_button="1234"

Edit button:

data-cms_ose_edit_item_button="{{this['Id']}}"

Delete button:

data-cms_ose_delete_item_button="{{this['Id']}}"

For example:

<button data-cms_ose_add_new_item_button="1234">Add</button>
<button data-cms_ose_edit_item_button="{{this['Id']}}">Edit</button>
<button data-cms_ose_delete_item_button="{{this['Id']}}">Delete</button>

(where ‘1234’ is the module’s ID)

If you do not wish to allow item deletion you can omit including the delete button in the item’s layout.
The ‘Enable’ property can be included as an editable field, so you may prefer to encourage admin’s to disable items rather than delete them.

Since the implementation of these buttons is up to you, if simply added to your layout they will also be visible for public viewers outside of the On-Site Editor.

Two possible suggestions for handling this and hiding/removing the buttons when not in the OSE mode are as follows:

Hide Buttons with CSS

When in OSE mode a class of cms_ose_activated is applied to your website’s <body> element. Therefore, you can target the buttons when the OSE is not activated and hide them with CSS styles, like so:

body:not(.cms_ose_activated) [data-cms_ose_delete_item_button],
body:not(.cms_ose_activated) [data-cms_ose_edit_item_button],
body:not(.cms_ose_activated) [data-cms_ose_add_new_item_button] {
    display: none !important;
}

Render Buttons with Liquid

The page URL used when in OSE mode will always contain a URL parameter of enableOSEAdmin=true. Therefore, you can use a Liquid condition to render the buttons only if this URL parameter is present, like so:

{% if request.request_url.params.enableOSEAdmin %}
    <button data-cms_ose_add_new_item_button="1234">Add</button>
    <button data-cms_ose_edit_item_button="{{this['Id']}}">Edit</button>
    <button data-cms_ose_delete_item_button="{{this['Id']}}">Delete</button>
{% endif %}

Editing Pages with OSE

General site Pages can also be edited with the OSE by following the steps above.

However, since you will typically be on the Page during OSE mode (which will be its detail layout) you will need to ensure your edit buttons are on the detail layout for Pages.

This is the same for any module where you want to enable editing on its detail view.

When on the Page (or any detail view) and an edit button has been included in the detail layout, you will see the pencil icon () next to the page title in the OSE sidebar.

Editing Pages (and module items from their detail view) with OSE

Using OSE (Front-end)

With your modules configured you are now ready to access the On-Site Editor mode and start editing content directly from the front-end.

There are several ways to access the OSE.

Firstly, if the admin user is configured as an OSE admin only, they can simply access the editor by appending ‘/edit’ to your websites domain name (or trial site/system URL), for example:

https://www.mydomain.com/edit

Or

https://my-site.trialsite.co/edit

If the admin user has access to the admin, there will be a link directly to the OSE mode at the bottom of the admin’s main navigation on the left hand side.

OSE Link in Main Admin Navigation

Additionally, module items will provide On-Site Editor links, to their detail pages, both from the 3 dot () contextual menu in the module list view:

OSE Link in Module Item's List View

And when on the edit page of an item, the OSE icon () at the top of the screen:

OSE Link in Module Item's Edit Screen

Site Information

When in the On-Site Editor mode, the editing sidebar will display to the left of your website.

Any enabled Site Information groups will display in this sidebar under the “Site-wide content” heading.

Clicking into the group name will present all the group’s fields for editing.

Use the ‘Save’ button at the bottom of the sidebar to apply any changes.

Available Modules

When in the On-Site Editor mode, the editing sidebar will display to the left of your website.

Any detected module wrappers on the current page will be listed in the sidebar and clicking on a listed module name will scroll to that module’s content on the page so that you can easily and quickly access its edit buttons.

Clicking the listed module name’s 3 dot () contextual menu will display an option to publish any draft changes that have been made, along with a number of item’s, for that module, that will be published with this action.

Editing, Drafts & Publishing

When in the On-Site Editor mode, any OSE configured module items should display their edit buttons.

Clicking the edit button will display all the item’s available properties (data fields) and allow you to make changes to their values, much like you would if in the admin area itself.

Upon any initial item’s change, you’ll have the option to save a draft. From that draft you can then choose to publish it directly in the current editing screen, discard the draft, or continue saving the draft.

Drafts do not need to be published at this time before moving on to other changes. The OSE will keep track of all draft versions and allow you to publish those either individually, as a batch per module, or all drafts across the site.

OSE Draft Count with Publishing Options

The OSE will actually detect and show a count for ALL draft files throughout the entire CMS, regardless of if those drafts are within modules configured for OSE or not. So be mindfull of publishing drafts in batches/bulk as this may inadvertently publish drafts that where not necessarily part of the admin user’s OSE session.

Javascript Events

“After” Events

"After" events can be used to retrieve data that was returned from the server after a On-Site Editor Javascript event occurs, in order to apply any custom Javascript logic (for example, reinitiating a javascript/jQuery plugin).

Example usage:

document.addEventListener("CMS_OSE_AfterEditedContentChanged", function (event) {
    var data = event.data;
    console.log("Event data: ", data);
    //additional custom code here (eg: reinitiating a javascript/jQuery plugin)
});

All available "After" events and their returned data are listed below.

CMS_OSE_AfterEditedContentChanged

Fires after a draft has been saved or published for any edited item.

Returned data:
{
    "itemId": 2290,
    "moduleId": 2288
}


Related Articles

  • Admin Users
    Admin Users, found under ‘Settings’, is where you can control administrator access to your website management and content.
  • Admin User Roles
    Admin User Roles provide fine-grain control over permissions for users granted with admin access.
  • Admin Menu Configurator
    Customise the way admin users find and access site content and settings by configuring the admin menu with your own structure, labels, icons and links.
  • Two-Factor Authentication (2FA)
    Treepl CMS provides the option of enabling Two-Factor Authentication for your Partner level access as well as for admin users on a per-site basis.

External Resources

There are currently no external resources available.

Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.


Questions?

We are always happy to help with any questions you may have.
Visit the Treepl Forum for community support and to search previously asked questions or send us a message at support@treepl.co and we will consult you as soon as possible.