Changes to Template Customization
In July, we released an update that introduced changes to the way in which template customization is now supported by Scroll HTML Exporter (currently for the beta version only). This relates to the user-added customizations that can be made via CSS and JavaScript within the export template.
What has changed?
The new update has introduced support for a CSS Grid Layout approach for supporting template customization in Scroll HTML Exporter.
This change will potentially have breaking changes for any custom export template that uses the template customization setting. It will also change the look and feel of the bundled Help Center template.
Who is affected by the changes?
The following Scroll HTML Exporter users could be affected by this change:
Any Scroll HTML Exporter for Confluence Cloud user that has;
created a custom export template prior to July 2024
uploaded a custom export template that was created prior to July 2024
Any Scroll HTML Exporter for Confluence Data Center v4 BETA user that has;
used the v4 beta version of Scroll HTML Exporter
created a custom export template prior to July 2024 with the beta version
uploaded a custom export template created prior to July 2024 with the beta or cloud version
Any Scroll HTML Exporter for Confluence Data Center user that has;
uploaded a custom export template created prior to July 2024 with the beta or cloud version
Why have changes been made?
We have switched to a new CSS Grid Layout because it is a layout system that makes web layout customization easier. Specifically, it is a CSS module designed for handling complex layouts efficiently, and helps to solve layout and formatting issues that traditional CSS layout techniques (eg. tables, floats, positioning, and inline-block), couldn’t fully solve. The change will make it easier for users to customize their own custom export templates.
What impact will the changes have?
Impact for Everyone
The look and feel of the bundled Help Center template will change. The most notable change will be to the colour of the header section (this can be changed back via custom CSS if you require it).
.png?inst-v=16de30dd-616d-42ba-bc21-a451e841d039)
Before
After
Additional Impact for those using Template Customization
Any custom export template, created before July 2024 and which has the template customization setting enabled, will be affected by this update. The affected template(s) will require changes to the template customization (ie. custom.css / custom.js file) file to support the new CSS approach.
As a result of the change, it is likely that the majority of CSS selectors that were used before will need to be adapted. Please see our template customization documentation for an overview of different examples that include the new supported customization approach.
In the short-term, we will be providing a deprecation period whereby custom export templates that are using the ‘old’ template customization styling will still work as expected. The deprecation period will last 1-year, and during this time we encourage users to update the customization in their existing/affected templates. After the deprecation period, custom export templates that still use the ‘old’ will not be officially supported.
How will I know if my export templates are affected by this change?
A notification will appear to users when selecting an affected export template from the export dialogue. Additionally, when editing an affected template a notification will display that requires the users to confirm that changes are required for their template, and they confirm the update to use the new template structure.
Any custom template selected from the export dialogue that:
was created before the update
has the Template customization setting enabled with customized files present
will display a warning indicating that action is required to update the customizations, and the template will need to be migrated to the new approach
Any custom template selected from the export dialogue that:
was created before the update
does not have the Template customization setting enabled with customized files present
will receive a notification about the change and the template will need to be migrated to the new template and customization approach
Export Dialogue Notification
Scroll HTML Exporter v4.2 or newer:
Scroll HTML Exporter v4.1.2 or older:
Template Editor Notification
How do I migrate my template(s)?
From the template list you can edit your export templates
After selecting your affected template;
Templates with customization present → Users will be required to manually update the customization files (ie.
custom.css/custom.js), reupload the amended files to the export template, and then save the templateTemplates without customization present → Users will be required to make any change in the template, and then save the template
After successfully saving the template, users will have migrated their 'old' template to the new template approach
When will the deprecation period be?
The deprecation period for affected export templates will run up until the 1st July 2025. Before this date, ‘old’ template customizations present in affected export templates will still work as expected.
However, once the deprecation period ends, only templates using the new customization approach will be supported. This means, after the 1st July 2025, all export templates which haven’t been migrated will be "auto-migrated" to the new template approach.
Auto-migrated templates used for export may result in unexpected export output because any custom CSS / JavaScript associated with the template will be subject to change. After the auto-migration, the corresponding CSS / JavaScript files would need to be updated accordingly.