3.4. 创建主题
主题包括:
- HTML 模板(自由标记模板)
- 镜像
- 消息捆绑包
- 风格表
- 脚本
- me 属性
除非计划替换每个页面,否则您应该扩展另一个主题。您最有可能想扩展 Red Hat Single Sign-On 主题,但如果您对页面的外观有很大更改,您还可能考虑对基础进行扩展。其基础主题主要由 HTML 模板和消息捆绑包组成,而 Red Hat Single Sign-On theme 主要包含镜像和样式表。
在扩展主题时,您可以覆盖单个资源(模板、风格表等)。如果您决定覆盖 HTML 模板,在升级到新版本时您可能需要更新自定义模板。
在创建主题时,最好禁用缓存,因为这样可以直接从 themes
目录中编辑主题资源,而无需重启 Red Hat Single Sign-On。
流程
-
编辑
standalone.xml
。 对于
主题
,将staticMaxAge
设置为-1
,将cacheTemplates
和cacheThemes
设置为false
:Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在
主题
目录中创建一个目录。目录的名称成为主题的名称。例如,要创建一个名为
mytheme
的主题,请创建目录themes/mytheme
。在me 目录中,为您要提供的每种类型创建一个目录。
例如,要将登录类型添加到
mytheme
theme 中,请创建目录themes/mytheme/login
。对于每个类型,创建一个文件
theme.properties
,允许为主题设置一些配置。例如,要配置主题
themes/mytheme/login
以扩展基础主题并导入一些常见资源,请使用以下内容创建文件themes/mytheme/login/theme.properties
:parent=base import=common/keycloak
parent=base import=common/keycloak
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 您现在已创建了支持登录类型的主题。
- 登录到 Admin Console 以签出您的新主题
- 选择您的域
- 从菜单中点 Realm Settings。
- 点 Themes 选项卡。
- 对于 Login Theme,选择 mytheme 并点 Save。
打开域的登录页面。
您可以通过应用程序登录或打开帐户管理控制台(
/realms/{realm name}/account
)来执行此操作。-
要查看更改父主题的效果,请在me
.properties
中设置parent=keycloak
并刷新登录页面。
确保在生产环境中重新启用缓存,因为它会对性能有严重影响。
3.4.1. me 属性 复制链接链接已复制到粘贴板!
me 属性在主题目录中的 < ;THEME TYPE>/theme.properties
中设置。
- 父项 - 要扩展的主题
- import - 从另一主题导入资源
- 样式 - 空格分隔的样式列表包括
- locales - 以逗号分隔的支持区域列表
有一个属性列表可用于更改用于某些元素类型的 cs 类。如需这些属性的列表,请查看对应类型 keycloak theme 中的 theme.properties 文件(themes/keycloak/<THEME TYPE>/theme.properties
)。
您还可以添加自己的自定义属性,并从自定义模板使用它们。
在这样做时,您可以使用以下格式替换系统属性或环境变量:
-
${some.system.property}
- for system properties -
${env.ENV_VAR}
- 用于环境变量。
如果系统属性或环境变量没有使用 ${foo:defaultValue}
找到,也可以提供默认值。
如果没有提供默认值,且没有对应的系统属性或环境变量,则不会替换任何内容,您会在模板中以 格式结束。
以下是可能的问题示例:
javaVersion=${java.version} unixHome=${env.HOME:Unix home not found} windowsHome=${env.HOMEPATH:Windows home not found}
javaVersion=${java.version}
unixHome=${env.HOME:Unix home not found}
windowsHome=${env.HOMEPATH:Windows home not found}
3.4.2. 将风格表添加到主题 复制链接链接已复制到粘贴板!
您可以在主题中添加一个或多个样式表。
流程
-
在 <
THEME TYPE>/resources/css
目录中创建一个文件。 将此文件添加到
theme.properties
中的styles
属性中。例如,要将
风格.cs
添加到mytheme
中,请使用以下内容创建themes/mytheme/login/resources/css/styles.css
:.login-pf body { background: DimGrey none; }
.login-pf body { background: DimGrey none; }
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 编辑
它们/mytheme/login/theme.properties
并添加:styles=css/styles.css
styles=css/styles.css
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 要查看更改,请打开您的域的登录页面。
您将注意到应用的唯一样式是来自您的自定义风格表。
为了包括来自父主题的样式,请从该主题加载 样式。编辑
themes/mytheme/login/theme.properties
并更改样式
以:styles=web_modules/@fontawesome/fontawesome-free/css/icons/all.css web_modules/@patternfly/react-core/dist/styles/base.css web_modules/@patternfly/react-core/dist/styles/app.css node_modules/patternfly/dist/css/patternfly.min.css node_modules/patternfly/dist/css/patternfly-additions.min.css css/login.css css/styles.css
styles=web_modules/@fontawesome/fontawesome-free/css/icons/all.css web_modules/@patternfly/react-core/dist/styles/base.css web_modules/@patternfly/react-core/dist/styles/app.css node_modules/patternfly/dist/css/patternfly.min.css node_modules/patternfly/dist/css/patternfly-additions.min.css css/login.css css/styles.css
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意要从父风格表中覆盖样式,请确保您的风格表已列出最后。
3.4.3. 将脚本添加到主题 复制链接链接已复制到粘贴板!
您可以将一个或多个脚本添加到主题。
流程
-
在 <
THEME TYPE>/resources/js
目录中创建一个文件。 将此文件添加到
theme.properties
中的scripts
属性中。例如,要将
script.js
添加到mytheme
中,请使用以下内容创建themes/mytheme/login/resources/js/script.js
:alert('Hello');
alert('Hello');
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 然后编辑它们
/mytheme/login/theme.properties
并添加:scripts=js/script.js
scripts=js/script.js
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.4.4. 将镜像添加到主题 复制链接链接已复制到粘贴板!
要使镜像提供给主题,请将它们添加到主题的 < ;THEME TYPE>/resources/img
目录中。它们可以从样式表内使用,或者直接在 HTML 模板中使用。
例如,要在 mytheme
中添加一个镜像,将镜像复制到 themes/mytheme/login/resources/img/image.jpg
中。
然后您可以使用以下自定义风格表:
body { background-image: url('../img/image.jpg'); background-size: cover; }
body {
background-image: url('../img/image.jpg');
background-size: cover;
}
或者直接在 HTML 模板中使用以下内容,将以下内容添加到自定义 HTML 模板:
<img src="${url.resourcesPath}/img/image.jpg">
<img src="${url.resourcesPath}/img/image.jpg">
3.4.5. 消息 复制链接链接已复制到粘贴板!
模板中的文本从消息捆绑包加载。扩展另一主题的主题将继承父消息捆绑包中的所有消息,您可以通过向您的主题添加 < THEME TYPE>/messages/messages_en.properties
来覆盖单个消息。
例如,在登录表单上,使用 Your
for Username
mytheme
create file themes/mytheme/login/messages/messages_en.properties
替换为以下内容:
usernameOrEmail=Your Username
usernameOrEmail=Your Username
在使用消息值时,{0}
和 {1}
等消息值会被替换为参数。例如,{0} 中的 {0}
被替换为该域的名称。
这些消息捆绑包的文本可以被特定域的值覆盖。特定于 realm 的值可通过 UI 和 API 进行管理。
3.4.6. 在域中添加语言 复制链接链接已复制到粘贴板!
先决条件
- 要为域启用国际化,请查看 服务器管理指南。
流程
-
在主题的目录中创建文件
<THEME TYPE>/messages/messages_<LOCALE>.properties
。 将此文件添加到 <
THEME TYPE>/theme.properties
中的locales
属性。要使语言提供给用户登录
、帐户和
电子邮件
,主题必须支持该语言,因此您需要为这些主题类型添加您的语言。例如:要将 Norwegian 转换添加到
mytheme
theme create filethemes/mytheme/login/messages/messages_no.properties
中以下内容:usernameOrEmail=Brukernavn password=Passord
usernameOrEmail=Brukernavn password=Passord
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果省略了消息的翻译,将使用英语。
编辑
它们/mytheme/login/theme.properties
并添加:locales=en,no
locales=en,no
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
为
帐户
添加相同的电子邮件
类型。要执行此操作,请创建它们/mytheme/account/messages/messages_no.properties
和themes/mytheme/email/messages_no.properties
。这些文件为空将导致使用英语消息。 -
将
themes/mytheme/login/theme.properties
复制到themes/mytheme/account/theme.properties
以及themes/mytheme/email/theme.properties
。 为语言选择器添加翻译。这是通过向英语翻译添加消息来完成的。要执行此操作,请将以下内容添加到
themes/mytheme/account/messages/messages_en.properties
和themes/mytheme/login/messages/messages_en.properties
:locale_no=Norsk
locale_no=Norsk
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 默认情况下,消息属性文件应使用 ISO-8859-1 进行编码。也可以使用特殊标头指定编码。例如,使用 UTF-8 编码:
encoding: UTF-8
# encoding: UTF-8 usernameOrEmail=....
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.4.7. 添加自定义身份提供程序图标 复制链接链接已复制到粘贴板!
Red Hat Single Sign-On 支持为自定义身份提供程序添加图标,该图标显示在登录屏幕中。
流程
-
在 login
theme.properties
文件中定义图标类(例如themes/mytheme/login/theme.properties
)使用键模式kcLogoIdP-<alias&
gt;。 对于带有别名
myProvider
的身份提供程序,您可以在自定义主题的me.properties
文件中添加一行。例如:kcLogoIdP-myProvider = fa fa-lock
kcLogoIdP-myProvider = fa fa-lock
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
所有图标都位于 PatternFly4 的官方网站上。社交供应商的图标已在基本登录主题属性中定义(它们/密钥/登录/theme.properties
),您可以激励自己。
3.4.8. 创建自定义 HTML 模板 复制链接链接已复制到粘贴板!
Red Hat Single Sign-On 使用 Apache Freemarker 模板来生成 HTML。您可以通过创建 < THEME TYPE>/<TEMPLATE>.ftl
来覆盖您的主题中的单个模板。有关使用的模板列表,请查看 themes/base/<THEME TYPE>
。
流程
- 将模板从基础主题复制到您自己的主题。
应用您需要的修改。
例如,要为
mytheme
theme 创建自定义登录表单,请将themes/base/login/login.ftl
复制到他们es/mytheme/login
,并在编辑器中打开它。第一行(<#import …>)后,添加
<h1>HELLO WORLD!</h1&
gt;,如下所示:<#import "template.ftl" as layout> <h1>HELLO WORLD!</h1> ...
<#import "template.ftl" as layout> <h1>HELLO WORLD!</h1> ...
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 备份修改后的模板。当升级到新版本的 Red Hat Single Sign-On 时,您可能需要更新自定义模板,以对原始模板应用更改(如果适用)。
3.4.9. 电子邮件 复制链接链接已复制到粘贴板!
要编辑电子邮件的主题和内容,如密码恢复电子邮件,请在主题 的电子邮件
类型中添加消息捆绑包。每个电子邮件都有三个信息。对于主题,一个用于纯文本正文,另一个用于 html 正文。
要查看所有可用电子邮件,请查看 主题/基础/电子邮件/messages/messages_en.properties
。
例如,要更改 mytheme
的密码恢复电子邮件,请创建主题主题创建 主题/mytheme/email/messages/messages_en.properties
以及以下内容:
passwordResetSubject=My password recovery passwordResetBody=Reset password link: {0} passwordResetBodyHtml=<a href="{0}">Reset password</a>
passwordResetSubject=My password recovery
passwordResetBody=Reset password link: {0}
passwordResetBodyHtml=<a href="{0}">Reset password</a>