Help Center

Menu

Adapting an existing design template to work with inline edit

This tutorial steps you through the process of converting an existing Matrix template to work with the new inline editing feature. Inline editing lets your content editors edit content by seeing what their content changes will look like within the context of the actual page design.

This tutorial is particularly relevant if you are upgrading from Matrix 5 to Matrix 6 and want to make sure your existing templates will function correctly and continue to provide a consistent content editing experience.

What are custom edit layouts?

Custom edit layouts are a Matrix asset that allow you to control the editing layout of your content for Inline edit mode at both a global and local level.

Custom edit layouts can be applied globally to customize the editing experience for a type of asset anywhere it is used in the Matrix instance. For example, a custom edit template applied globally to a standard page would change the editing experience for all standard pages in the website. (for example, standard page, news, events).

You can also apply custom edit layouts locally to customize the editing experience for individual component templates. For component templates, custom edit layouts work on both Inline edit and Content screens.

This tutorial uses a combination of global and local custom edit layouts to practically demonstrate when to use each layout to make your inline edit mode experience easier to maintain.

Before you start

For this tutorial, you will require the following:

  • Access to a Squiz Matrix server, version 6 or later.

  • An existing template that you want to adapt to work with inline edit.

  • A Matrix user account type of system administrator. Your user account must be in the System management  System administrators user group.

  • An understanding of what the inline edit feature is.

  • An understanding of Design and layout assets.

Setting up a test copy of your site

You can set up a test copy of your site on the same Matrix instance by exporting your template then reimporting it into a new site structure.

This step is optional, but recommended. By completing this step you get an opportunity to experiment and test out your changes before you commit to updating your live templates.

The process of duplicating your site template may have extra steps beyond the scope of this suggested approach, particularly if you have a more complex site build.

To set up a test copy of your site:

  1. Export the folder containing your template using the Export assets to XML tool tool.

    This folder typically includes all of your design assets, paint layouts, metadata schemas, asset listings, and other asset types that control the look and feel of your website.

  2. Create a new test folder to hold the duplicate copy of your template.

    If you have a sandpit or test area within your Matrix instance, this location is perfect to hold the duplicate copy of your design. If you don’t have an area like this on your instance, you can create the test folder at the root of the server.

  3. Import a new copy of your template using the Import assets from XML tool tool.

  4. Apply new URLs to any site assets in the import (for example, the Designs site)

  5. Create a new site asset to test the design against, add a URL, as well as a home page set as the site index.

  6. Apply any global assets from your template to your test site, Designs, Paint Layouts, Custom edit layouts, Metadata Schemas, etc. The goal is to have all template elements used in your original site available to test in your test site.

    If your site has a lot of customizations or paint layouts, this step may take some time. You may want to start with just the most commonly used design and paint layout combinations.

  7. Review your test site to make sure it is a good representation of the functionality of your real site.

Disabling or enabling inline edit mode

For each design asset there is an enable inline edit mode setting. This setting is disabled by default for newly created designs.

If left disabled, when users access /_edit on standard page assets using the design, they are redirected to either the content or details screen of that asset rather than inline edit mode. The inline edit mode option in the screen header is disabled for all users for those assets.

Watch this video to learn the basics of using inline edit mode.

Enabling inline edit mode

You must enable inline edit mode for your duplicated design. You can then preview the inline edit experience and work out which parts of the design can be improved for a more seamless inline editing experience.

To enable inline edit mode:

  1. Access the Details screen of the relevant design asset.

  2. Turn on the Enable inline edit mode option.

  3. Edit a content page with the design applied to confirm that the inline edit button is available and you can access inline editing.

Disabling inline edit mode

The simplest way to make sure your template is compatible with Matrix 6, and avoid any confusion for content editors working on a site with your template applied, is to disable the inline editing feature for the given design.

This will allow the design to work as it would in Matrix 5, with only the Content screen available. If you have many sites and templates, you can then control a gradual conversion of templates to work well with the inline editing feature.

To disable inline edit mode:

  1. Access the Details screen of the relevant design asset.

  2. Turn off the Enable inline edit mode option.

  3. Edit a content page using the design to confirm that the inline edit button is no longer available.

Review your default global inline editing experience

For some Matrix templates, you may not need any further action to start using inline editing. For example, for standard pages using only WYSIWYG components, inline editing will most likely work smoothly.

In this step, you’ll review what the default inline editing experience is like for the global parts of your template, to identify the areas of the template to adapt to work better with inline editing.

Your overarching site design may impact how inline editing designs work on some asset types. The steps that follow describe a basic test process you can build upon depending on the complexity of your site.

To review your default inline editing experience:

  1. Create a standard page asset in your site.

  2. Open your page in inline edit mode.

  3. Take a note of any global design elements missing in inline edit, these will be parts of the Paint Layout. Look for issues such as:

    • Missing headings

    • Missing wrapping div tags

    • Missing design elements such as right column asides, banners, header and footer.

  4. Test any other global paint layouts that your site template uses in the same manner. Some asset type examples to check include event, link, and data record asset types.

Review your default component template editing experiences

Aside from the global template, the other major impact on the quality of the inline editing experience is component templates.

To review your default component template editing experience:

  1. Create a standard page asset in your site.

  2. Add one of each component template to the page.

  3. Save and update content for each field in each component template.

  4. Take a note of any component templates that render incorrectly or that you can’t edit fully. Look for issues such as:

    • Any fields not saving

    • Image metadata fields not working correctly

    • Related asset metadata fields not working correctly

    • Any custom JavaScript interactions

You should now have a list of all issues to address to improve inline editing for your template. You can prioritize these, and choose which to address, using the following remediation options.

Add global custom edit layouts to match global paint layouts

Custom edit layouts allow you to control the editing layout of your content for inline edit mode, at a global template level, as well as at a component template level. For component templates, custom edit layouts work on both inline edit and content screens.

If parts of your global design are missing in inline edit mode, you will likely need to recreate parts of your paint layout code in your global template. While these changes may be subtle, (for example, an extra HTML div tag with a class) they may significantly impact the look and feel of the page depending on how the CSS renders the page.

To add a global custom edit layout:

  1. Create a custom edit layout asset.

  2. Edit the contents of your custom edit layout, and add the keyword %__custom-contents%.

    You can use the View custom edit layout keywords link to find other values you want to be editable on the inline edit screen, such as the asset name.

  3. Above and below the custom-contents keyword, add the HTML from your paint layouts

  4. On your site asset, navigate to Settings  Custom edit layouts.

  5. To add a layout to the site, select Standard page from the Add layout dropdown, and select Save.

  6. In the Standard page section, select inline_edit from the screen drop down.

  7. Select Save to commit the layout changes.

  8. Select your newly created custom edit layout, and commit

  9. Access the inline edit screen of a page within your site, you should now see the missing elements from your Paint Layout rendered and be able to update the asset contents in inline edit mode.

If you use Server Side JavaScript (SSJS) in your templates, this will still render within inline edit mode.

Adding additional custom edit layouts for different assets

Now that you understand how to add a custom edit layout, you can repeat the process for other asset types such as news and events. Additional asset types can be applied with one custom edit layout by using type formats.

If you have different paint layouts set for different root nodes within your site, you will need to set equivalent custom edit layouts to match those paint layouts for each root node.

To add an additional custom edit layout for another asset type:

  1. Create a new custom edit layout asset.

  2. Edit the contents of your custom edit layout.

  3. Use the View custom edit layout keywords link to find the values you want to be editable on the inline edit screen. For example, for a news asset you will probably want %details-F_name%, %details-F_summary% and %details-F_body% to edit the name, summary and body of the news item on the inline edit screen.

  4. On your site asset, navigate to Settings  Custom edit layouts.

  5. Select your asset type from the Add layout dropdown, for example, News.

  6. Select Save to commit the layout changes.

  7. In your asset type section, select inline_edit from the screen drop down, and select Save.

  8. Select the custom edit layout you want to use for this asset type, and select Save.

Convert component templates

For some Matrix sites, adapting your component templates is the most significant part of a conversion to fully support inline editing with your template.

There are two broad approaches for how to handle the editing experience for your component templates.

For each component template, choose one of the following approaches:

  1. Edit components through the content screen only.

  2. Edit components through inline edit with a preview.

Edit components from the content screen only

Choose this option if you want the minimum effort to customize and maintain your component template, or you do not need your component template to work in inline edit mode.

This option will display a message in inline edit mode in place of the component, advising the user to switch to the content screen to edit the component. This is consistent with other components (code, nested content) that are not editable in inline edit mode.

To configure a component to be editable from the content screen only:

  1. Add the following code to your Component’s custom edit layout, to conditionally display a message in inline edit mode only:

    %begin_globals_server_request_uri^contains:inline_edit=true% (1)
	<div class="sq-edit-bodycopy-section-wrapper sq-content-type-disallowed component-wrapper">
		<span>This component is not supported when editing inline. Edit this content through the content screen.</span>
	</div>
%else_%
	YOUR CONTENT LAYOUT GOES HERE (2)
%end_%
    1 The “begin” conditional keyword checks the URL to determine whether the user is editing via the inline edit screen.
    2 Add the code for editing your component in the content screen only.

  2. Test the editing experience in the Content screen as well as inline edit:

    1. In the Content screen you should see your original customized edit layout.

    2. In the inline edit screen you should see the standard message that the component is not supported here.

Edit components through inline edit with a preview

Choose this option if you want components to be editable in inline edit without content editors having to switch to the content screen to update components.

This option will allow the structured content of your component to be edited by displaying the metadata form fields. It will also show a rendered preview of the saved component. The component preview will update when the editor saves the page.

To configure a component to be editable in inline edit with a preview:

  1. Access the Details screen of the component template.

  2. Ensure there is a metadata schema set on the component template.

  3. Ensure there is a custom edit layout set on the component template.

  4. Change the Enable inline edit interface in admin mode option to On so that the custom edit layout will work in both inline edit and the Content screen.

  5. Edit the custom edit layout.

  6. Use the View custom edit layout keywords to add the appropriate editing keywords to allow editors to input fields.
    The simplest version if you are only using metadata fields is %metadata-F_metadata_values%. This keyword prints a form containing all metadata values applied.
    Another approach is to use individual metadata keywords, and provide your own layout for editing the fields For example: %metadata-F_1234%.

  7. If you want to customize the the metadata fields styling, you can add custom CSS here with a HTML link tag.

  8. Underneath the metadata section, use the following keyword to render the component as it would appear on the frontend of the site. The conditional keyword will make sure that this only renders in inline edit, instead of the content screen.

    %begin_globals_server_request_uri^contains:inline_edit=true%
    %asset_assetid^as_asset:asset_contents%
%end_%

  9. Test the editing experience in the Content screen as well as inline edit:

    1. In inline edit, you should be able to edit the fields of the component template, save your changes, and see the change rendered.

    2. In the content screen, you should just see the form fields and be able to save content.

Update your original site template

If you set up a test copy of your site, once you have updated your duplicated template and are happy with the changes, you can recreate those changes on your production template.

Depending on the size and scope of your sites, choose one of the following approaches:

  • Keep the new template

  • Update the original template

Keep the new template

For a smaller site, it may be preferable to keep your new duplicated version of the template, and apply it to your existing website. This approach is particularly useful if your component templates have not been used on many pages.

  1. Apply designs, paint layouts, custom edit layouts, metadata schemas, etc to the existing site.

  2. Check the usage screen of each component and update the content pages to use the new component templates.

Update the original template

For a larger site, it may be preferable to repeat the changes you made on your duplicate site on the original template assets now that you have tested them. This approach is particularly useful your component templates are used across many web pages and would take a long time to replace.

  1. For each step in the above tutorial applied to the duplicate template, recreate your changes on the original template assets

  2. Make sure to update designs, paint layouts, custom edit layouts, metadata schemas.

  3. Update each component, ensuring to update its custom edit layout.

    Unless you made new changes to the metadata schemas and paint layouts of your component templates, you shouldn’t need to update these.