diff options
| author | Vadim Mishenev <vad-mishenev@yandex.ru> | 2022-04-15 21:39:31 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-04-15 21:39:31 +0300 |
| commit | 8305eaffbc51fccc72183b4fe64f4c9db047fb82 (patch) | |
| tree | 67ec0b826c50dcfc538f488a2ff759a1cd66120d | |
| parent | 48b5918c2d465b482de4f070879b5ad93cc248b3 (diff) | |
| download | dokka-8305eaffbc51fccc72183b4fe64f4c9db047fb82.tar.gz dokka-8305eaffbc51fccc72183b4fe64f4c9db047fb82.tar.bz2 dokka-8305eaffbc51fccc72183b4fe64f4c9db047fb82.zip | |
Decompose `base.ftl` template (#2432)
6 files changed, 74 insertions, 48 deletions
diff --git a/docs/src/doc/docs/user_guide/base-specific/frontend.md b/docs/src/doc/docs/user_guide/base-specific/frontend.md index 2a6deac9..0e31aa48 100644 --- a/docs/src/doc/docs/user_guide/base-specific/frontend.md +++ b/docs/src/doc/docs/user_guide/base-specific/frontend.md @@ -81,22 +81,29 @@ To customize HTML output, you can use the [default template](https://github.com/ To change page assets, you can set properties `customAssets` and `customStyleSheets`. Assets are handled by Dokka itself, not FreeMaker. -Currently, there is only one template file with predefined name `base.ftl`. It defines general design of all pages to render. -If `templatesDir` is defined, Dokka will find the `base.ftl` file there. +There is a template file with predefined name `base.ftl`. It defines general design of all pages to render. +`base.ftl` can import another templates that can be set by user as well: +* `includes/header.ftl` +* `includes/footer.ftl` +* `includes/page_metadata.ftl` +* `includes/source_set_selector.ftl`. + +If `templatesDir` is defined, Dokka will find a template file there. +If the file is not found, a default one will be used. Variables given below are available to the template: - * `${pageName}` - the page name - * `${footerMessage}` - text that is set by the `footerMessage` property - * `${sourceSets}` - a nullable list of source sets, only for multi-platform pages. Each source set has `name`, `platfrom` and `filter` properties. +* `${pageName}` - the page name +* `${footerMessage}` - text that is set by the `footerMessage` property +* `${sourceSets}` - a nullable list of source sets, only for multi-platform pages. Each source set has `name`, `platfrom` and `filter` properties. Also, Dokka-defined [directives](https://freemarker.apache.org/docs/ref_directive_userDefined.html) can be used: - * `<@content/>` - main content - * `<@resources/>` - scripts, stylesheets - * `<@version/>` - version ([versioning-plugin](https://kotlin.github.io/dokka/1.6.20/user_guide/versioning/versioning/) will replace this with a version navigator) - * `<@template_cmd name="...""> ...</@template_cmd>` - is used for variables that depend on the root project (such `pathToRoot`, `projectName`). They are available only inside the directive. This is processed by a multi-module task that assembles partial outputs from modules. - Example: - ``` - <@template_cmd name="projectName"> - <span>${projectName}</span> - </@template_cmd> - ```
\ No newline at end of file +* `<@content/>` - main content +* `<@resources/>` - scripts, stylesheets +* `<@version/>` - version ([versioning-plugin](https://kotlin.github.io/dokka/1.6.20/user_guide/versioning/versioning/) will replace this with a version navigator) +* `<@template_cmd name="...""> ...</@template_cmd>` - is used for variables that depend on the root project (such `pathToRoot`, `projectName`). They are available only inside the directive. This is processed by a multi-module task that assembles partial outputs from modules. + Example: + ``` + <@template_cmd name="projectName"> + <span>${projectName}</span> + </@template_cmd> + ```
\ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/base.ftl b/plugins/base/src/main/resources/dokka/templates/base.ftl index fb8fabd9..78ce21e2 100644 --- a/plugins/base/src/main/resources/dokka/templates/base.ftl +++ b/plugins/base/src/main/resources/dokka/templates/base.ftl @@ -1,10 +1,12 @@ +<#import "includes/page_metadata.ftl" as page_metadata> +<#import "includes/header.ftl" as header> +<#import "includes/footer.ftl" as footer> <!DOCTYPE html> <html> <head> <meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8"> - <title>${pageName}</title> + <@page_metadata.display/> <@template_cmd name="pathToRoot"> - <link href="${pathToRoot}images/logo-icon.svg" rel="icon" type="image/svg"> <script>var pathToRoot = "${pathToRoot}";</script> </@template_cmd> <#-- This script doesn't need to be there but it is nice to have @@ -19,43 +21,14 @@ if(savedDarkMode === true){ <@resources/> </head> <body> -<div class="navigation-wrapper" id="navigation-wrapper"> - <div id="leftToggler"><span class="icon-toggler"></span></div> - <div class="library-name"> - <@template_cmd name="pathToRoot"> - <a href="${pathToRoot}index.html"> - <@template_cmd name="projectName"> - <span>${projectName}</span> - </@template_cmd> - </a> - </@template_cmd> - </div> - <div> - <#-- This can be handled by a versioning plugin --> - <@version/> - </div> - <div class="pull-right d-flex"> - <#if sourceSets??> - <div class="filter-section" id="filter-section"> - <#list sourceSets as ss> - <button class="platform-tag platform-selector ${ss.platform}-like" data-active="" data-filter="${ss.filter}">${ss.name}</button> - </#list> - </div> - </#if> - <button id="theme-toggle-button"><span id="theme-toggle"></span></button> - <div id="searchBar"></div> - </div> -</div> + <@header.display/> <div id="container"> <div id="leftColumn"> <div id="sideMenu"></div> </div> <div id="main"> <@content/> - <div class="footer"><span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>${footerMessage}</span><span - class="pull-right"><span>Generated by </span><a - href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span> - </div> + <@footer.display/> </div> </div> </body> diff --git a/plugins/base/src/main/resources/dokka/templates/includes/footer.ftl b/plugins/base/src/main/resources/dokka/templates/includes/footer.ftl new file mode 100644 index 00000000..461a8162 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/footer.ftl @@ -0,0 +1,7 @@ +<#macro display> + <div class="footer"> + <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>${footerMessage}</span><span + class="pull-right"><span>Generated by </span><a + href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span> + </div> +</#macro>
\ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl new file mode 100644 index 00000000..a7ba81ba --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl @@ -0,0 +1,24 @@ +<#import "source_set_selector.ftl" as source_set_selector> +<#macro display> +<div class="navigation-wrapper" id="navigation-wrapper"> + <div id="leftToggler"><span class="icon-toggler"></span></div> + <div class="library-name"> + <@template_cmd name="pathToRoot"> + <a href="${pathToRoot}index.html"> + <@template_cmd name="projectName"> + <span>${projectName}</span> + </@template_cmd> + </a> + </@template_cmd> + </div> + <div> + <#-- This can be handled by a versioning plugin --> + <@version/> + </div> + <div class="pull-right d-flex"> + <@source_set_selector.display/> + <button id="theme-toggle-button"><span id="theme-toggle"></span></button> + <div id="searchBar"></div> + </div> +</div> +</#macro>
\ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl b/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl new file mode 100644 index 00000000..f897c104 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl @@ -0,0 +1,6 @@ +<#macro display> + <title>${pageName}</title> + <@template_cmd name="pathToRoot"> + <link href="${pathToRoot}images/logo-icon.svg" rel="icon" type="image/svg"> + </@template_cmd> +</#macro>
\ No newline at end of file diff --git a/plugins/base/src/main/resources/dokka/templates/includes/source_set_selector.ftl b/plugins/base/src/main/resources/dokka/templates/includes/source_set_selector.ftl new file mode 100644 index 00000000..13650ee5 --- /dev/null +++ b/plugins/base/src/main/resources/dokka/templates/includes/source_set_selector.ftl @@ -0,0 +1,9 @@ +<#macro display> + <#if sourceSets??> + <div class="filter-section" id="filter-section"> + <#list sourceSets as ss> + <button class="platform-tag platform-selector ${ss.platform}-like" data-active="" data-filter="${ss.filter}">${ss.name}</button> + </#list> + </div> + </#if> +</#macro>
\ No newline at end of file |