====== 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 =====

  * **Navigation Menus** - Main menu, sidebar navigation managed centrally
  * **Repeating Elements** - Footer, headers, buttons
  * **Localized Components** - HTML with integrated multilingual support
  * **Widget-like Blocks** - Social media links, contact boxes
  * **Template Extensions** - Complex HTML structures in wiki pages

----

===== Syntax =====

<code>
{{wvds:snippet>key}}
</code>

==== 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:

<code>
[snippet_name]
HTML content here
can be multiline
{{wvds:i18n>key}} tags are allowed
</code>

==== 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 | ''<nowiki>{{wvds:i18n>...}}</nowiki>'' tags are processed |
| HTML | Full HTML allowed |

==== Allowed Content ====

^ Content Type ^ Example ^
| HTML tags | ''<div>'', ''<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 | ''<nowiki>{{wvds:i18n>menu_home}}</nowiki>'' |
| Inline translations | ''<nowiki>{{wvds:i18n>de:Text|en:Text}}</nowiki>'' |

----

===== 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">{{wvds:i18n>menu_home}}</a></li>
        <li class="menu-item"><a href="?id=docs">{{wvds:i18n>menu_docs}}</a></li>
        <li class="menu-item"><a href="?id=contact">{{wvds:i18n>menu_contact}}</a></li>
    </ul>
</nav>

[go_back]
<div class="go-back">
    <i class="fa fa-arrow-left"></i>
    <a href="javascript:history.back()">{{wvds:i18n>menu_back}}</a>
</div>

[social_links]
<div class="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>
</div>

[footer]
<footer class="site-footer">
    <div class="copyright">
        &copy; 2025 {{wvds:i18n>conf:title}}
    </div>
    <div class="links">
        <a href="?id=imprint">{{wvds:i18n>menu_imprint}}</a>
        <a href="?id=privacy">{{wvds:i18n>menu_privacy}}</a>
    </div>
</footer>
</code>

----

===== Examples =====

==== Example 1: Main Menu in Sidebar ====

**Requirement:** Central navigation menu for all pages.

**Snippet Definition:**
<code>
[main_menu]
<nav class="main-menu">
    <ul>
        <li><a href="?id=start">{{wvds:i18n>menu_home}}</a></li>
        <li><a href="?id=en:docs:start">{{wvds:i18n>menu_docs}}</a></li>
    </ul>
</nav>
</code>

**Usage in sidebar.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>main_menu}}
</code>

**Result:**
  * Menu appears on all pages
  * Translations are automatically applied
  * Changes are centralized in configuration

==== Example 2: Back Link with Icon ====

**Requirement:** Uniform back link in sub-namespaces.

**Snippet Definition:**
<code>
[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()">{{wvds:i18n>de:Zurück|en:Back|sl:Nazaj}}</a>
</div>
</code>

**Usage in sidebar1.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== Example 3: Contact Box ====

**Requirement:** Reusable contact information.

**Snippet Definition:**
<code>
[contact_box]
<div class="contact-box">
    <h4>{{wvds:i18n>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>
</code>

**Usage:**
<code>
{{wvds:snippet>contact_box}}
</code>

==== Example 4: Multilingual Footer ====

**Requirement:** Footer with dynamic year and localized links.

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

----

===== How It Works =====

==== Processing Pipeline ====

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

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

3. wvdsi18n Processing
   └── Replaces {{wvds:i18n>...}} tags in snippet
   └── Applies current language

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

==== Processing Order ====

^ Priority ^ Plugin ^ Sort Value ^
| 1 | wvdsi18n | 305 |
| 2 | wvdssnippet | 310 |
| 3 | wvdsimage | 319 |

<note>
wvdsi18n is processed **before** wvdssnippet so that translations in snippets work correctly.
</note>

----

===== Integration =====

==== With wvdsi18n ====

Snippets support all wvdsi18n syntax variants:

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

==== With wvdsacmenu ====

Typical sidebar structure:

<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== With wvdsimage ====

Snippets can also contain images:

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

----

===== 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 ''~~NOCACHE~~'' set for dynamic content?
  * Do the wvdsi18n tags work individually?

----

===== Performance =====

==== Recommendations ====

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

==== Caching ====

<note tip>
Pages with language-dependent snippets should have ''~~NOCACHE~~'' at the beginning so the correct language version is displayed.
</note>

----

===== 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 =====

  * [[wvdsi18n]] - Multilingual translations
  * [[wvdsacmenu]] - Accordion menu
  * [[wvdsimage]] - Responsive images
  * [[flat]] - Template extensions

----

===== 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 | Processes wvdsi18n tags |

==== Configuration Format ====

<code>
# Comments with # (are ignored)

[snippet_name_1]
HTML content for snippet 1
can be multiline

[snippet_name_2]
HTML content for snippet 2
</code>

----

{{wvds:snippet>wvds_audit_badge}}

~~DISCUSSION~~