Inhaltsverzeichnis

WvdS.DokuWiki.Snippet Plugin

Plugin: wvdssnippet
Version: 2.0.0
Namespace: lib/plugins/wvdssnippet/
Author: Wolfgang van der Stille zeljko.petrusic@outlook.de
License: GPL 2

Definition

The wvdssnippet plugin enables reusable HTML building blocks (snippets) with centralized management. It provides a secure alternative to htmlok and allows combining HTML with multilingual translations.

Use Cases

Syntax

{{wvds:snippet>key}}

Parameters

Parameter Type Description
key string Name of the snippet from configuration

Snippet Definition

Format

Snippets are defined in the plugin configuration using the following format: 

[snippet_name]
HTML content here
can be multiline
key tags are allowed

Rules

Rule Description
Name line Starts with [name] on its own line
Content Everything after the name line until the next […]
Multiline Any number of lines possible
Empty lines Allowed within a snippet
wvdsi18n ... tags are processed
HTML Full HTML allowed

Allowed Content

Content Type Example
HTML tags

, <nav>, <ul>, etc. | | CSS classes | class=„my-class“ | | Inline styles | style=„color: red;“ | | JavaScript | onclick=„…“ (use with caution) | | Font Awesome | <i class=„fa fa-home“></i> | | wvdsi18n tags | Home | | Inline translations | de:Text|en:Text | —- ===== Configuration ===== ==== Admin Settings ==== Via Admin → Configuration → wvdssnippet: ^ Setting ^ Type ^ Description ^ | enabled | On/Off | Enable/disable plugin | | snippets | Textarea | Snippet definitions in INI-like format | ==== Example Configuration ==== <code> [main_menu] <nav class=„main-menu“> <ul class=„menu-list“> <li class=„menu-item“><a href=„?id=start“>Home</a></li> <li class=„menu-item“><a href=„?id=docs“>Project Documentation</a></li> <li class=„menu-item“><a href=„?id=contact“>Contact</a></li> </ul> </nav> [go_back] 

  <i class="fa fa-arrow-left"></i>
  <a href="javascript:history.back()">Go Back</a>

[social_links] 

  <a href="https://github.com/myorg" target="_blank"><i class="fa fa-github"></i></a>
  <a href="https://twitter.com/myorg" target="_blank"><i class="fa fa-twitter"></i></a>

[footer] <footer class=„site-footer“> 

      &copy; 2025 conf:title
  </div>
  <div class="links">
      <a href="?id=imprint">menu_imprint</a>
      <a href="?id=privacy">menu_privacy</a>
  </div>

</footer> </code>

Examples

Example 1: Main Menu in Sidebar

Requirement: Central navigation menu for all pages.

Snippet Definition: 

[main_menu]
<nav class="main-menu">
    <ul>
        <li><a href="?id=start">Home</a></li>
        <li><a href="?id=en:docs:start">Project Documentation</a></li>
    </ul>
</nav>

Usage in sidebar.txt: 

~~NOCACHE~~
{{wvds:snippet>main_menu}}

Result:

  • Menu appears on all pages
  • Translations are automatically applied
  • Changes are centralized in configuration

Requirement: Uniform back link in sub-namespaces.

Snippet Definition: 

[go_back]
<div class="go-back" style="margin-bottom: 1em;">
    <i class="fa fa-arrow-left" style="margin-right: 0.5em;"></i>
    <a href="javascript:history.back()">de:Zurück|en:Back|sl:Nazaj</a>
</div>

Usage in sidebar1.txt: 

~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}

Example 3: Contact Box

Requirement: Reusable contact information.

Snippet Definition: 

[contact_box]
<div class="contact-box">
    <h4>de:Kontakt|en:Contact|sl:Kontakt</h4>
    <p>
        <i class="fa fa-envelope"></i> info@example.com<br>
        <i class="fa fa-phone"></i> +49 123 456789
    </p>
</div>

Usage: 

{{wvds:snippet>contact_box}}

Requirement: Footer with dynamic year and localized links.

Snippet Definition: 

[footer]
<footer class="site-footer">
    <div class="footer-content">
        <p>&copy; 2025 conf:title</p>
        <nav class="footer-links">
            <a href="?id=imprint">menu_imprint</a> |
            <a href="?id=privacy">menu_privacy</a> |
            <a href="?id=sitemap">menu_sitemap</a>
        </nav>
    </div>
</footer>

How It Works

Processing Pipeline

1. Syntax Detection
   └── Finds all {{wvds:snippet>...}} tags

2. Snippet Lookup
   └── Searches snippet name in configuration
   └── Extracts HTML content

3. wvdsi18n Processing
   └── Replaces ... tags in snippet
   └── Applies current language

4. HTML Output
   └── Inserts processed HTML code into page
   └── No additional escaping (raw HTML)

Processing Order

Priority Plugin Sort Value
1 wvdsi18n 305
2 wvdssnippet 310
3 wvdsimage 319
wvdsi18n is processed before wvdssnippet so that translations in snippets work correctly.

Integration

With wvdsi18n

Snippets support all wvdsi18n syntax variants: 

[multilingual_block]
<div class="info">
    greeting
    de:Hallo|en:Hello|sl:Zdravo
    {{wvds:lang:en>english_only_text}}
</div>

With wvdsacmenu

Typical sidebar structure: 

~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}

With wvdsimage

Snippets can also contain images: 

[logo_block]
<div class="logo">
    {{wvds:image>wiki:logo.png|width=100%|maxwidth=200}}
</div>

Security

Advantages over htmlok

Aspect htmlok wvdssnippet
HTML Input Free in every page Only via Admin
Security Risk High (XSS, Injection) Low (controlled)
Audit Difficult (scattered) Easy (central)
User Rights Anyone with edit rights Administrators only

Best Practices

  • Keep JavaScript minimal - Only when absolutely necessary
  • External links with target=„_blank“ - Security with rel=„noopener“
  • No sensitive data - No API keys, passwords in snippets
  • Unique names - Choose descriptive snippet names

Error Handling

Behavior on Errors

Scenario Behavior
Snippet not found Outputs [snippet_name not found]
Empty snippet Outputs nothing
Invalid format Ignores invalid lines
wvdsi18n error Returns key (fallback)

Debugging

If problems occur, check:

  • Is the snippet name spelled correctly?
  • Does the definition start with [name]?
  • Is set for dynamic content?
  • Do the wvdsi18n tags work individually?

Performance

Recommendations

Scenario Recommendation
Static snippets Leave cache enabled
Dynamic snippets (language) Use
Large snippets Split into smaller ones
Many snippets Don't define more than 50

Caching

Pages with language-dependent snippets should have at the beginning so the correct language version is displayed.

Version History

Version Date Changes
2.0.0 2026-01-06 Renamed from wvdschunk to wvdssnippet
1.0.0 2025-01-06 Initial release

See Also

Technical Reference

Class: syntax_plugin_wvdssnippet

File: lib/plugins/wvdssnippet/syntax.php

Method Description
getType() Returns substition
getSort() Returns 310 (after wvdsi18n)
connectTo($mode) Registers pattern \\{\\{wvds:snippet>[^}]+\\}\\}
handle($match, …) Extracts snippet name
render($mode, …) Outputs HTML content

Private Methods

Method Parameters Returns Description
getSnippet() $name string Searches snippet in configuration
parseSnippets() $config array Parses snippet definitions
processSnippet() $content string