====== Struct Template Plugin ======

---- plugin ----
description: Use struct data to fill in a template, as many times as there are results
author     : Iain Hallam
email      : iain@nineworlds.net 
type       : syntax
lastupdate : 2022-03-11
compatible : Hogfather
depends    : struct
conflicts  : 
similar    : dataloop, datatemplate
tags       : html, struct, template

downloadurl: https://github.com/iainhallam/dokuwiki-plugin-structtemplate/zipball/main
bugtracker : https://github.com/iainhallam/dokuwiki-plugin-structtemplate/issues
sourcerepo : https://github.com/iainhallam/dokuwiki-plugin-structtemplate/
donationurl: 

screenshot_img : 
----

===== Installation =====

:!: **External requirements:** This plugin requires the following additional components that must be installed separately: 
  * [[plugin:Struct]]

Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

Social media links:

With a struct schema, ''socialmedia'':

^name^link^
|''Facebook''|''<nowiki>https://www.facebook.com/pages/DokuWiki/52877633616</nowiki>''|
|''Twitter''|''<nowiki>https://twitter.com/dokuwiki</nowiki>''|
|''GitHub''|''<nowiki>https://github.com/dokuwiki/dokuwiki</nowiki>''|

... the following template:

<code>
<struct-template>
---- data ----
schema: socialmedia
cols: name, link
----
 [[{{$$socialmedia.link}}|{{$$socialmedia.name}}]]
</struct-template>
</code>

... will render as:

 [[https://www.facebook.com/pages/DokuWiki/52877633616|Facebook]] [[https://twitter.com/dokuwiki|Twitter]] [[https://github.com/dokuwiki/dokuwiki|GitHub]]

===== Syntax =====

==== Basic syntax ====

<code>
<struct-template>
---- data ----
schema: ...
cols: ...
filter: ...
sort: ...
----
...
</struct-template>
</code>

The opening tag can be any of the following:

    * ''<struct-template>'' or ''<struct-template inline>'': will be enclosed in any element from outside the template
    * ''<STRUCT-TEMPLATE>'' or ''<struct-template block>'': any block-level element before the template will be closed before rendering; if using the capitalised version, the end tag must be ''</STRUCT-TEMPLATE>''

The data block can be pretty much any syntax from the [[plugin:struct:aggregation#table|struct table aggregation]]; each entry in the resulting data will be used once to render the template.

==== Value interpolation ====

Following the data block, the template will be interpreted as Wiki text in the normal DokuWiki format. Entries from the data can be used with a similar syntax to the struct value aggregation, but using a double dollar sign:

<code>
{{$$schema.column}}
{{$$%pageid%}}
</code>

Unlike the struct value aggregation, the schema must always be supplied. You can still use the actual struct value aggregation (''<nowiki>{{$[page].[schema].column}}</nowiki>'').

==== HTML template ====

If the [[config:htmlok|DokuWiki HTML OK configuration setting]] is enabled, you can add a flag to the opening template tag to interpret the template as HTML, without having to render the Wiki text. This can speed up processing by a lot on a page with a few templates on.

<code>
<struct-template inline html>
...
</struct-template>
</code>

The ''html'' option must come after the ''inline'' or ''block'' specifier.

===== Development =====

==== Change Log ====

[[https://github.com/iainhallam/dokuwiki-plugin-structtemplate/commits/main.atom|{{https://raw.githubusercontent.com/legacy-icons/famfamfam-silk/master/dist/png/feed.png?16x16&recache |Subscribe to 'Struct Template Plugin Change Log' by RSS}}]]

{{rss>https://github.com/iainhallam/dokuwiki-plugin-structtemplate/commits/main.atom date}}

==== Known Bugs and Issues ====

Please report bugs and issues at [[https://github.com/iainhallam/dokuwiki-plugin-structtemplate/issues]]

===== FAQ =====

//[discussions should ideally be deleted and turned into FAQ entries along the way]//

===== Discussion =====

Please sign your contribution with the button in the editor controls.