Text_Wiki 0.24.0 beta

I released a new version of Text_Wiki today composed of some bugfixes and functionality enhancements (all based on user requests, thanks everyone!).

The big deal is that Text_Wiki is “beta” now. Even though it doesn’t have all the renderers I would like, the API has proven stable and extensible. The full change notes are:

* fixed Bug:2670 (incorrect css_new case in “wikilink” xhtml renderer)

* fixed Bug:2916 (parser for “code” does not set all attributes)

* implemented Request:2947 (more flexible way to handle wikilinks) — the wikilink renderer now lets you specify a callback to determine if a page exists or not

* implemented Request:2917 (allow dot in interwiki regex parser)

* implemented Request:3162 (allow for additional punctuation in interwiki regex parser)

Text_Wiki is a PEAR package designed to parse wiki text into an intermediate format, and then render the parsed text into any supported output format (XHTML by default, but plain text and Latex are also supported, and RTF as well as other formats are expected in the future).

Savant 2.3.3 released

Savant version 2.3.3 is ready for download. The change notes are:

* the form plugin now defaults to null for “clear” and “float” on blocks; previous default settings would break surrounding CSS layout

* the form plugin now has added ‘layout’ setting; when false, no automatic layout is produced; default is true

* the form plugin now unquotes based on GPC -or- runtime magic quotes (becuase values may be coming directly from database)

* basic compiler now uses regular expressions to parse templates

* basic compiler has ‘strict’ flag to restrict the PHP used in a compiled template, but it’s not yet fully operational (chokes on some valid variable code, waiting for fixes in PHPCodeAnalyzer)

Savant3-3.0.0dev1

The first development release of Savant version 3 is ready for download. (Savant is a template system for PHP that uses PHP itself as the template markup language; it supports plugins and output filters, as well as optional compilers.) The following is a link to the PEAR package tarball.

http://phpsavant.com/Savant3-3.0.0dev1.tgz

The release rate for Savant has been very high (three major versions in 18 months). This is because had the bad luck (or poor foresight) to start Savant2 on the cusp of the PHP5 release, so it had to handle both PHP4 and PHP5. With any luck, Savant3 should be the last major version number until PHP6.

Some change notes follow, but they are not a replacement for examining the source code. As development progresses, I’ll write up real documentation.

CHANGE NOTES:

Savant2 code was 31793 bytes with comments; Savant3 is 23728 bytes with comments. This is not due to reduced comments. 😉

PHP5 only, uses public/protected (no private because we want to allow extension) and runs clean under E_ALL|E_STRICT error reporting.

Real unit tests using the .phpt framework. The ‘form’ plugin test fails becuase the test is not complete yet, but all others pass.

Reduced number of default plugins, mostly from the form element suite. The plugin ‘modify’ has been renamed to ‘safe’ but I’m not sure that will remain the case.

In Savant2, you were not supposed to assign a variable with a name starting in “_”. In Savant3, there no more restrictions on what you can name an assigned variable; any allowed PHP name is OK.

In Savant2, configuration properties were prefixed with underscore. In Savant3, config properties are stored as a static array inside the conf() method. This has the benefit of keeping all configs away from the assigned variable space (i.e., the object properties). Access only through public getters and setters (which are nominally dumb, but in this case are necessary).

The assign() and assignRef() methods work just like always, but return true/false instead of error objects.

Variable extraction is still allowed. Initially I disliked the idea, but the new configuration scheme allows a very simple and elegant extraction using extract() and get_object_vars($this).

Restricted directories are always on (i.e., Savant2::setRestrict(true) is always the case).

Filters are now simply callbacks; you can specify a function, static class method, or object instance method. The callback should take one parameter, the buffered template output.

Filters are now applied through the native PHP ob_start() callback system, so you can do more complex stuff like ob_gzhandler. However, it makes filters harder to debug, as they occur within the ob_start() process.

Compilers are now simply callbacks; you can specify a function, static class method, or object instance method. The callback should take two parameters, the path to the source template and a reference to the calling Savant object.

No more methods like clear() or getVars(); you can access all assigned variables as public properties of the template object.

No more loading or unloading of plugins or filters; all happens automatically. Once a plugin is instantiated, you cannot un-instantiate it.

Plugins always get a reference to the calling Savant object, just like in Savant1.

Plugin classes must use the method name as their “main” method instead of plugin(). E.g., the ‘form’ plugin uses form() instead of plugin() as the main method. This is because E_STRICT forces you to have the exact same number of parameters when extending a class.

Plugins are activated via the magic method __call(); thus, no more plugin() method per se. Plugin instance are stored in a static array inside __call(); they are not available to the rest of the object.

All plugins return instead of echo; to display plugin output, use “echo $this->pluginName()”. This is because of magic method __toString() requirements. Thus, no more splugin() method.

You can call display() and fetch() the way you did in Savant2, but you can also “echo $Savant;” as the equivalent of display().

The following old methods are rougly congruent to these new method names (this is only a partial list).

    Savant2::loadTemplate() ~= Savant3::template()
    Savant2::setError()     ~= Savant3::setErrorType()
    Savant2::loadPlugin()   ~= Savant3::setPluginConf()
    Savant2::loadFilter()   ~= Savant3::addFilters()
    Savant2::plugin('xxxx') ~= Savant3::xxxx()

Savant: Why Plugins?

A good question from the Savant-Talk list today. The quote is from the questioner, and the remainder is my response (almost verbatim from the list).

But could You PLS explain me shortly the main idea of plugins? I mean I can not understand that there is a need to create for example any html form fields by php… I still see the idea of templates as separation of business logic from display logic. From my point of view such example form fields shoud be still in template but not generated by php. So maybe such ones should be provided quite so as a templates or something like that. Only the values should come to them.

Well my wonders goes farther – why to use ANY php or savant function INSIDE template…(?)

First off, use of plugins is not required, of course, so if you don’t like them you don’t need to use them. This is kind of a weak argument, I know, because the code for plugin support is there whether you like it or not — in Savant3 this will end up being about 30 lines (with comments it’s about 50 lines), which I think is very small for the power you can get from them.

But second, and more importantly, they are convenient time-savers. I completely agree with you when you say you “see the idea of templates as separation of business logic from display logic.” To that, I say: a plugin is just an encapsulated, reusable portion of display logic. It gets tiresome to write forms by hand all the time. Instead of *having* to write a select box by looping through options passed in as an assigned variable, and mixing the PHP echo code with the literal HTML, you can use one line in the template to call the ‘form’ plugin and generate a select box with correct items pre-selected for you.

One argument against plugins is that they are not a necessary component of a template engine; if you want convenience methods, you can instantiate your own output objects and assign them to the template, or write them as global functions, or call them as static class methods. This is a perfectly valid argument. However, to my mind, that kind of thing is a “pattern” of development, and will end up looking nearly the same across all implementations. All that Savant does is take the common aspects of that pattern and codify them for common use so that different developers can collaborate easily and effectively using the same higher-level tool set.

This is not a comprehensive defense of plugins, but I hope this brief essay begins to show why plugins can be useful and worthwhile in a template system.

Savant3 and Unit Testing

I’m starting work on Savant3, which will be PHP5 E_STRICT compliant, and the work is going nicely; I should have an alpha release at the end of the week. This time around, I’m doing real unit tests, and I can now say I am a fan of unit testing. With Savant2, I used “eyeball” testing (described here) but that was no fun at all.

The real problem with unit tests is not writing them; in fact, it’s kind of fun trying to figure out how to break the library and then come up with a test for it. No, the trouble was figuring out how to *do* unit tests in the first place. After cursory reviews of SimpleTest and PHPUnit, I was less than enthusiastic; they are their own applications in many ways, and not that intuitive for the new unit-testing initiate (me).

However, the .phpt methodology easy to approach and apply … once I found it and figured out how to do it. There is some official documentation here (although it does not seem to be widely advertised), and a tutorial-like overview from Aaron Wormus here at the very end of the article.

Between those two pages, and a day spent experimenting, I am now putting together a unit test suite for Savant3. Let me tell you, it is *much* easier to call pear run-tests *.phpt than it is to load the individual Savant2 test pages in a browser and eyeball them for errors. I’m not sure how difficult it would be to apply unit testing to a complex application, but in a library with limited behaviors, it’s relatively easy to do and has a high reward-to-effort ratio.

Update (19 Jan, 23:15 CST): You can find the Savant3 CVS repository here.

YaWiki 0.20 released

I have just released YaWiki 0.20. The change notes are:

* Added “create new page” link in the authentication box, so you can create a new page directly instead of having to edit an existing page (requires Javascript)

* Added “edit this page” link in the authentication box, so you don’t need to scroll all the way down to end of the page

* Can now specify i18n strings for submit buttons (Save, Cancel, Delete, etc) and scripts will honor them. See the new Yawp.conf-dist.php file for more information. Per request from Heiner Gassen.

* History links to older page versions now bring up the proper version, not the current version. Per note from Lukas Smith.

YaWiki 0.19 alpha released

YaWiki is a wiki-ish CMS, or CMS-ish wiki, primarily for collaborative documentation efforts; it uses Yawp and PEAR as its foundation.

This release adds an enhancement that was removed in earlier versions. The AreaMap page, which allows you to add navigational hints such as tabs and sidebars, now allows you to specify an optional navigation title for the element. This was available in early versions YaWiki, before it supported freelinks; after freelinks became available, navigation element titles were taken from the page title. Due to consistent user feedback, it appears I was unwise to take away the alternate titling, so now it’s back. Use a pipe character (“|”) on an AreaMap line to indicate the navigation title; e.g., “HomePage | Welcome!” will link to the home page, but the navigation element text will be “Welcome!” regardless of what the HomePage page title is.

You can view the list of changes for this release here.