• View
• Edit
• History
• Attach
• Print

00774: Pagelist format not found behavior

Description:

Exists as the (:template none:) directive in PageListTemplates.

Currently, if a pagelist directive refers to a non-existent format, the directive returns the Site.PageListTemplates page (or whatever page is setup to be the last page searched), which can be confusing and unexpected.

Stated another way, if a page contains the following pagelist directive:

The result will look the same as if the following pagelist were specified:

Results

The result is probably not what any user expects and does not really convey the feeling that the format was missing, but rather that some strange looping or include interaction is occuring. Assuming that the behavior could be changed, here are some alternatives that might be more understandable and expected:

1. Display no content (a blank page)
2. Display some meaningful content (a passive error message)
3. Process the pagelist using the default format (as if no fmt parameter had been specified), or
4. Combine a default format with some message (at the begining or end) that reports that the specified format was not found.

Methods

As for the methods for accomplishing these, here are some suggestions:

• To display a blank page, add $ttext = ''; as the last line of the following loop in pagelist.php:

  foreach ($tname as $t) {
    $t = FmtPageName($t, $pagename);
    if (!PageExists($t)) continue;
    if ($qf) $t .= "#$qf";
    $ttext = IncludeText($pagename, $t, true);
    if (!$qf || strpos($ttext, "[[#$qf]]") !== false) break;
  }

• To enable all of the results identified above (blank, message, default, or default+message), Pm could add a new page (Site.PageListNotFound?) to the $FPLTemplatePageFmt array (and distribution) whose content would control the results of pagelists that specify non-existent formats. Presumably that page would have to be setup to be the last page searched. The advantage of this is that the specialized purpose of the page would be readily apparent and, as a result, the fact that its content might depart from the standards that ordinarily apply to all other pagelist templates might be more acceptable.
• A alternative to enable all of the results without adding a new page to the $FPLTemplatePageFmt array (and distribution) would be to simply use the top of the existing SitePageListTemplates page to control the results of a pagelist that refers to a non-existent format. The advantage of this approach is clear: it makes use of existing code and distributed pages. The disadvantage is simply due to the fact that the markup departs from that of other template formats, as identified below.
• In either case, the content of the relevant page could control the results. In each instance, it is important that the content appears at the very top of the page and does not include either the starting anchor nor the escape codes ("[@") commonly used in ordinary pagelist template formats (unless testing confirms that the results are acceptable).
  1. To display a blank pagelist

(:if equal {<$Group}:)
[[#notfoundend]]

• This particular conditional is not required, but the workaround breaks if the anchor is on the first line. All that is required is a simple (:if:) or some non-displaying markup, e.g. (:comment :), (other than an escape sequence), or even "non-repeating" character, e.g. a space, that prevents the anchor from ending up on the first line. Of course, the page could also be left completely blank. See the following note for more on repeating characters.

2. To display a message

(:if equal {<$Group}:)
Inline message to be displayed when specified pagelist format not found.
[[#notfoundend]]
(:if:)

• This condition, or its companion, (:if equal {>$Group}:) are required to prevent the message from looping and displaying for each page returned by the underlying pagelist directive.

3. To display the pagelist using a simple format

(:if equal {<$Group}:)
* [[{=$FullName}]]
[[#notfoundend]]
(:if:)

• Note, don't forget that closing (:if:) (otherwise the entire page will be blank).

4. To display a message and pagelist

(:if equal {<$Group}:)
Message to be displayed
(:if ! equal {$Name} PageListTemplates:)
* [[{=$FullName}]]
[[#notfoundend]]
(:if:)

• Note, the second condition is added to prevent the markup from being interpreted and displayed on the SitePageListTemplates. Of course, if used in a new page (Site.PageListNotFound), the name of that page would have to be substituted. In either case, the conditional serves to prevent the markupp from being rendered on the relevant template page and could be omitted if it was acceptable to have the markup rendered. And, again, the closing (:if:) is important, particularly on the Site.PageListTemplates page.
• The advantage of using this last result in the distributed page is that it is the most inclusive and can be transformed to yield any of the other results simply by removing lines.

Note, there is more than one way to mess up a format parameter and the above discussion just addresses a couple of them (fmt=#nonexistent and fmt=#typo). Other ways to screwup a format include omitting the pound sign (fmt=simple) and misnaming the parameter frm=#simple), each of which should return a blank pagelist (unless, of course an existing page name is referenced, e.g. if a page called simple exists in the first example).

Consistency with Includes

Pm mentioned on this post to the list that

I note that an include to an existent page that specifies a non-existent anchor seems to behave the same as a pagelist, in that a reference to PageName#nonexistentanchor behaves like a reference to PageName#, in that both will stop including content when they encouter any anchor.

I've often found myself frustrated by this. If I specify a nonexistent format then I'd like to be informed of it by error message. I've made a mistake and I should be told so I can fix it -- I can't imagine a situation where I entered a specific format and would want something else (using a default format, etc.) to happen. To me the error message is the only reasonable alternative -- anything else is just going to confuse people, I think...

Peter Bowers September 05, 2008, at 09:10 AM