85 lines
4.3 KiB
Text
85 lines
4.3 KiB
Text
|
[[_migrate_themes]]
|
||
|
|
|
||
|
|
== Migrating Themes
|
||
|
|
|
||
|
|
If you have created any custom themes they must be migrated to the new server. Any changes to the built-in themes might
|
||
|
|
need to be reflected in your custom themes, depending on which aspects you have customized.
|
||
|
|
|
||
|
|
You must copy your custom themes from the old server “themes” directory to the new server “themes” directory.
|
||
|
|
After that you need to review the changes below and consider if the changes need to be applied to your custom theme.
|
||
|
|
|
||
|
|
In summary:
|
||
|
|
|
||
|
|
* If you have customized any of the changed templates listed below you need to compare the template from the base theme
|
||
|
|
to see if there are changes you need to apply.
|
||
|
|
* If you have customized any of the styles and are extending the {project_name} themes you need to review the changes to
|
||
|
|
the styles. If you are extending the base theme you can skip this step.
|
||
|
|
* If you have customized messages you might need to change the key or value or to add additional messages.
|
||
|
|
|
||
|
|
ifeval::[{project_product}==true]
|
||
|
|
Each step is described in more detail below the list of changes.
|
||
|
|
|
||
|
|
include::rhsso/migrate_themes-changes-71.adoc[leveloffset=0]
|
||
|
|
endif::[]
|
||
|
|
|
||
|
|
=== Migrating Templates
|
||
|
|
|
||
|
|
If you have customized any of the templates you need to carefully review the changes that have been made to the templates
|
||
|
|
to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same
|
||
|
|
changes to your customized templates. If you have not customized any of the listed templates you can skip this section.
|
||
|
|
|
||
|
|
A best practice is to use a diff tool to compare the templates to see what changes you might need to make to your
|
||
|
|
customized template. If you have only made minor changes it is simpler to compare the updated template to your
|
||
|
|
customized template. However, if you have made many changes it might be easier to compare the new template to your
|
||
|
|
customized old template, as this will show you what changes you need to make.
|
||
|
|
|
||
|
|
The following screenshot compares the info.ftl template from the Login theme and an example custom theme:
|
||
|
|
|
||
|
|
.Comparison of the updated version of a Login theme template with an example custom Login theme template
|
||
|
|
image:images/theme-migration-meld-info-1.png[]
|
||
|
|
|
||
|
|
From this comparison it is easy to identify that the first change (“Hello world!!”) was a customization, while the
|
||
|
|
second change (“if pageRedirectUri”) is a change to the base theme. By copying the second change to your custom template,
|
||
|
|
you have successfully updated your customized template.
|
||
|
|
|
||
|
|
For the alternative approach the following screenshot compares the info.ftl template from the old installation with
|
||
|
|
the updated info.ftl template from the new installation:
|
||
|
|
|
||
|
|
.Comparison of an example custom Login theme template with the updated version of the Login theme template
|
||
|
|
image:images/theme-migration-meld-info-2.png[]
|
||
|
|
|
||
|
|
From this comparison it is easy to identify what has been changed in the base template. You will then manually have to
|
||
|
|
make the same changes to your modified template. Since this approach is not as simple as the first approach, only use
|
||
|
|
this approach if the first one is not feasible.
|
||
|
|
|
||
|
|
=== Migrating Messages
|
||
|
|
|
||
|
|
If you have added support for another language, you need to apply all the changes listed above. If you have not added
|
||
|
|
support for another language, you might not need to change anything; you only have to make changes if you have changed
|
||
|
|
an affected message in your theme.
|
||
|
|
|
||
|
|
For added values, review the value of the message in the base theme to determine if you need to customize that message.
|
||
|
|
|
||
|
|
For renamed keys, rename the key in your custom theme.
|
||
|
|
|
||
|
|
For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.
|
||
|
|
|
||
|
|
=== Migrating Styles
|
||
|
|
|
||
|
|
If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect
|
||
|
|
changes made to the styles from the built-in themes.
|
||
|
|
|
||
|
|
A best practice is to use a diff tool to compare the changes to stylesheets between the old server installation and the
|
||
|
|
new server installation.
|
||
|
|
|
||
|
|
For example, using the diff command:
|
||
|
|
|
||
|
|
[source,bash,subs=+attributes]
|
||
|
|
----
|
||
|
|
$ diff {project_dirref}_OLD/themes/keycloak/login/resources/css/login.css \
|
||
|
|
{project_dirref}_NEW/themes/keycloak/login/resources/css/login.css
|
||
|
|
----
|
||
|
|
|
||
|
|
Review the changes and determine if they affect your custom styling.
|
||
|
|
|