-
Notifications
You must be signed in to change notification settings - Fork 158
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[TT-11434, DX-1154] Update the theme upgrade guide for the EDP. (#4208)
* [TT-11434] Update the theme upgrade guide for the EDP. --------- Co-authored-by: Sergei Lega <[email protected]>
- Loading branch information
Showing
2 changed files
with
92 additions
and
61 deletions.
There are no files selected for viewing
Binary file added
BIN
+131 KB
...ts/img/dashboard/portal-management/enterprise-portal/fork-portal-theme-repo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,71 +11,102 @@ weight: 1 | |
| --- | ||
|
|
||
| ## Overview | ||
| The Tyk Enterprise Developer Portal doesn't automatically update the default theme with every new release of the product because in that case the automatic update may lead to a loss of the customers-made customizations. | ||
| Therefore, customers need to upgrade their themes manually to get the recent updates and fixes. Follow these steps to upgrade a theme for the portal: | ||
| 1. Download a new default theme. | ||
| 2. Change its name. | ||
| 3. Upload it to the portal. | ||
| 4. *(Optionally)* Apply existing customization to the new theme. | ||
|
|
||
| ## Download a new default theme | ||
| - Download the new **default** theme for your portal version from the portal-themes repo in [GitHub](https://github.com/TykTechnologies/portal-themes). For example, v1.8.1 theme can be downloaded directly from [here](https://raw.githubusercontent.com/TykTechnologies/portal-themes/main/v1.8.1/default.zip "https://raw.githubusercontent.com/TykTechnologies/portal-themes/main/v1.8.1/default.zip"). | ||
| - Change the name of the theme to preview the new default theme without overwriting any existing one. You can use any that is other than `default` or any name of your existing theme. An already customized v1.8.1 theme `default-customized.zip` that has a name `default_v1_8_1` can be downloaded directly from [here](https://raw.githubusercontent.com/TykTechnologies/portal-themes/main/v1.8.1/default-customized.zip "https://raw.githubusercontent.com/TykTechnologies/portal-themes/main/v1.8.1/default-customized.zip"). | ||
| - To change the theme's name by yourself, follow the [instructions]({{< ref "/product-stack/tyk-enterprise-developer-portal/upgrading/theme-upgrades#change-the-name-of-the-theme" >}}) below on this page. You can skip it if you are going to use the `default-customized.zip` file from the previous step. | ||
|
|
||
| ## Change the name of the theme | ||
| - Unzip the theme file with a graphical file manager or by running a command like this: | ||
| ```shell | ||
| unzip -d default default.zip | ||
|
|
||
| The Tyk Enterprise Developer Portal does not automatically update the default theme with each new release of the product, because doing so could result in the loss of customisations made by customers. | ||
| Therefore, customers are required to manually upgrade their themes to access the latest updates and fixes. We recommend using GitFlow for the latest theme updates. | ||
| Alternatively, you can download the theme package from the **Releases** section of the [portal-default-theme](https://github.com/TykTechnologies/portal-default-theme) repository. | ||
| However, we advise against this method, as it requires you to merge your customised theme with the downloaded one, which is much simpler to accomplish via GitFlow. | ||
| Follow the guide below to obtain the latest version of the portal theme and merge it with your customised version. | ||
|
|
||
| ## Updating Tyk Enterprise Developer Portal themes via gitflow | ||
|
|
||
|
|
||
| The default theme for the Tyk Enterprise Developer Portal is located in the [portal-default-theme](https://github.com/TykTechnologies/portal-default-theme) repository. | ||
| The `main` branch contains code corresponding to the latest stable release. If you wish to check out a specific release (e.g., v1.8.3), you can use tags: | ||
|
|
||
| ```console | ||
| git checkout tags/1.8.3 -b my-custom-theme branch | ||
| ``` | ||
| - The above command will create a directory named `default` that contains the theme files including the `theme.json` file. | ||
| - Navigate to the `default` directory and edit the `theme.json` file which defines the name and author of the theme as well as which templates are available in the theme. More information about the theme structure can be found in the [theme customization documentation]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/customise-enterprise-portal/full-customisation/file-structure-concepts" >}}), | ||
| - The `theme.json` file looks the following json file: | ||
| ```json | ||
| { | ||
| "name": "default", | ||
| "version": "1.8.1", | ||
| "author": "Tyk Technologies Ltd. <[email protected]>", | ||
| "templates": [ | ||
| { | ||
| "name": "Flip Flop", | ||
| "template": "flip_flop", | ||
| "layout": "portal_layout" | ||
| }, | ||
| { | ||
| "name": "Home", | ||
| "template": "home", | ||
| "layout": "portal_layout" | ||
| }, | ||
| { | ||
| "name": "Catalogue", | ||
| "template": "catalogue", | ||
| "layout": "portal_layout" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| - To change the name of the theme, edit the `name` field to anything other than `default` and save your changes. | ||
| - Run the following commands to create a new theme archive that will contain your changes inside the **default** directory: | ||
| ```shell | ||
| rm default.zip $ zip -r9 default.zip * | ||
|
|
||
| To organise local development in a way that facilitates seamless theme updates using git merge, follow the steps below: | ||
| 1. Fork the `portal-default-theme` repo in [github](https://github.com/TykTechnologies/portal-default-theme). | ||
| {{< img src="/img/dashboard/portal-management/enterprise-portal/fork-portal-theme-repo.png" alt="Fork the portal-theme repo" >}} | ||
|
|
||
| 2. Clone the forked repository: | ||
| ```console | ||
| git clone https://github.com/my-github-profile/portal-default-theme && cd ./portal-default-theme | ||
| ``` | ||
| - The above command will create a **default.zip** file inside the **default** directory with your changes incorporated. | ||
|
|
||
| ## Upload the theme to the portal | ||
| To upload the new theme to the portal, use the `default.zip` theme that is created in the [previous step]({{< ref "/product-stack/tyk-enterprise-developer-portal/upgrading/theme-upgrades#change-the-name-of-the-theme" >}}) to the portal via the portal's [Admin dashboard]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/customise-enterprise-portal/full-customisation/file-structure-concepts#part-1-create-a-new-theme" >}}) or the [admin API]({{< ref "/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api" >}}), and [activate]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/customise-enterprise-portal/full-customisation/file-structure-concepts#part-3-activate-a-theme" >}}) it. | ||
| 3. If you have an existing repository, check if you already have the `portal-default-theme` repo among your remotes before adding it. Execute the following command to check: | ||
| ```console | ||
| git remote -v | grep 'TykTechnologies/portal-default-theme' | ||
| ``` | ||
|
|
||
|  | ||
| Skip the next step if you see the following: | ||
| ```console | ||
| # portal-default-theme https://github.com/TykTechnologies/portal-default-theme (fetch) | ||
| # portal-default-theme https://github.com/TykTechnologies/portal-default-theme (push) | ||
| ``` | ||
|
|
||
| If the output of the above command is empty, proceed to step 5 to add the `portal-default-theme`. | ||
|
|
||
| 4. Add the `portal-default-theme` to the remotes by executing the following command: | ||
| ```console | ||
| git remote add portal-default-theme https://github.com/TykTechnologies/portal-default-theme | ||
| ``` | ||
|
|
||
| 5. Create a new local branch that tracks the remote `main` branch. That branch will mirror the latest changes from the `portal-default-theme` main. You will be using it to import the latest changes from the `portal-default-theme` to your custom theme: | ||
| ```console | ||
| git fetch portal-default-theme main:portal-default-theme-main | ||
| ``` | ||
|
|
||
| If you have an existing local branch that tracks the `main` branch in the `portal-default-theme` repo, you can just pull the latest updates: | ||
| ```console | ||
| git checkout portal-default-theme-main | ||
| git pull portal-default-theme main | ||
| ``` | ||
|
|
||
| 6. To start customising the theme, create a local develop branch from the `portal-default-theme-main`: | ||
| ```console | ||
| git checkout portal-default-theme-main | ||
| git checkout -b dev-branch | ||
| ``` | ||
|
|
||
| 7. Once the required customisations are completed, commit the changes to the `dev-branch`. | ||
|
|
||
| 8. Merge the latest updates from the `portal-default-theme` into the `dev-branch`. Please remember to always pull the latest changes from the `portal-default-theme-main` branch before merging: | ||
| - Checkout to the portal-default-theme-main and fetch the latest changes. | ||
| ```console | ||
| git checkout portal-default-theme-main | ||
| git pull portal-default-theme main | ||
| ``` | ||
| - Checkout the dev-branch and merge the changes from the portal-default-theme-main to retrieve the latest changes from the portal-default-theme repo with the customised theme. | ||
| ```console | ||
| git checkout dev-branch | ||
| git merge portal-default-theme-main | ||
| ``` | ||
|
|
||
| Finally, address merge conflicts and commit changes. | ||
|
|
||
| {{< note success >}} | ||
| **You have successfully updated your custom theme** | ||
|
|
||
| Now you can repeat the above described process when upgrading the portal version to make sure you have incorporated the latest theme changes to your customised theme. | ||
|
|
||
| {{<note sucess>}} | ||
| **Applying existing customizations** | ||
| {{< /note >}} | ||
|
|
||
| If you have made customizations to your existing theme and want to bring those changes to the new theme, please follow the instructions in the [copy customizations from existing theme to the new theme]({{< ref "/product-stack/tyk-enterprise-developer-portal/upgrading/theme-upgrades#copy-customizations-from-existing-theme-to-the-new-theme" >}}) section below. | ||
| {{</note>}} | ||
| ## Upload the theme to the portal | ||
| Once you have merged your local changes with the latest changes from the `portal-default-theme` repo, you need to create a zip archive with the customised theme and upload it to the portal. | ||
| 1. Create a zip archive with the customised theme. Make sure you zip the content of the `src` folder and not the folder itself. To create a zip archive with the customised theme execute the following: | ||
| - cd to the `src` directory to make sure you: | ||
| ```console | ||
| cd ./src | ||
| ``` | ||
| - zip the content of the `src` directory: | ||
| ```console | ||
| zip -r9 default.zip | ||
| ``` | ||
|
|
||
| ## Copy customizations from existing theme to the new theme | ||
| If you want to transfer customization of your existing theme to the new theme, follow these steps: | ||
| - Compare the changes between your old theme and the new theme (latest is v1.8.1) and copy your customizations to the new theme directory accordingly. | ||
| - Then follow the previous steps to: | ||
| - [Change the name]({{< ref "/product-stack/tyk-enterprise-developer-portal/upgrading/theme-upgrades#change-the-name-of-the-theme" >}}) of the theme. | ||
| - [Upload it to the portal]({{< ref "/product-stack/tyk-enterprise-developer-portal/upgrading/theme-upgrades#upload-the-theme-to-the-portal" >}}) and then activate it. | ||
| 2. Upload the theme package that is created in the [previous step]({{< ref "/product-stack/tyk-enterprise-developer-portal/upgrading/theme-upgrades#change-the-name-of-the-theme" >}}) to the portal. You can use the portal's [Admin dashboard]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/customise-enterprise-portal/full-customisation/file-structure-concepts#part-1-create-a-new-theme" >}}) or the [admin API]({{< ref "/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api" >}}) to do it. | ||
|  | ||
| 3. Finally, you need to [activate]({{< ref "/tyk-stack/tyk-developer-portal/enterprise-developer-portal/customise-enterprise-portal/full-customisation/file-structure-concepts#part-3-activate-a-theme" >}}) the theme so that it will be applied to the portal. | ||