Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Decompose base.ftl template #2432

Merged
merged 4 commits into from Apr 15, 2022
Merged

Decompose base.ftl template #2432

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4b279c5
Decompose `base.ftl` template
vmishenev Apr 11, 2022
399e3e6
Move source set selector out
vmishenev Apr 13, 2022
aeaf9e9
Refactor and remove `article.ftl`
vmishenev Apr 14, 2022
ffb21b7
Merge branch 'master' into decompose-base-template
vmishenev Apr 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 17 additions & 15 deletions docs/src/doc/docs/user_guide/base-specific/frontend.md
View file
Open in desktop
Expand Up @@ -81,22 +81,24 @@ 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.
IgnatBeresnev marked this conversation as resolved.
Show resolved Hide resolved
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.10/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>
```
* `<@content/>` - main content
* `<@resources/>` - scripts, stylesheets
* `<@version/>` - version ([versioning-plugin](https://kotlin.github.io/dokka/1.6.10/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>
```
42 changes: 8 additions & 34 deletions plugins/base/src/main/resources/dokka/templates/base.ftl
View file
Open in desktop
@@ -1,10 +1,13 @@
<#import "includes/page_heads.ftl" as page_heads>
<#import "includes/header.ftl" as header>
<#import "includes/footer.ftl" as footer>
<#import "includes/article.ftl" as article>
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
<title>${pageName}</title>
<@page_heads.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
Expand All @@ -19,43 +22,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>
<@article.display/>
<@footer.display/>
</div>
</div>
</body>
Expand Down
3 changes: 3 additions & 0 deletions plugins/base/src/main/resources/dokka/templates/includes/article.ftl
View file
Open in desktop
@@ -0,0 +1,3 @@
<#macro display>
<@content/>
</#macro>
IgnatBeresnev marked this conversation as resolved.
Show resolved Hide resolved
7 changes: 7 additions & 0 deletions plugins/base/src/main/resources/dokka/templates/includes/footer.ftl
View file
Open in desktop
@@ -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>
24 changes: 24 additions & 0 deletions plugins/base/src/main/resources/dokka/templates/includes/header.ftl
View file
Open in desktop
@@ -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>
6 changes: 6 additions & 0 deletions plugins/base/src/main/resources/dokka/templates/includes/page_heads.ftl
View file
Open in desktop
@@ -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>
IgnatBeresnev marked this conversation as resolved.
Show resolved Hide resolved
9 changes: 9 additions & 0 deletions plugins/base/src/main/resources/dokka/templates/includes/source_set_selector.ftl
View file
Open in desktop
@@ -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>