KEYCLOAK-6519 Documentation for theme resource provider
This commit is contained in:
stianst
Stian Thorgersen
parent
bf74b61e8b
commit
f4fd499238
7 changed files with 29 additions and 59 deletions
|
|
@ -1,7 +1,8 @@
|
|||
include::topics/preface.adoc[]
|
||||
include::topics/admin-rest-api.adoc[]
|
||||
include::topics/themes.adoc[]
|
||||
include::topics/themes-selector.adoc[leveloffset=+2]
|
||||
include::topics/themes-selector.adoc[]
|
||||
include::topics/themes-resources.adoc[]
|
||||
include::topics/custom-attributes.adoc[]
|
||||
include::topics/identity-brokering.adoc[]
|
||||
include::topics/identity-brokering/tokens.adoc[]
|
||||
|
|
|
|||
|
|
@ -374,8 +374,8 @@ getReferenceCategory() is just a category the Authenticator belongs to.
|
|||
==== Adding Authenticator Form
|
||||
|
||||
Keycloak comes with a Freemarker <<_themes,theme and template engine>>.
|
||||
The createForm() method you called within authenticate() of your Authenticator class, builds an HTML page from a file within your login theme: secret-question.ftl.
|
||||
This file should be placed in the login theme with all the other .ftl files you see for login.
|
||||
The createForm() method you called within authenticate() of your Authenticator class, builds an HTML page from a file within your login theme: `secret-question.ftl`.
|
||||
This file should be added to the `theme-resources/templates` in your JAR, see <<_theme_resource,Theme Resource Provider>> for more details.
|
||||
|
||||
Let's take a bigger look at secret-question.ftl Here's a small code snippet:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
[[_custom_user_attributes]]
|
||||
== Custom User Attributes
|
||||
|
||||
You can add custom user attributes to the registration page and account management console with a custom theme. This chapter describes how to add attributes
|
||||
|
|
|
|||
|
|
@ -160,9 +160,9 @@ The alternative approach is to deploy as a module.
|
|||
|
||||
If you are creating a custom SPI you will need to deploy it as a module, otherwise we recommend using the {project_name} deployer approach.
|
||||
|
||||
==== Using the {project_name} deployer Deployer
|
||||
==== Using the {project_name} Deployer
|
||||
|
||||
If you copy your provider jar to the {project_name} deployer `deploy/` directory, your provider will automatically be deployed.
|
||||
If you copy your provider jar to the {project_name} `standalone/deployments/` directory, your provider will automatically be deployed.
|
||||
Hot deployment works too. Additionally, your provider jar works similarly to other components deployed in a {appserver_name}
|
||||
environment in that they can use facilities like the `jboss-deployment-structure.xml` file. This file allows you to
|
||||
set up dependencies on other components and load third-party jars and modules.
|
||||
|
|
|
|||
18
server_development/topics/themes-resources.adoc
Normal file
18
server_development/topics/themes-resources.adoc
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
[[_theme_resource]]
|
||||
=== Theme Resources
|
||||
|
||||
When implementing custom providers in {project_name} there may often be a need to add additional templates and resources.
|
||||
|
||||
ifeval::[{project_community}==true]
|
||||
An example use-case would be a <<_auth_spi,custom authenticator>> that requires additional templates and resources.
|
||||
endif::[]
|
||||
|
||||
The easiest way to load additional theme resources is to create a JAR with templates in `theme-resources/templates`
|
||||
and resources in `theme-resources/resources` and drop it into the `standalone/deployments/` directory of {project_name}.
|
||||
|
||||
If you want a more flexible way to load templates and resources that can be achieved through the ThemeResourceSPI.
|
||||
By implementing `ThemeResourceProviderFactory` and `ThemeResourceProvider` you can decide exactly how to load templates
|
||||
and resources.
|
||||
|
||||
Follow the steps in <<_providers,Service Provider Interfaces>> for more details on how to create and deploy a custom
|
||||
provider.
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
= Theme Selector
|
||||
[[_theme_selector]]
|
||||
=== Theme Selector
|
||||
|
||||
By default the theme configured for the realm is used, with the exception of clients being able to override the login
|
||||
theme. This behavior can be changed through the Theme Selector SPI.
|
||||
|
|
|
|||
|
|
@ -322,56 +322,5 @@ The contents of `META-INF/keycloak-themes.json` in this case would be:
|
|||
|
||||
A single archive can contain multiple themes and each theme can support one or more types.
|
||||
|
||||
To deploy the archive to {project_name} you can either manually create a module in `modules` or use the `jboss-cli` command. It's simplest to use
|
||||
`jboss-cli` as it creates the required directories and module descriptor for you.
|
||||
|
||||
To deploy `mytheme.zip` on Linux run:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
bin/jboss-cli.sh --command="module add --name=org.example.mytheme --resources=mytheme.zip"
|
||||
----
|
||||
|
||||
On Windows run:
|
||||
|
||||
[source]
|
||||
----
|
||||
bin\jboss-cli.bat --command="module add --name=org.example.mytheme --resources=mytheme.zip"
|
||||
----
|
||||
|
||||
This command creates `modules/org/example/mytheme/main` directory with the `mytheme.zip` archive and `module.xml`.
|
||||
|
||||
To manually create the module create the directory `modules/org/keycloak/example/mytheme/main`, copy `mytheme.zip` to this directory and create the file
|
||||
`modules/org/keycloak/example/mytheme/main/module.xml` with the contents:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<?xml version="1.0" ?>
|
||||
<module xmlns="urn:jboss:module:1.3" name="org.keycloak.example.themes">
|
||||
<resources>
|
||||
<resource-root path="mytheme.zip"/>
|
||||
</resources>
|
||||
</module>
|
||||
----
|
||||
|
||||
You also need to register the module with {project_name}. This is done by editing `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
For more information on where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file resides see the link:{installguide_link}[{installguide_name}].
|
||||
|
||||
Then find the `theme` tag under `keycloak-server` subsystem and add the module to `theme/modules/module`. For example:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<theme>
|
||||
...
|
||||
<modules>
|
||||
<module>org.example.mytheme</module>
|
||||
</modules>
|
||||
</theme>
|
||||
----
|
||||
|
||||
If the server is running you need to restart the server after changing `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
If the same theme is deployed to both the `themes` directory and as a module the version in the `themes` directory is used.
|
||||
====
|
||||
To deploy the archive to {project_name} simply drop it into the `standalone/deployments/` directory of
|
||||
{project_name} and it will be automatically loaded.
|
||||
|
|
|
|||
Loading…
Reference in a new issue