Template & Fmt
Documentation > Concepts > Search > Template & Fmt
Summary
This page shows you how to control search results using BoltWire's templating. To understand this page you first need to read Search.
Example
BoltWire has a powerful templating engine you can use to format search results. To use it, set [(search template=somevalue)]
The best way to understand Templating search results is to take a look at action.changes code.
<code>
| Page | Date Modified | Change Summary |
|---|---|---|
| info.pagefail | 06/18/13 | |
| member.thelma32mcdonald | 06/16/13 | |
| member.patricemiranda | 06/15/13 | |
| info.pagecount | 06/15/13 | |
| docs.extend.create_bf | 06/15/13 | Page edited by Caveman. |
| docs.handbook.markups | 06/15/13 | Page edited by argaso. |
| member.gillespieadriana26 | 06/15/13 | |
| member.sosa25araceli | 06/15/13 | |
| member.dixonadeline25 | 06/15/13 | |
| member.rst616 | 06/15/13 | |
| test.badbox | 06/13/13 | Page edited by NoSpam. |
| member.yuiio | 06/13/13 | |
| member.jacmgr | 06/13/13 | |
| member.holmes27lily | 06/12/13 | |
| member.joygarner21 | 06/12/13 | |
| member.jacquelineirwin25 | 06/12/13 | |
| member.marciemunoz25 | 06/12/13 | |
| member.richfrancisca34 | 06/12/13 | |
| member.petradiaz19 | 06/12/13 | |
| member.flores26elsa | 06/12/13 |
| Page | Date Modified | Change Summary |
|---|---|---|
| {+:changesummary} |
It starts with a search query, sorts the results showing lastmodified first, only the first 20 and using template=changes.
As you may have noticed, in this example the change template is hidden on the same page as the search query. In cases where a template is used by several search queries, it is best to store in a shared template.changes page.
Note: it is also possible to insert a template directly in the search function by using a fmt parameter. For example, [(search fmt="[[{+p}|+]]")] is essentially the same as the "title" template built into BoltWire. This makes simple templates easy to generate.
Several system templates exist including:
| count | count number of pages |
| csv | a csv list of pages |
| list | a vertical list of pages |
| title | returns a list of clickable page titles |
| toc | A nice indented table of contents list |
| default | returns a breadcrumb of each page (default template) |
Note: some templates only work with template=, not fmt=. Some work with either. See below for and explanation.
How it works
In the changes template above, BoltWire will use [(template first)] to start the template, which is a table. Because changes are not just one, but the last 20, BoltWire needs to know how to display _each_ of them. It will use [(template each] which is a row, 3x a cell, each cell containing info we want to see and finally we close our table with [(template last)]
Other options include [(template group)] which is triggered every time the page switches to a different parent group. And even [(template 5)] or [(template 7)] for the fifth or seventh entry, respectively.
Hierarchical
BoltWire treats template values the same as Hierarchical Groups.
Simpely put it will search for a template in this order:
template.yourvalue
template.yourpage
template.default
First it will search for template.yourvalue, if not found, it will look for the exact same page as entered and use it as template. Finally, if no template is found it will use template.default.
Below in Advanced you can read how BoltWire actually looks for a search template.
Note: template and fmt use the same order
Template vs. Fmt
The difference between template and fmt is how it handles each "hit".
hit is click on a button, submitting a search for example.
Templates handles a hit like this:
- you click on search button
- BoltWire runs through the entire markup engine (markup.php) for each page in the output
- the finished html is all assembled and returned
fmt handles a hit like this:
- you click on search button
- results are generated without any markup being rendered
- main markup engine then renders the output normally with the rest of the page content.
Using fmt instead of template basically saves time and (server) resources and produces significantly faster results. The disadvantage is any markups in the output that are processed before the search is called will be ignored (though special rules allow for some limited variables). So use fmt when possible. If you find markup not being rendered properly, try switching to template.
Template Selection
Below is how BoltWire actually looks for a template. It's pretty complex, but for those who are experienced using BoltWire it might be helpful. new users are advised to use the simple explanation above.- if an action, look on the action page for an anchored section with the templatename.
- Looks for an anchored section on the current page with the templatename.
- Looks on template.templatename.skinname
- Looks on template.templatename
- Looks for the actual page "templatename" if it exists and you have view permissions
- Uses the actual content of the template itself (also called an inline template).
Template Development
Templates will either be injected wholesale into each page, or you can customize it into sections to be injected at certain places. Some of these divisions include:
Beginning of the output
Content shown when switching to a new page group
General content for each page returned
Special output for the third return
Shown at the end of the output
And these vars (can be used with or without +)
{count} Matches currently returned
{count_total} Total pages searched for criteria
{count_matches} Total pages matching criteria
{prev} Previous page name
{next} Next page name
{index} Index number before any sorting or reordering
To refer to current page in the template use these. Without the + you get the base page with the search on it.
{+p}, {+p1}, {+title}, {+:data}, {+::info} etc
To pass parameters from the search string to the template use
$count
$template
There are also several parameters that can be set in a search function to control output, such as:
join= (the code between each hit, normally a line break)
markuptable=reload (rerun whole markup table on output (fmt/template))
escape=true/false (do escape the output (fmt) or don't escape (template))
There's also {+prev} {+next} {+count} {+count_total} &
{+count_matches} template vars available (template only)
And with all functions there are several output= options
output=false (some functions true)
output=source
output=nolines
output=csv
output=escape
