====== WvdS.DokuWiki.Flat Template ====== **Template:** flat\\ **Version:** 1.1.0 (WvdS Extensions)\\ **Namespace:** ''lib/tpl/flat/''\\ **Original:** beemoon \\ **Extensions:** Wolfgang van der Stille \\ **License:** GPL 2 ---- ===== Definition ===== The **Flat Template** is a minimalist, responsive DokuWiki template with WvdS extensions for multilingual support, language switcher, configurable sidebars, logo system with base64 rendering, and seamless integration with WvdS plugins. ===== Use Cases ===== * **Multilingual Documentation** - Automatic language switcher and detection * **Knowledge Bases** - Clean navigation with accordion menus * **Project Documentation** - Hierarchical sidebar structure * **Enterprise Wikis** - Professional, customizable design * **Optimized Performance** - Inline base64 images, cookie-based state management ---- ===== Features ===== ==== WvdS Extensions ==== ^ Feature ^ Description ^ | Language Switcher | Built-in language switching with flag icons | | Automatic Redirect | Redirect based on browser language | | Dual Sidebar | Configurable top and bottom sidebar | | Accordion Menu | Collapsible navigation | | Multilingual Text | Support for ''de:X|en:Y'' format | | Logo System | Flexible logo with base64 rendering via wvdsimage | | TOC State | Table of contents state saved in cookie | | Plugin Integration | Seamless cooperation with WvdS plugins | ---- ===== Configuration ===== ==== Language Switcher ==== ^ Setting ^ Type ^ Default ^ Description ^ | ''enableLangSwitcher'' | On/Off | Off | Enable language switcher | | ''languages'' | Text | de,en | Available languages (comma-separated) | | ''langPosition'' | Number | 0 | Position of language in namespace (0 = first level) | | ''defaultLanguage'' | Text | de | Default language for fallback | **enableAutoRedirect removed:** Automatic redirects are now handled via the [[wvdscond]] plugin. Use ''{{wvds:redirect target="{lang}:start"}}'' in your wiki pages. ==== Sidebar ==== ^ Setting ^ Type ^ Default ^ Description ^ | ''topSidebar'' | Text | sidebar | Top sidebar page | | ''bottomSidebar'' | Text | sidebar1 | Bottom sidebar page | | ''topSidebarTitle'' | Text | //(empty)// | Title of top sidebar | | ''bottomSidebarTitle'' | Text | //(empty)// | Title of bottom sidebar | | ''adminSidebarTitle'' | Text | //(empty)// | Title of admin sidebar | | ''enableAccordion'' | On/Off | Off | Accordion behavior for sidebar | ==== Logo and Title ==== ^ Setting ^ Type ^ Default ^ Description ^ | ''showTitle'' | On/Off | On | Show wiki title | | ''showLogo'' | On/Off | Off | Show logo | | ''logoSource'' | Choice | template | Logo source: ''template'', ''wiki'', ''url'' | | ''logoPath'' | Text | //(empty)// | Path depending on source (filename, wiki:path or URL) | | ''logoContainerSize'' | Number | 300 | Container size in pixels (square) | | ''logoFit'' | Choice | contain | Image fit: ''contain'', ''cover'', ''fill'', ''scale-down'', ''none'' | | ''logoPosition'' | Choice | center | Position in container: ''center'', ''top'', ''bottom'', etc. | | ''logoMaxWidth'' | Number | 300 | Max resize width for image optimization | | ''logoQuality'' | Number | 90 | Image quality (10-100) | **base64 Rendering:** When the [[wvdsimage]] plugin is installed, logos are rendered as base64 inline images. This reduces HTTP requests and improves load time. ==== TOC (Table of Contents) ==== ^ Setting ^ Type ^ Default ^ Description ^ | TOC Cookie | Automatic | - | State (expanded/collapsed) is saved in cookie ''dw_toc_state'' (1 year) | The TOC state is automatically saved when the user clicks the toggle. On the next page load, the saved state is restored (desktop only). ==== Footer ==== ^ Setting ^ Type ^ Default ^ Description ^ | ''footerText'' | Text | //(empty)// | Footer text (supports ''de:X|en:Y'' format) | ---- ===== Examples ===== ==== Example 1: Multilingual Configuration ==== **Requirement:** Wiki with German, English, and Slovenian. **conf/local.php:** $conf['tpl']['flat']['enableLangSwitcher'] = 1; $conf['tpl']['flat']['languages'] = 'de,en,sl'; $conf['tpl']['flat']['langPosition'] = 0; $conf['tpl']['flat']['defaultLanguage'] = 'de'; **start.txt (for auto-redirect):** {{wvds:redirect target="{lang}:start"}} **Result:** * Language switcher shows DE/EN/SL options * Auto-redirect via wvdscond plugin * Language is detected from ''de:page'', ''en:page'', ''sl:stran'' * Visitors are automatically redirected to matching language ==== Example 2: Sidebar Structure ==== **Requirement:** Main menu at top, accordion navigation at bottom. **File structure:** data/pages/ ├── sidebar.txt → Main menu ├── sidebar1.txt → Empty file (placeholder) ├── de/ │ └── sidebar1.txt → {{wvds:snippet>go_back}} │ {{wvds:acmenu dynamic="2"}} ├── en/ │ └── sidebar1.txt → {{wvds:snippet>go_back}} │ {{wvds:acmenu dynamic="2"}} └── en/crypto/ └── sidebar1.txt → {{wvds:snippet>go_back}} {{wvds:acmenu dynamic="1"}} **sidebar.txt (Root):** ~~NOCACHE~~ {{wvds:snippet>main_menu}} **en/sidebar1.txt:** ~~NOCACHE~~ {{wvds:snippet>go_back}} {{wvds:acmenu dynamic="2"}} ==== Example 3: Multilingual Footer ==== **Requirement:** Footer text in different languages. **Configuration:** footerText = de:© 2025 Meine Firma - Alle Rechte vorbehalten|en:© 2025 My Company - All rights reserved|sl:© 2025 Moje podjetje - Vse pravice pridržane **Result:** * German pages: "© 2025 Meine Firma - Alle Rechte vorbehalten" * English pages: "© 2025 My Company - All rights reserved" * Slovenian pages: "© 2025 Moje podjetje - Vse pravice pridržane" ==== Example 4: Logo Configuration ==== **Requirement:** Logo from wiki media with optimal display. **Admin Configuration:** showLogo = 1 logoSource = wiki logoPath = wiki:logo.png logoContainerSize = 300 logoFit = contain logoPosition = center logoMaxWidth = 300 logoQuality = 90 **Result:** * Logo is rendered as base64 inline image (via wvdsimage) * No additional HTTP request for the logo * Image is scaled to max 300px and centered in 300x300px container * ''object-fit: contain'' ensures the entire image is visible **Alternative: Logo from template directory:** showLogo = 1 logoSource = template logoPath = logo.png // located in lib/tpl/flat/images/logo.png **Alternative: External logo:** showLogo = 1 logoSource = url logoPath = https://example.com/logo.png ---- ===== How It Works ===== ==== Language Switcher Logic ==== 1. Namespace Analysis └── Extracts language from position langPosition └── Example: en:crypto:openssl → "en" 2. Language Switch └── Replaces language segment in namespace └── en:crypto:openssl → de:crypto:openssl 3. Page Check └── Checks if target page exists └── If not: Redirect to language start page ==== Sidebar Resolution ==== 1. Namespace-specific └── Searches for sidebar/sidebar1 in current namespace 2. Parent Namespace └── Searches upward in parent namespaces 3. Root Fallback └── Uses root sidebar if nothing found ==== Automatic Redirect ==== 1. Detect Browser Language └── Parse Accept-Language header 2. Language Available? ├── Yes: Redirect to language namespace └── No: Redirect to defaultLanguage ---- ===== Integration with WvdS Plugins ===== The template works seamlessly with WvdS plugins: ==== wvdsi18n (Internationalization) ==== // In template files $helper = plugin_load('helper', 'wvdsi18n'); $lang = $helper->detectLanguage(); $text = $helper->get('menu_home'); **Usage:** * Localize footer texts * Translate menu labels * Parse configuration values **Migration:** The ''wvdslang'' plugin has been replaced by ''wvdsi18n''. Redirects are now handled by ''wvdscond''. ==== wvdschunk ==== **sidebar.txt:** {{wvds:snippet>main_menu}} **Usage:** * Reusable menu structures * HTML components in sidebars * Shared elements across namespaces ==== wvdsacmenu ==== **sidebar1.txt:** {{wvds:acmenu dynamic="2"}} **Usage:** * Accordion navigation in sidebars * Dynamic namespace detection * Automatic open/close behavior ---- ===== CSS Customization ===== ==== Overridable Classes ==== ^ Class ^ Description ^ | ''.dokuwiki'' | Main container | | ''.wrapper'' | Content wrapper | | ''.sidebar'' | Sidebar container | | ''.sidebar-top'' | Top sidebar | | ''.sidebar-bottom'' | Bottom sidebar | | ''.lang-switcher'' | Language switcher container | | ''.lang-flag'' | Language flags | | ''.footer'' | Footer area | | ''.logo-wrapper'' | Logo wrapper container | | ''.logo-container'' | Logo clickable area | | ''.logo-img'' | Logo image | ==== Custom Styles ==== Create ''conf/userstyle.css'' for customizations: /* Language switcher customization */ .lang-switcher { position: fixed; top: 10px; right: 10px; } /* Sidebar width */ .sidebar { width: 280px; } /* Footer styling */ .footer { background: #333; color: #fff; padding: 20px; } ---- ===== Error Handling ===== ^ Scenario ^ Behavior ^ | Language not configured | Shows all languages from ''languages'' | | Target page not found | Redirect to language start page | | Sidebar not found | Uses root sidebar | | Plugin not installed | Template works without extensions | | wvdsimage not installed | Logo uses regular URL instead of base64 | ---- ===== Best Practices ===== * **~~NOCACHE~~** in all sidebars with dynamic content * **langPosition** set correctly for namespace structure * **sidebar1.txt** create in each language namespace * **wvdschunk** use for reusable menu elements * **Fallback language** always configure ---- ===== Version History ===== ^ Version ^ Date ^ Changes ^ | 1.1.0 | 2026-01-08 | Logo system with wvdsimage integration, TOC cookie persistence | | 1.0.0 | 2025-01-06 | WvdS extensions added | ---- ===== See Also ===== * [[wvdsi18n]] - Internationalization (translations) * [[wvdscond]] - Conditional content + Redirects * [[wvdssnippet]] - Reusable HTML components * [[wvdsacmenu]] - Accordion menu * [[wvdsimage]] - Image processing with base64 output * [[https://www.dokuwiki.org/template:flat|Original Flat Template]] ---- ===== Technical Reference ===== ==== File Structure ==== lib/tpl/flat/ ├── main.php → Main template ├── detail.php → Media detail view ├── mediamanager.php → Media manager ├── conf/ │ ├── default.php → Default configuration │ └── metadata.php → Configuration metadata ├── lang/ │ ├── de/lang.php → German translations │ ├── en/lang.php → English translations │ └── sl/lang.php → Slovenian translations ├── lang_helper.php → Language & logo helper functions ├── css/ │ ├── style.css → Template styles │ └── logo.css → Logo styles ├── js/ │ └── script.js → Template scripts (incl. TOC cookie) └── images/ └── flags/ → Language flags ==== Template Functions ==== ^ Function ^ Description ^ | ''tpl_getLang()'' | Returns current language | | ''tpl_langSwitcher()'' | Renders language switcher HTML | | ''tpl_sidebar($which)'' | Renders specified sidebar | | ''tpl_footer()'' | Renders footer with multilingual text | | ''tpl_renderLogo()'' | Renders logo with base64 support | | ''tpl_getLangNs()'' | Returns namespace-aware translated string | | ''tpl_parseMultilang()'' | Parses multilingual format strings | ==== Hook Points ==== ^ Hook ^ Description ^ | ''TPL_METAHEADER_OUTPUT'' | Modify meta header | | ''TPL_ACT_RENDER'' | Action rendering | | ''TPL_CONTENT_DISPLAY'' | Content display | ---- [x][x][x][x] [x][x][x][x][x] [x][x][x][-][-] ~~DISCUSSION~~