Introduction

The Migrate 5.x Themes Utility can be used as a starting point for upgrading a custom theme from 5.x to 6.x/7.x. It uses the layout export from 5.x along with the original file-based implementation to merge customizations into a working 6.x/7.x theme export.  

Its output is a full theme export suitable for importing into a 6.x+ site and a SQL schema patch that can be used to migrate existing theme configuration and layout data in an upgraded database.

High-level features include:

  • Importing of the theme title, description, and preview image.
  • Importing of default page layouts
  • Embedding of image files within the theme/images/ folder
  • Embedding of CSS files referenced in theme headers:
    • Imported CSS files are merged into the top-level CSS file.
    • Image references are updated to reference the embedded versions of the files.
  • Embedding of JS files referenced in theme headers.
  • Importing of theme headers.
  • Importing of theme configuration data (theme width, height, CSS overrides, etc.).
  • Support for defining which types of files should override base theme files.

Caution

This tool does not produce an output theme that will look exactly as the 5.x version. It is a starting point for a complete migration. After the migration tool has been used, a theme developer will need to:

  1. Re-implement the header/footer. Headers and footers fragments in 5.x were not full widgets, and cannot be automatically migrated.
  2. Review migrated CSS. Because the CSS is applied against updated factory default implementations of widgets, the visual result may not be the same as in 5.6.
  3. Implement markup translations. If the source theme used markup translations in 5.x, those translations will need to be applied directly to the applicable widgets by making a theme-specific version of the widget in Widget Studio.
  4. Migrate/upgrade custom widgets. Custom widgets will need to be migrated separately. Scripted widgets did not exist in 5.6.
  5. Handle configuration options no longer supported. Any options exposed in the 5.6 theme via its theme.config file that are not supported in 6.x/7.x are not migrated. Often, additional properties were associated to header/footer configuration. Any properties not supported will need to be reviewed and re-implemented in the 6.x/7.x theme via widgets or plugins.

Installation

  1. Download the utility.
  2. Unblock the ZIP file by right-clicking the file, selecting properties, and clicking the "Unblock" button.
  3. Extract the contents of the ZIP into a new folder.
  4. Run "UpgradeTheme.exe".

Using the Migration Tool

  • Browse to find the Base Theme Export file. This can be generated from a 6.x/7.x site by going to Control Panel > Administration > Site Administration > Site Content > Manage Themes. Be sure to select the base theme and correct theme type before exporting. For example, if the custom site theme was based on the Fiji theme in 5.x, export the 6.x/7.x version of the Fiji site theme.
  • Browse to find the Layout Export file. This can be generated from a 5.x site by going to Control Panel > Administration > Site Administration > Site Content > Import/Export Layouts. It is not necessary to limit the export to only a single theme type; the tool will extract the layouts that match the base theme export file during migration.
  • Browse to find the Theme.config file. This is the theme.config file for the custom theme. For example, when migrating a custom site theme called "newtheme", the theme.config file should exist within the 5.x site at themes/newtheme/theme.config. The theme.config file that is selected should exist within a working folder structure for the theme - its location will be used to resolve relative links in CSS and theme configuration data.
  • Browse to select the name of the Theme Export File. This is where the resulting theme export file will be saved when migration is complete. This output file is suitable for importing into a 6.x/7.x site.
  • Browse to select the name of the Theme Schema Patch file. This is where the resulting theme migration script will be saved when migration is complete. This output file is suitable for execution against a 6.x/7.x database.
  • Define the Theme ID. The theme ID is used to uniquely identify this theme in the site. If this is a single theme (there is no associated group/blog/site theme), click "Generate" to create a new identifier. If this theme is related to another theme (for example, the group theme related to a site theme), enter the ID of the parent theme here. Note that themes are unique in Evolution 6.x/7.x by ThemeID+ThemeType. A site cannot have multiple site themes with the same Theme ID (or group or blog themes with the same ID).
  • Specify Overwriting Options. By default, only image files will be overwritten when migrating the theme. To enable overwriting CSS or JavaScript files as well, adjust the overwriting settings.
  • Click Migrate to being the migration process.

  • The migration is now complete. The output files have been written and can be used against an Evolution 6.x/7.x site. The theme export can be imported into the 6.x/7.x site by going to Control Panel > Administration > Site Administration > Site Content > Manage Themes. The SQL patch can be run against the upgraded database. After the theme is installed and the SQL patch is executed, the theme can be selected again on the appropriate Theme Configuration pages within the Control Panel.
  • The notes regarding what was migrated and what wasn't are shown. These notes should be reviewed to identify what wasn't imported. Specifically:
    • No headers or footers are imported. They will remain as they were in the selected base theme and will need to be manually updated after the theme is imported.
    • No widget markup translations are imported. Markup changes should be applied directly to the widgets versioned for this theme (if necessary).
    • Other import issues (missing files, invalid files, etc.) will be noted within the migration notes.
  • To migrate another theme, click "Reset."  Otherwise, click "Cancel" to close the migration tool.