feat: code.ftl

[nmathew98]

objective we need to customise the default theme used by Keycloak to apply our own theme. These themes are developed using React with keycloakify. React is one of many frontend frameworks used to develop user interfaces for web applications.

out of the box, Keycloak themes are mainly developed with FreeMarker which is another tool to generate HTML and CSS for web applications. Developing with FreeMarker is not suitable for our needs as it is hard to create rich interactive experiences with it. It's not impossible but any form of testing would require discovery as opposed to using React which is widely known.

at a high level, each Keycloak page is made of two key components, the template and everything else. The template provides the layout for the page and the body is the actual content of the page.

we will be customising this particular page: code.ftl.

prerequisites doing development requires a couple of things first:

1. Docker
   • Docker is a tool used to containerize an environment. When we do development work, there are usually additional applications and packages that we need installed before we can get started. In the case of this task, we would require NodeJS, git, maven which is a build tool for Java. for this reason, we do development work inside a container, a container puts a fence around all these tools that we need and allows us all to use the same versions of the same tools and operating system. the result of this is that we reduce errors and helps us get started on the work we need to actually do quicker instead of spending our time tracking down errors related to a tool we use. doing development work inside a container also allows us to get started quicker as most of the setup process is automated. Commonly containers used to do development work is known as devcontainers.
2. VSCode
   • Currently the most popular way to use devcontainers for development is through VSCode. VSCode is a text editor which offers a rich set of extensions allowing for a variety of different languages and tools. These extensions will also be useful as we are developing inside containers (search for the extension):
     • ms-vscode-remote.remote-containers
       • 
     • ms-azuretools.vscode-docker
       • 
3. Signed commits
   • We require commits to be signed. Setting this up requires you to update your git configuration. The following guide may be useful: https://medium.com/@ryanmillerc/use-gpg-signing-keys-with-git-on-windows-10-github-4acbced49f68. To configure git to sign all commits regardless of project by default, read this and run the following command: git config --global commit.gpgsign true in powershell. You will likely also have to configure git to specify your name and email, both of which can be done using the following commands: git config --global user.name <your name> and git config --global user.email <email> (also in powershell). the email used should be the same email you used with your Github account. After configuring your credentials on windows, when you open up the devcontainer, you also need to update your gitconfig within to use specify the name, email signing key and to sign commits.

Task

1. clone this repository using git clone https://github.com/skulpturenz/shared-resources.git
2. we need to update src/keycloak-theme/login/KcPage.tsx to use the custom page we develop. to do this, we need update the switch statement to return the Code component located at src/keycloak-theme/login/pages/Code.tsx.
3. In src/keycloak-theme/login/pages/Code.tsx is the code which displays the code.ftl page. we need to customise the body:
   • at a high level, we need the typography and one time code input to be updated, see src/components/ui/typography, src/components/ui/input-otp.tsx for the components required to do this. an example of using the one time code input component can be found in /Users/naveenmathew/Developer/skulpture/shared-resources/authnz-theme/src/keycloak-theme/login/pages/LoginOtp.tsx, L73-L84.

Local testing

1. we can test our changes using Storybook. within the devcontainer, we can run storybook using pnpm storybook

related resources:

• https://docs.docker.com/desktop/install/windows-install/
• https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials#_sharing-gpg-keys
• https://gist.github.com/xavierfoucrier/c156027fcc6ae23bcee1204199f177da
• https://react.dev/learn
• https://tailwindcss.com/docs/installation
• https://storybook.js.org/docs/get-started/why-storybook
• https://docs.keycloakify.dev
• https://www.typescriptlang.org/docs/handbook/intro.html
• https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests

[nmathew98]

@mwabe592 hey ben, here's ur first task haha. its a bit involved and the guide is not thorough enough for someone completely new but have a read of the docs and lmk if u get stuck