Automatically Migrating Projects to New Theme Versions
ThemeBuilder comes with a project migration feature that allows you to automatically move your custom styles to a new project that uses a later version of the Telerik and Kendo UI Themes. This enables you to apply your custom styles to the later version of the Telerik and Kendo UI components.
Understanding the Telerik and Kendo UI Versions
Each custom theme that you create in ThemeBuilder uses a specific version of the Telerik and Kendo UI themes as a base for your customizations. Each version of the Telerik and Kendo UI themes supports a specific version of the Telerik and Kendo UI components. This dependency means that your custom theme supports only the component versions that are supported by the Telerik and Kendo UI theme used as a base theme in your project. For example, if your ThemeBuilder project references version 6.0.3 of the Telerik and Kendo Default theme, the compatible Telerik and Kendo UI components are from the R1 2023 release.
Consider the following specifics related to versioning and matching theme versions with UI component versions:
- The Telerik and Kendo UI components support only the Telerik and Kendo UI themes from the same release (the components and the themes are released on the same date).
- The Telerik and Kendo UI components and the Telerik and Kendo UI themes are distributed as different packages and have different versioning.
-
ThemeBuilder displays a badge with the version of the base theme for each ThemeBuilder project. To find the compatible versions of the Telerik and Kendo UI components:
- From the toolbar, select the project menu dropdown.
-
Select the Telerik and Kendo UI Theme Version button.
To apply your custom ThemeBuilder theme to a version of the UI components from a later release, you must migrate your project to target a base theme from the same release as the target UI components version.
Migrating Your Project
To migrate the customizations from a project that uses a previous version of the Telerik and Kendo UI themes:
Open the project that you want to migrate.
-
Open the Migrate dialog:
From the toolbar, select the project menu dropdown.
-
Select A New Version is Available.
-
Choose the target theme version from the drop-down list.
Click Migrate to start the migration process.
-
In the MIGRATION COMPLETED dialog, click Reload to continue.
If the migration process is successful, a backup project with your original styles is created automatically for you. However, this project will not contain the project's version history if any.
If the migration fails, no changes are applied to your original project and you may continue using it as is.
Checking the Migration Status
The migration status dialog appears when the migration process is completed. You can also check the status by opening the dialog manually: select Last Migration Status from the toolbar.
Migration Successful
When the migration process is successful, the migration status dialog contains the following information:
-
DELETED PARTS—A list with all component parts that have been removed from the rendering of the Telerik and Kendo UI components.
If a part is deleted, the styles cannot be transferred automatically and will be lost in the migrated project. To preserve the desired styling, apply the styles manually to the appropriate component part. You can inspect the removed styles by clicking the Backup Location link in the table.
RENAMED VARIABLES—A list with all variables that have been renamed during the migration process.
Migration Failed
If the migration process is not successful, the migration status dialog contains a two-step wizard allowing you to contact the support team and resolve the issue.
- Share your project with us—This step is crucial for resolving migration issues faster. Clicking the button automatically shares the project with the support team and allows them to debug and resolve the issues.
- Send us a ticket—Once the project is shared with the ThemeBuilder support team, you can contact the team through a support ticket where you can provide additional context and communicate with the team.
Using the Backup Project
If the migration process is successful, the source project is modified and becomes compatible with the later Telerik and Kendo UI theme version. To guarantee that you do not lose any important styling information, ThemeBuilder automatically creates a backup project with the name YOUR_PROJECT_NAME_CURRENT_VERSION_Backup. The backup contains a snapshot of your original project at the moment of the migration. Later, you can use the project for reference. Once you no longer need this project, you can delete it from the project menu.
Automatic Migration Blockers
Occasionally, the developers of the Telerik and Kendo UI themes introduce breaking changes that aim at adding new features and improving the rendering of the UI components. This allows the developers to keep the Telerik and Kendo UI themes in sync with the latest trends.
Breaking changes, however, can block the untroubled migration described in the previous section. When this happens, you must perform some steps manually to ensure that all your custom styles are transferred correctly.
Such breaking changes include:
- Changes in the rendering of the components.
- Changes in the type of the component parts.
- Added component parts.
Changed Component Rendering
Specific versions of the Telerik and Kendo UI themes may introduce changes in the component rendering. For example, a wrapper in a previous version of the components could be removed in a later version. Such parts are detected by the migration process and are listed in the migration status dialog. In such cases, manual changes are required to preserve the desired component styles.
Changed Component Parts
Specific versions of the Telerik and Kendo UI components can introduce changes in the component parts. For example, a <span> in a previous version could be converted to a Button in a later version. This could lead to a transfer of styles that have not been there in the previous version. In such cases, manual changes are required to preserve the desired component styles.
Added Component Parts
Later versions of the Telerik and Kendo UI components may add new component parts. For example, a text part could be added to the Button component in a later version. This could lead to a mismatch in the styles that you must handle manually.