Advanced Formatting and code generation

All of the features on this page are now installed as a beta features on this server as of 2005-06-12.

This is the development page (or rather a hub for a number of separate development pages) for advanced Wikka formatting and other new or enhanced code "responsible" for generating valid XHTML in Wikka pages.

While the Formatter takes user-supplied source code in Wikka "markup" and turns it into XHTML, there are several actions and handlers also produce XHTML output directly: using core utility methods for this generation process helps to make such generated code structural, valid and consistent. This page deals with both aspects of Wikka since although they have different operation they are closely related in their purpose (and the Formatter also makes use of some of the core utility methods for its work).
 


The code written by JavaWoman (all now installed on this server as a beta feature) addresses several issues of the current formatter and other code generation. In particular, it fixes a number of small formatting bugs, and adds new important features - like automatic generation of ids for headers and forms - required both for XHTML compliance and for (later) extensions such as the ability to link to page fragments (often implemented through anchors though we've chosen the XHTML-strict compliant method of using fragment ids), which in turn will enable TOC's. More consistent generated code and generated ids will also enable advanced styling through CSS.

What's new


Much of this really isn't visible on the "surface", and you can't suddenly do new things yet; what we get instead is a number of enabling features that (will) make other things (visible things) possible, as well as ways to generate code more consistently and reliably. Some of it really is "formatting" (given page source with Wikka formatting codes, generating valid XHTML from it), some of it is just utility methods that can be called upon by the formatter as well as other methods, actions and handlers to help generating valid XHTML that provides "hooks" for styling and other things.

These "enabling" features mostly take the form of new and enhanced methods in the Wikka core:

The core: wikka.php


html_entity_decode()
This is new compatibility code (similar to mysql_real_escape_string()) to provide functionality used by wakka.php when generating ids for headings: the function html_entity_decode() is available as of PHP 4.3 but for older versions we provide a (near) equivalent alternative;

FormOpen()
A more advanced version of the FormOpen() method (see AdvancedFormOpen) which uses the new makeId() method (see GenerateUniqueId); it also supports more types of forms, including forms that allow file uplaods. The FormOpen() method is already used by many actions and handlers but with the extensions all code generating a form really should use this method together with its FormClose() counterpart since all forms type are now provided for. This will ensure consistent and valid code and make it easier to style forms.

makeId()
A new makeId() method with some supporting code (see GenerateUniqueId). From the docblock for the method:
Although - given Wikka accepts embedded HTML - it cannot be guaranteed that an id generated by this method is unique, it tries its best to make it unique:
  • ids are organized into groups, with the group name used as a prefix;
  • if an id is specified it is compared with other ids in the same group; if an identical id exists within the same group, a sequence suffix is added, otherwise the specified id is accepted and recorded as a member of the group
  • if no id is specified (or an invalid one) an id will be generated, and given a sequence suffix if needed
For headings, it is possible to derive an id from the heading content to support this, any embedded whitespace is replaced with underscores to generate a recognizable id that will remain (mostly) constant even if new headings are inserted in a page.
The method supports embedded HTML as well: as long as the formatter passes each id found in embedded HTML through this method it can take care that the id is valid and unique. This works as follows:
  • indicate an 'embedded' id with group 'embed'
  • NO prefix will be added for this reserved group
  • ids will be recorded and checked for uniqueness and validity
  • invalid ids are replaced
  • already-existing ids in the group are given a sequence suffix
The result is that as long as the already-defined id is valid and unique, it will be remain unchanged (but recorded to ensure uniqueness overall).


makeList() and makeMemberList()
Two new utility methods makeList() and makeMemberList() are so far only a draft form (see ArrayToList); they are able to generate a list from an array, with id and / or class attributes. Only 'flat' arrays supported for now; the intention is to enhance it with recursion to generate nested lists as well. From the docblock for the makeList() method:
Given an array, this method builds a simple unordered or ordered list with an id. Only a (simple) array is required which will generate an unordered list; optionally id, class, type of list and an indent level can be specified. For type 'menu' an unordered list is generated but with an id in group 'menu' instead of 'ul' or 'ol': this enables the list being styled as a menu.
Several existing actions could make use of these utilities, and work is in progress to adapt them to do this.
More on ArrayToList.

makeCols() and makeMemberCols()
Analogous to makeList() and makeMemberList(), two equally new utility methods makeCols() and makeMemberCols() provide a similar API to generate columns of data instead of a single list (see ArrayToColumns). The columns are implemented as floated divs instead of as a layout table, providing more structural and accessible code. From the docblock for the makeCols() method:
Given an array and number of columns, this method builds vertically-arranged columns (meaning they are read vertically, one by one) implemented as floated divs. Column width is derived from the specified number of columns, implemented as an embedded style because it's dynamically generated; left float is added to the style (hardcoded for now but alignment could become an option later).
Again several existing pieces of Wikka code could make use of these, with work in progress to implement this.
More on ArrayToColumns.

The Formatter: ./formatters/wakka.php


The Formatter has the responsibility to translate user-provided page code into valid XHTML. It's not perfect at this but it's getting a little better. Since some of the intended improvements required quite a bit of digging into the code, some work was also done to make that code a bit more readable, while the digging work also unearthed a few existing bugs (including unrecorded ones) that could now be solved.

All of this does not make an advanced Formatter but it does make our Formatter more advanced.
To make generating valid XHTML from Wikka code more reliable, a complete rewrite would actually be needed, but for now the following will at least get us closer, and help enable new features as well:

For details and code, see ImprovedFormatter.

The code


core formatter

CategoryDevelopmentFormatters CategoryDevelopmentCore
There are no comments on this page.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki