Decompose base.ftl template (#2432)

Kotlin · Apr 15, 2022 · 8305eaf · 8305eaf
1 parent 48b5918
commit 8305eaf
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 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
@@ -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>
-    ```
+* `<@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>
+  ```
diff --git 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
@@ -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>
diff --git a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl 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>
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
@@ -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>
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
@@ -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>