Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Theme upgrade language edit #94

Merged
merged 1 commit into from
Jun 22, 2023
Merged

Theme upgrade language edit #94

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions site/docs/v1/tech/installation-guide/_theme-upgrade.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
=== Templates

When new functionality is introduced to link:/docs/v1/tech/core-concepts/integration-points#hosted-login-pages[the hosted login pages], new theme templates are occasionally added. They are added to the default theme by the upgrade process, but if you've customized your theme to fit your brand, you'll need to modify the theme to have the new template.
When new functionality is introduced to link:/docs/v1/tech/core-concepts/integration-points#hosted-login-pages[the hosted login pages], new theme templates are occasionally added. They are added to the default theme by the upgrade process but if you've customized your theme to fit your brand, you'll need to modify the theme to have the new template.

In the version release notes, any new templates and macros are documented. If there are changes, you'll want to take a closer look at the themes post upgrade.

As part of your upgrade testing, open the administrative user interface and navigate to [breadcrumb]#Customizations > Themes#.

If any themes are missing templates, they will show as "Upgrade Required". Port the new theme files over to your custom theme, modify them as needed, and save the theme.

In some cases, existing templates are modified. If you have customized your theme, you'll need to compare the new template to your existing versions base theme, and port over any changes to your customized theme. The easiest way to do this is to use a diff tool to compare the two sets of files. Here is a suggested process, before you upgrade:
In some cases, existing templates are modified. If you have customized your theme, you'll need to compare the new template to your existing version's base theme and port over any changes to your customized theme. The easiest way to do this is to use a diff tool to compare the two sets of files. Here is a suggested process to follow before you upgrade:

1. Download the default theme from your existing version of FusionAuth.
2. Download the default theme from the new version of FusionAuth.
Expand All @@ -19,26 +19,30 @@ You can use the link:https://github.com/FusionAuth/fusionauth-theme-helper[Theme

==== Using the Theme Helper to Upgrade Themes

Clone the link:https://github.com/FusionAuth/fusionauth-theme-helper[Theme Helper] repo and follow the install instructions in the `README.md` file. Now, you'll need to download the base themes from your existing version of FusionAuth and the new version of FusionAuth to compare.
Clone the link:https://github.com/FusionAuth/fusionauth-theme-helper[Theme Helper] repo and follow the install instructions in the `README.md` file.

To get the existing version's theme files, create a `.env` file from the `.env.sample` file. Create an link:/docs/v1/tech/apis/authentication#managing-api-keys[API key] with read permissions for Themes in the FusionAuth administrative user interface. Add the API key to the `.env` file. Navigate to [breadcrumb]#Customizations -> Themes# and copy the ID of the default "FusionAuth" theme. Use this value to update the `THEME_ID` key in the .env file.
Download the base themes from your existing version of FusionAuth and the new version of FusionAuth to compare.

To get the existing version's theme files, create a `.env` file from the `.env.sample` file. Create an link:/docs/v1/tech/apis/authentication#managing-api-keys[API key] with read permissions for Themes in the FusionAuth administrative user interface. Add the API key to the `.env` file. Navigate to [breadcrumb]#Customizations -> Themes# and copy the Id of the default "FusionAuth" theme. Use this value to update the `THEME_ID` key in the `.env` file.

In the `.env` file, set the `FUSIONAUTH_URL` to the URL of your existing FusionAuth instance. Finally, update the `TMP_DIR` to a directory on your local machine where you want the existing theme files to be downloaded, such as `current-theme`.

Now you can run the `download.sh` script to download the existing theme files to the `TMP_DIR` directory.

Once this has completed downloading, you'll need to get the base theme files from the new version of FusionAuth. The easiest way to do this before upgrading your production version is to install the new version of FusionAuth on your local machine or a VM using Docker. Instructions for installing FusionAuth using Docker can be found in the link:/docs/v1/tech/installation-guide/docker#docker-compose[FusionAuth Docker Installation Guide].
Once the download is complete, you'll need to get the base theme files from the new version of FusionAuth. The easiest way to do this before upgrading your production version is to install the new version of FusionAuth on your local machine or a VM using Docker. Instructions for installing FusionAuth using Docker can be found in the link:/docs/v1/tech/installation-guide/docker#docker-compose[FusionAuth Docker Installation Guide].

Once you've got the new version of FusionAuth running, you can update the Theme Helper `.env` file in the Theme Helper repo to point to the new version of FusionAuth. You'll need to update the `FUSIONAUTH_URL` to `\http://localhost:9011`.

Once you've got the new version of FusionAuth running, you can update the Theme Helper `.env` file in the Theme Helper repo to point to the new version of FusionAuth. You'll need to update the `FUSIONAUTH_URL` to `\http://localhost:9011`. You'll also need to login to the new FusionAuth to create an API key, and copy the default theme ID into `THEME_ID` variable as you did for the existing version. Finally, update the `TMP_DIR` to a directory on your local machine where you want the new theme files to be downloaded, such as `new-theme`. Make sure it is a different directory than the one you used for the existing theme files.
Log in to the new version of FusionAuth to create an API key and copy the default theme Id into the `THEME_ID` variable as you did for the existing version. Finally, update the `TMP_DIR` to a directory on your local machine where you want the new theme files to be downloaded, such as `new-theme`. Make sure it is a different directory than the one you used for the existing theme files.

Now you can run the `download.sh` script again to download the new theme files to the `TMP_DIR` directory.

Once you have both sets of theme files downloaded, you can run the `diff-themes.sh` script to compare the two sets of files. The script takes 2 arguments, the first is the path to the existing theme files, and the second is the path to the new theme files. For example:
Once you have both sets of theme files downloaded, you can run the `diff-themes.sh` script to compare the two sets of files. The script takes two arguments: the path to the existing theme files and the path to the new theme files. For example:

```sh
./diff-themes.sh current-theme new-theme
```
The script will output a list of files that are different between the two sets of theme files, along with the differences. You can use this list to update your customized theme files. While you can directly use this output to find the changes, it might be useful to use a visual diff tool of your choice to help you make the changes, using the file list as a guide.
The script will output a list of files that show differences between the two sets of theme files and the differences. You can use this list to update your customized theme files. While you can directly use this output to find the changes, it might be useful to use a visual diff tool to help you make the changes, using the file list as a guide.

=== Messages

Expand All @@ -52,7 +56,7 @@ Missing required keys. See text area below for default English translations. To

FusionAuth warns you about missing required keys in order to avoid an inadvertent bad user experience. The default display for keys with no valid values in theme [field]#Messages# is the key text, such as `[ExternalAuthenticationException]LinkedInToken`, which can be confusing for end users.

During an upgrade, you can find these keys by testing the upgrade on a development instance or comparing releases in the link:https://github.com/FusionAuth/fusionauth-localization/[fusionauth-localization] repo. You can safely add these new key values to your theme prior to an upgrade. Any unused messages in a theme's `messages` file are silently ignored (unless malformed).
During an upgrade, you can find these keys by testing the upgrade on a development instance or comparing releases in the link:https://github.com/FusionAuth/fusionauth-localization/[fusionauth-localization repo]. You can safely add these new key values to your theme prior to an upgrade. Any unused messages in a theme's `messages` file are silently ignored (unless malformed).

The extra lines won't do any harm, and will ensure an excellent end user experience if they stumble on new functionality right after an upgrade.
The extra lines won't do any harm and will ensure an excellent end-user experience if a user stumbles on new functionality right after an upgrade.