The ListPages module is an incredibly powerful tool that easily lists pages according to specific criteria. This is useful for wikis with massive contributions, personal blogs, notebooks, and more. One of the best parts is that the displayed info on each page can be formatted to your tastes. Making the pages display in a customized table, however, can be sort of tricky. In this how-to, we will show you how to quickly make a custom table which displays your pages and their respective info.

Understanding prependLine, appendLine, and separate

First, you should know about three very special ListPages attributes which makes table creation possible. Those attributes are the prependLine, appendLine, and separate. Simply, prependLine defines what content comes before the displayed list. The appendLine, in contrast, defines content that comes after the displayed list. These will allow you to open and close tables later in the tutorial.

The other attribute is separate. By default, when the module lists your pages, the terms are broken up into individual div blocks. This puts spaces in between entries. What you want for a table to display correctly, however, is for those spaces to disappear. Fortunately, applying separate="false" as a criterion will eliminate this mysterious space and hence make tables possible.

You can see these three commands in action below:

Here is the code:

 [[module ListPages category="howto" limit="5" prependLine="How Tos" appendLine="There are more..." separate="false"]] * %%title_linked%% [[/module]]

The Simple Table

Before going on to complex tables, let's try to understand how this works. Pretend that we have three how-tos to list, and we want them displayed in a table like the below:

Title	Author	Age
Title 1	Author	Age
Title 2	Author	Age
Title 3	Author	Age

This is called a simple table, since it uses the simple table syntax (see simple tables). And interestingly, they are simple to construct with ListPages. The headings can be defined in the prependLine section of the attributes. Since simple tables do not need to be closed, appendLine for now will sit out. The separate="false", however, is a must!

The following code will do the trick:

 [[module ListPages category="howto" limit="3" prependLine="||~ Title||~ Author||~ Age||" separate="false"]] ||%%title_linked%%||%%created_by%%||%%created_at|%O old%%|| [[/module]]

This will generate a table, shown below:

Hopefully you can see that table creation in ListPages is not terribly difficult. However, the goal is to make a customized table where you can define things like width and color. Let's see how to do that.

Custom Tables at Last

Let's begin with the end in mind. We want a table using ListPages that looks like this:

So, using the above knowledge on ListPages, its attributes, and simple table creation, let's find a way to make this work.

Step 1: Make an Include

First, you need to make an incomplete table. That's right: incomplete. When we stick it into the ListPages module, the module will complete the table for us, so for now, we want to make just part of the table, namely the headings.

Make a separate page and title it whatever you want. For this tutorial, we'll call this page inc:custom-table. On this page, you are going to make the first row of the table, which constitutes the headings. When you are making this table, do not close the table. Essentially, what you will have is an opened table with a full row, like the below:

 [[table style="width: 100%;"]][[row style="font-weight: bold; background-color: #B8D1DD;"]][[cell style="padding: 0 2px; width: 50%;"]]Title[[/cell]][[cell style="padding: 0 2px; width: 25%; text-align: center;"]]Author[[/cell]][[cell style="padding: 0 2px; text-align: right;"]]Age[[/cell]][[/row]]

We closed the row, but not the table. Save that page and remember the page name.

Step 2: Define prependLine

Now, we are going to install this heading into the ListPages using prependLine.

Wait a minute… why did we make a separate page for this? Could we have just opened the table by directly putting the code into prependLine? The answer is no, unless you have no styling or classes. When you define your table and then additionally define a style, you are using quotes (""). ListPages uses these same quotes! Therefore, the module might confuse the beginning of a style statement with the end of an attribute definition. Therefore, making that separate page was entirely necessary.

Here is what you do: put this into the prependLine.

 prependLine="[[include inc:custom-table]]"

Note: Replace inc:custom-table with the page name (in the URL) of the page you created in step 1.

This way, ListPages will insert your heading without the interference additional quotes might pose.

Step 3: Define appendLine and separate

This is easier. Place the following into your list of ListPages criteria:

 appendLine="[[/table]]" separate="false"

Step 4: Define the Body

Now for the meat of the table. In the simple table example, you saw how we used the simple table syntax between the [[module]][[/module]] tags to help construct a table. If we are using a custom table, we are going to use the custom table syntax.

Each item will be its own row, so the "sandwiched" part will have a single [[row]] and [[/row]], with cells in between corresponding to the headings. You can style this however you wish. Just make sure your headings and body match!

Here is the code we used above for the table:

 [[row]][[cell style="vertical-align: top;"]]**%%title_linked%%**[[/cell]][[cell style="vertical-align: top; text-align: center;"]]%%created_by%%[[/cell]][[cell style="vertical-align: top; text-align: right;"]]%%created_at|%O old%%[[/cell]][[/row]]

Step 5: Admire your Handiwork

After that, you are done! You can double check that the table looks the way you want and tweak it if it needs improvement. You can furthermore add embellishments and other styling, such as the Table Alterations snippet which will help you alternate row colors.

Here is the overall code that we used for the table:

 [[module ListPages category="howto" limit="5" prependLine="[[include inc:custom-table]]" appendLine="[[/table]]" separate="false"]] [[row]][[cell style="vertical-align: top;"]]**%%title_linked%%**[[/cell]][[cell style="vertical-align: top; text-align: center;"]]%%created_by%%[[/cell]][[cell style="vertical-align: top; text-align: right;"]]%%created_at|%O old%%[[/cell]][[/row]] [[/module]]