01102: Break FPLTemplate function into several functions to create development hooks

Summary: Break FPLTemplate function into several functions to create development hooks
Created: 2009-06-26 11:02
Status: Closed - added for 2.2.5
Category: CoreCandidate
From: HansB
Priority: 444
Version: 2.2

Description: I suggest to break the FPLTemplate function into 5 subfunctions, defined in an array and called as a chain:

SDV($FPLTemplateFunctions, array(
   'FPLTemplateLoad',      //load pagelist template
   'FPLTemplateDefaults',  //add any defaults from template to options
   'FPLTemplatePageList',  //make pagelist, calls MakePageList(), merges with previous list 
   'FPLTemplateSliceList', //slice pagelist according to start= and count= parameters
   'FPLTemplateFormat'));  //construct and return HTML formatted output 

Cookbook.FPLTemplate provides a recipe implementing this as an alternative FPLTemplate function. I created this as a "proof-of-concept", with the hope it will be implemented in the core. It will add some functionality with a small core code increase.

  • Original function broken into 5 (sub-)functions, called in a chain, offering possibilities of adding custom functions into the chain.
  • Additional pagelist supplied by custom function can be merged with list returned by MakePageList() function
  • Additional {$$PageListCount} template variable, giving total count of pagelist before any slicing into chunks.
  • Additional optional start= parameter for (:pagelist:)
  • Additional optional (:template none:) as template section for the case of "no matches"

See also discussion on pmwiki-devel list topic FPLTemplate() Revision

Hi Hans and thanks! This function seems really good: great job! Would it be better if we call each function with an additional &$output variable and let the function append/prepend/modify it as it wishes? Currently, we just glue together any output from these functions. I also wonder is the start=5 parameter required, if we already have count=5.. which does the same thing? (OTOH, a custom user function could honor any additional parameter it needs.) I am also considering using 'fname'=>number indexes in the $FPLTemplateFunctions array, to simplify the insertion of a custom function between any two. --Petko June 27, 2009, at 02:13 AM

Re: &$output
The 5 functions change different variables, handed along as different parameters ($matches, $opt, $tparts). Only the last one produces HTML output, returned as $out.

  1. FPLTemplateLoad() sets $tparts (template parts)
  2. FPLTemplateDefaults() sets $opt (template options)
  3. FPLTemplatePageList() sets $matches (pagelist matches)
  4. FPLTemplateSliceList() reduces $matches according to start= and count= parameters
  5. FPLTemplateFormat() produces formatted output

Of course we could add $out to the parameters, even though output is only created in the last function. But it would give the possibility of a custom function adding or changing the formatted output.

Re: start= and count= parameters
I found it very helpful to have a separate start= option together with count= , and have the $matches sliced accordingly: the slice starts at start and goes for count matches. I used it in Cookbook.BreakPageList, which is perhaps the only recipe so far using the alternative Cookbook.FPLTemplate we discussing here as core candidate.

Re: 'fname'=>number index
Anything making it easier to insert a custom FPLTemplate subfunction is most welcome! In Cookbook.BreakPageList I had to redefine the whole $FPLTemplate for array to insert one custom function. - HansB June 27, 2009, at 04:30 AM