Join Now

Click here to join our
growing community:

JOIN LOGIN



Docs

Welcome Tour
Handbook
      Markups
      Variables
      Conditions
      Functions
      Forms
      Commands
      Concepts
Extensions
Pro Modules
Developers



Copyright © 2020
Terms of Use
Privacy Policy
BoltWire

Handbook

List

List is a powerful command/function that allows you to take a comma separated list of values and run them through BoltWire's report engine. It is more often used as a function.

Here's a simple function to illustrate how it works:

[(list bob,mary,dave,sue fmt='[[~{+p}]]')]

This takes each name and runs it through the report engine to generate this output. I've escaped it so you can see the connection with the fmt.

[[~bob]]
[[~mary]]
[[~dave]]
[[~sue]]

Note: Though in this example, each item is a user id, the report engine treats them as a page. This is the reason for {+p}.

Instead of a list, you could point the function to a page containing a list of names and each line becomes an item in the list. For example:

[(list page=group.editor fmt='[[~{+p}]]')]

This generates the same report, except it uses the ids of all your site editors.

A third option is to run the script through a series of numbers:

[(list for=1100-1200 fmt='[[forum.{+p}]]' if='exists forum.{+p}')]

This function returns links to any forum pages that exist between forum.1100 and forum.1200 (inclusive).

Note: You can change the delimiter separating each item in the list to something beside ',' by adding a delimiter parameter. If you are doing a list from a page, you can similarly change the delimiter from the default line break to something else.

You can generate the list any number of ways. Say for example you wanted to create a list of plugins. The {plugins} system variable is already a csv list. Just do this:

[(list {plugins} fmt='{+p}')]

You can also use another function to generate a csv list and then drop it into the list function. For example:

[(list '{(info list page=info.counter)}' fmt='{+p}')]

Because the info function uses a format processed earlier in the markup table, it is called first and all the fields on the counter page are returned as a csv list. Then shortly after, the list function is called and it generates a report using each of those fields.

The List Command

The list command works exactly as the list function, except it is processed after a form is submitted and can be modified based on user input. Suppose for example you had a friends page (info.friends), with info vars tracking each user's friends as a csv list. It might contain information like:

bob: mary,jane,mark
mary: bob,mark,david
sue: david
david: jane,mark,fred

I can give the user the ability to decide which person's friend list to display:

[form]
Choose a name:  [radio id bob] Bob   [radio id mary] Mary   [radio id sue] Sue   [radio id david] David
[submit]
[command info field={=id} page=info.friends output=csv]
[command list '{=info}' fmt={+p}]
[command passdata list mode=post]
[form]

{?list}

The user selects a person. Then the info command uses that id to retrieve the specified friends list. The output=csv parameter is only added to help ensure it is formatted properly. Then the list command grabs the list and uses it to generate a report (basically a list of the id's). Passdata then sends that information back to the page when it reloads on form submission, and the post variable picks it up and displays it.

For the sake of illustration, the same thing could be done with this approach:

[form]
Choose a user:  [radio id bob] Bob   [radio id mary] Mary   [radio id sue] Sue   [radio id david] David
[submit]
[command passdata id]
[form]

[if set {?id}]<(list '{info.friends::{?id}}' fmt={+p})>[if]

Here, the id is selected and only it is passed back to the page. When the page reloads, the conditional sees that the id has been set and the list is generated. In many cases it is easier to use a function than a command.

Refining Your List

The list function sends your raw list of items through the same filtering system used by the search function/command. This means you can modify the list of items returned by any of the following parameters:

include=some.page,another.page
add these items to those already in the list

exclude=some.page,another.page
remove these items from the list

type=info,index
return only pages whose last page part is info or index

type=-header,footer,side
remove all pages of that page type

type=number
only return pages whose last page part is a number

sort=false
do not alphabetize the list

sort=random
shuffle the order of the list

sort=lastmodified
list pages modified most recently first

sort={+p} or {+field} or {+2}, etc
sorts the output based on various vars

order=reverse
reverse the order of the list

when='number {+p2} && more {+p2} 1200'
only returns pages with p2 > 1200 (can use any conditional).

count=10
only return first 10 items

count=10-20
return items 10-20

count=false
return all items (ignore searchlimit in site.config, or default of 50).

Note: The sort parameter can recognize a wide variety of values including most data, page, and template variables. If a query, it also knows {+field}, {+value}, {+value::2} or its equivalent{+2}. You can also try {+group}, {+lastmodified} and possibly others.

Generating the Report

Once the items in the list are established, and the results refined, the function sends them over to the report engine. This engine is very powerful and gives you a wide very variety of options. See the tutorial for more information. Here's a brief summary:

You can use either a template or a fmt to generate the report. Templates run each item through the entire BoltWire markup engine and allow maximum versatility. It can be inline (defined in the function/command) or you can refer to a template page. The fmt returns raw markup back to the page and the BoltWire markup engine simply completes its cycle for the entire page. This is far faster, but it only allows you to include markup in the fmt that has not already been processed. So in general, templates are safer, fmts are faster.

If neither the template or fmt parameter is defined, list tries to set fmt to the value of parameter 2. If that returns blank, it defaults to fmt={+p}.

Several templates/fmts are built into BoltWire. You can set either template or fmt to any of these:

count - returns total number of hits
csv - returns a csv list of hits
list - returns a line of items separated by linebreaks
title - returns a list of titles linked to the pages
toc - returns a list of links indented by {p0}
default - returns a list of breadcrumbs

Note: the default for the list command/function is list. For the search command/function, it uses default.

Join

Normally each item in the output is joined together by a simple line break. You can change what joins them by resetting the join parameter. For example, [(search pages=a,b,c join=' | ')] will generate: a | b | c. To eliminate any delimiter set join=false.

Tables & Columns

You can create a table easily by using the following format. It supplies the opening and closing table markups, and each item generates a row. If you want to customize the table, you can set its attributes in the table parameter, like table='border=1' instead of table=true.

[(search bob,joe,dave fmt='
{+p} {~{+p}:phone}' table=true)]

If you have a short output (like title or {+page}), you can set cols=3 (or some other number) and a table will be generated with an equal portion of elements in each column. If you want special formatting for the table, you can add a table='some parameters' to the function as well. You do NOT need to put table=true for columns.

Formats

Suppose you set fmt=mydisplay. BoltWire first looks for an anchored section on the current page (or the action page if you are calling an action). Then it tries to find template.mydisplay. Finally it looks for a page called mydisplay. If none of these can be found, it will use the letters "mydisplay" as your fmt. You can of course put your fmt value directly in the fmt parameter. That's called an inline fmt.

Once BoltWire has a fmt value, it applies this value to each item in the list and links them together using the report delimiter (usually a line break). BoltWire then does whatever processing remains for the page on the output. This requires you to be familiar with the markup table to see which rules follow the function calling the list, and which are before. For long reports, the speed advantages of fmts over templates are significant.

If you want to freeze the list output and stop all further processing use output=escape or escape=true.

The following template replacements are available to your fmt through some special code in the BoltWire report engine:

{+p} = The current item
{+p0} = The number of page parts
{+p1}, {+p2} = Individual page parts
{+page} = Last page part
{+count} = Return 7 if the seventh item
{+prev} = The item immediately preceding
{+next} = The next item
{+group} = The current page minus the last page part
{+first} = The first item in the report
{+last} = The last item in the report
{+matches} = Total number of items

You can also insert any parameter in the command/function directly into the fmt/template. So if you added color=red to the list command/function, you could put {+color} in the fmt and it would be replaced with red.

Templates

Templates are similar to fmts. BoltWire looks for a value in the same locations as fmts, and if nothing is found, it too will use an inline template. Once it has its value it applies it to each item in the report. However, it runs the entire markup table on each item, meaning you can use any markup and create as elaborate a template as you wish. Another difference is that the output is escaped by default. Though not recommended you can turn this off by setting escape=false.

All the template replacements available for fmts (see above) are also available for templates. If you set query=some.page (and that page has items in your list as info fields), the following template replacements become available:

{+field} = the page name
{+value} = the corresponding info value
{+value::1} = the correspondng info value, part 1
{+#1} = the corresponding info value, part 1

If you use a full template, rather than an inline template you can greatly customize your report. For example, you can modify the report for the first item, the last item, for each new group, and even for specific items. You can also control what to display if there are no matches. Here's an easy example of a full template:

[(list bob,mary,sue,dave template=profile)]

/*
[[#profile]]
[(template first)]Welcome to my profile report!
[(template each)]{+p}
Phone: {~:phone}
Email: {~:email}
Address: {~:address}
[(template last)]Printed <(time %x)>
[(template none)]No records found...
[[#end]]
*/

The template is defined by the anchor and continues to the next anchor. It is hidden in comment markups, so the template is not visible on the page.

This particular template creates a nice header, displays each members id, phone, email and address drawn from the member page, and then the date is printed. If no matches are found. If there were more than one group in my list, I could have added a [(template group)] option to insert something between each change of page groups. If I wanted to display something special for sue, I could have added [(template 3)]. Actually, that would apply to mary, because once the output is alphabetized, mary will be number three.