More Power to Smarty – Serendipity

I've patched up several of the functions (after the documentation effort) to allow some forward-compatibility features.

For that, I modified the core functions serendipity_fetchEntries() and serendipity_printEntries() and created a new Smarty function {serendipity_fetchPrintEntires} that interfaces with it.

The function serendipity_printEntries() can now much easier take on a list of parameters (through smarty, or even through your event plugins). With the help of judebert on the forums, I've introduced these new features for that function:

1. Be able to pass the $smarty_block parameter, which defines the parseable blockname of Smarty. Thus you can parse multiple instances of a entries.tpl file into multiple smarty blocks for later use.
2. The $smarty_fetch parameter can be used by plugins to prevent the use of the Smarty parse functions. Some plugins might want to not output their blocks straight ahead, but mangle them. So after the serendipity_printEntries() function is run, your plugin can do whatever it wants with it. Your plugin can then even use a different ".tpl" file to parse the data from.
3. The $use_hooks parameters enables you to prevent the execution of plugin hooks that might influence the display of your entry listing (like the comic plugin or a Page Nugget plugin). If you set this variable to false, it means that such plugins are not executed.
4. Via the $use_footer parameter you can disable executing plugins that listen on the footer event.
5. The most important new parameter is the $use_grouped_array one. Developers might know that serendipity_printEntries() mangles the input $entries array that comes from serendipity_fetchEntries, and it stacks the entries to be grouped by date. This ensures that you will only get the date header displayed once, even if you have multiple entries on that date. Exactly this functionality is responsible for the 2-level nesting of $dategroup and $entries within your entries.tpl file.
   And now for the new functionality. By setting this value to true you instruct the function to take the input $entries array as an already grouped input array.
   That again means, you can use whatever kind of grouping for your date to use. You could group your entries by category or even by author on your output template!
   If you submit $use_grouped_array = 'plugin' to the function, it will execute a plugin API hook ("entry_groupdata"), where you can use a plugin to regroup your input entry data, any way you like.

Even more, some new $serendipity control variables have been introduced. Those are:

1. $serendipity['skip_smarty_hooks']. If you set this boolean parameter to TRUE it will prevent the use of any {serendipity_hookPlugin} smarty function calls within your templates. Together with a plugin that uses serendipity_printEntries() this is very handy to prevent any HTML Page nugget or other plugins to show up if you don't want it.
2. $serendipity['skip_smarty_hook']. This variable holds an array of FORBIDDEN plugin API hooks to be used within {serendipity_hookPlugin}. So if you don't want to globally disable all hooks, you can restrict it to several special hooks.

Remember that both control variables can be set before the serendipity_printEntries() function call, and can (or need to) be reset after the function call again.

We're not trough yet! The genpage event hook (called before formatting any page) has been enhanced and received a new $addData array. This holds a variable $addDAta['startpage'] which is set to TRUE if the current page is the frontpage of your blog. Plugins like the staticpage plugin are already using this to detect the frontpage, but now it's a bit easier for plugin developers, as they don't need to duplicate code within their 'genpage' hook declaration.

Last, but not least, the most important new feature introduction, the {serendipity_fetchPrintEntries} Smarty function. You can use it within your entries to display a listing of other entry. So you can print a list of latest entries of all Author X on your frontpage, to highlight this author specifically. Or you can print the latest entries of Category X always on your frontpage, or print the latest entries in a different language [interaction through a plugin or your template's config.inc.php might be required at times]. The possibilities to use this to further customize your blog are endless. Read the parameter documentation and use the power!

All described functionality is part of Serendipity 1.0 development and has been committed to our SVN trunk repository. It is also part of the nightly snapshots created each day (wait for today's snapshot). If you want to discuss this feature in depth, or have specific questions, please come to the forums.

Have fun,
Garvin