Revision history for AdvancedFormatter
Revision [23471]
Last edited on 2016-05-20 07:38:48 by BrianKoontz [Replaces old-style internal links with new pipe-split links.]Additions:
//All of the features on this page are now installed as a [[WikkaBetaFeatures | beta features]] on this server as of 2005-06-12.//
These "enabling" features mostly take the form of new and enhanced methods in the [[Docs:WikkaCore | Wikka core]]:
===The core: [[WikkaCore | wikka.php]]===
This is new [[CompatibilityCode | 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;
These "enabling" features mostly take the form of new and enhanced methods in the [[Docs:WikkaCore | Wikka core]]:
===The core: [[WikkaCore | wikka.php]]===
This is new [[CompatibilityCode | 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;
Deletions:
These "enabling" features mostly take the form of new and enhanced methods in the [[Docs:WikkaCore Wikka core]]:
===The core: [[WikkaCore wikka.php]]===
This is new [[CompatibilityCode 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;
Revision [21339]
Edited on 2011-02-15 09:35:39 by BrianKoontz [Replaces old-style internal links with new pipe-split links.]Deletions:
Revision [21334]
Edited on 2011-02-15 04:07:49 by GarethBerns [Replaces old-style internal links with new pipe-split links.]Additions:
[[http://iresearchpapers.com/order.php order term papers]]
Revision [18545]
Edited on 2008-01-28 00:11:57 by JavaWoman [Modified links pointing to docs server]Additions:
These "enabling" features mostly take the form of new and enhanced methods in the [[Docs:WikkaCore Wikka core]]:
Deletions:
Revision [9964]
Edited on 2005-07-14 17:41:33 by JavaWoman [added and improved features for the Formatter]Additions:
~- better closing of open tags at end of document, including open indents and lists (a long-standing bug!) ''Now improved''
~- better handling of nested lists so change of list "type" is actually detected and coded correctly; also produces nicely-formatted HTML code for lists and indents now, especially more readable for nested lists. ''New!''
~- better handling of nested lists so change of list "type" is actually detected and coded correctly; also produces nicely-formatted HTML code for lists and indents now, especially more readable for nested lists. ''New!''
Deletions:
Additions:
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 ##id##s 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 **id**s//), which in turn will enable //TOC//'s. More consistent generated code and generated ids will also enable advanced styling through CSS.
Deletions:
Additions:
//All of the features on this page are now installed as a [[WikkaBetaFeatures beta features]] on this server as of 2005-06-12.//
Revision [9129]
Edited on 2005-06-11 09:35:22 by JavaWoman [moving formatter details to ImprovedFormatter page]Additions:
~- using single quotes wherever possible making [[RegEx]]es and generated HTML easier to read;
For details and code, see ImprovedFormatter.
For details and code, see ImprovedFormatter.
Deletions:
==Heading ids==
Creating ids for headings is (you guessed it) the first (and necessary) piece of the puzzle to enable generating [[TableofcontentsAction page TOC]]s, but other bits will be needed for that as well, such as actually **gathering** the references to headings (and their levels), and the ability to **link** to page fragments (something our [[WikkaCore current core]] does not support yet). So: we cannot generate TOCs - yet - but we are getting there; the code is also designed to make it possible to extend it to generate TOCs not just for headings, but also for things like images, tables and code blocks.
A method for generating a TOC has not been decided yet (we may even provide alternatives), but one thing we //certainly// need is ids for headings (see TableofcontentsAction for more background on this); and even if we do not (yet) generate a TOC, being able to link to a page fragment (the obvious next step) will be useful in itself.
Some thought went into the method of generating the ids: Ideally they should be 'recognizable' so creating links **to** a page fragment with a heading wil be easy, and they should be as 'constant' as possible so a link to a section //remains// a link to //that// section, even if that is moved to a different position on the page, or another is inserted before it. This implies that all methods that simply generate a sequential id will not fulfill our requirements. We also don't burden the writer with coming up with ids (or even needing to think about them): they should be able to just concentrate on the **content**. Instead, we use following approach:
~-The actual content of the heading is the basis for the id: this makes it very likely the id wil remain the same even if page sections are re-arranged or new sections inserted.
~-A heading may contain images; if the images have an alt text, they are replaced by this (after all, alt text is meant for precisely that: to replace an image where it cannot be shown!); all other tags are simply stripped.
~-A heading may also contain entity references; where possible these are translated into ASCII letters (using ##html_entity_decode()##) while all other ones are removed.
~-Any character (except whitespace) that is not valid in an id is then removed: the result is a string that consists only of characters valid for an id - but it could now possibly be an empty string
~-A valid id can only contain letters, numbers, dashes, underscores and periods, and must start with an (ASCII) letter; this implies that spaces (and whitespace in general) is not allowed. However, the ##""makeId()""## method tackles this by first transforming all whitespace into underscores.
~-The resulting string is examined for uniqueness within the group of "heading" ids; if necessary, a sequence number is added, or a new id hash is generated.
The result is an id that is almost always derived directly from the heading content, giving a high chance that it will remain constant even if the page content is re-arranged: thus it provides a reliable target for a link.
Additions:
=====Advanced Formatting and code generation=====
~-ImprovedFormatter
>>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).::c::
~-The Formatter - see ImprovedFormatter
~-ImprovedFormatter
>>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).::c::
~-The Formatter - see ImprovedFormatter
Deletions:
>>This is the development page (or rather a //hub// for a number of separate development pages) for an advanced Wikka formatter and other new or enhanced code "responsible" for generating valid XHTML in Wikka pages.
While the Formatter takes user-supplied source code and turns it into XHTML, 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.::c::
~-The Formatter - //later
Additions:
>>This is the development page (or rather a //hub// for a number of separate development pages) for an advanced Wikka formatter and other new or enhanced code "responsible" for generating valid XHTML in Wikka pages.
While the Formatter takes user-supplied source code and turns it into XHTML, 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.::c::
While the Formatter takes user-supplied source code and turns it into XHTML, 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.::c::
Deletions:
While the Formatter takes user-supplied source code and turns it into XHTML, several actions and handlers also produce XHTML output: using core utility methods for this generation process helps to make such generated code structural, valid and consistent.::c::
Additions:
~-A heading may also contain entity references; where possible these are translated into ASCII letters (using ##html_entity_decode()##) while all other ones are removed.
Deletions:
Revision [8930]
Edited on 2005-06-07 19:29:25 by JavaWoman [reference to CompatibilityCode + layout]Additions:
//core//
~-CompatibilityCode
//formatter//
~-CompatibilityCode
//formatter//
Revision [8929]
Edited on 2005-06-07 19:27:03 by JavaWoman [reference to CompatibilityCode + extra category]Additions:
This is new [[CompatibilityCode 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;
~-**##html_entity_decode()##** - see CompatibilityCode
CategoryDevelopmentFormatters CategoryDevelopmentCore
~-**##html_entity_decode()##** - see CompatibilityCode
CategoryDevelopmentFormatters CategoryDevelopmentCore
Deletions:
~-**##html_entity_decode()##** - //later//
CategoryDevelopmentFormatters
Additions:
~-ArrayToColumns
==##""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 ##div##s 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.
~-**##""makeList()""##** and **##""makeMemberList()""##** - see ArrayToList
~-**##""makeCols()""##** and **##""makeMemberCols()""##** - see ArrayToColumns
==##""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 ##div##s 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.
~-**##""makeList()""##** and **##""makeMemberList()""##** - see ArrayToList
~-**##""makeCols()""##** and **##""makeMemberCols()""##** - see ArrayToColumns
Deletions:
Additions:
Creating ids for headings is (you guessed it) the first (and necessary) piece of the puzzle to enable generating [[TableofcontentsAction page TOC]]s, but other bits will be needed for that as well, such as actually **gathering** the references to headings (and their levels), and the ability to **link** to page fragments (something our [[WikkaCore current core]] does not support yet). So: we cannot generate TOCs - yet - but we are getting there; the code is also designed to make it possible to extend it to generate TOCs not just for headings, but also for things like images, tables and code blocks.
Deletions:
Revision [8906]
Edited on 2005-06-07 10:40:15 by JavaWoman [also mention makeMemberList(); extended heading and intro]Additions:
=====Advanced Formatter and code generation=====
~-ArrayToList
>>This is the development page (//stub//) for an advanced Wikka formatter and other code "responsible" for generating valid XHTML in Wikka pages.
While the Formatter takes user-supplied source code and turns it into XHTML, several actions and handlers also produce XHTML output: using core utility methods for this generation process helps to make such generated code structural, valid and consistent.::c::
==##""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:
Several existing actions could make use of these utilities, and work is in progress to adapt them to do this.
More on ArrayToList.
~-**##""makeList()""##** and **##""makememberList()""##** - see ArrayToList
~-ArrayToList
>>This is the development page (//stub//) for an advanced Wikka formatter and other code "responsible" for generating valid XHTML in Wikka pages.
While the Formatter takes user-supplied source code and turns it into XHTML, several actions and handlers also produce XHTML output: using core utility methods for this generation process helps to make such generated code structural, valid and consistent.::c::
==##""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:
Several existing actions could make use of these utilities, and work is in progress to adapt them to do this.
More on ArrayToList.
~-**##""makeList()""##** and **##""makememberList()""##** - see ArrayToList
Deletions:
>>This is the development page (//stub//) for an advanced Wikka formatter and other code "responsible" for generating valid XHTML in Wikka pages..::c::
==##""makeList()""##==
The new utility method **##makeList()##** is so far only a draft form (see ArrayToList); it is 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 method:
Several existing actions could make use of this utility, and work is in progress to adapt them to do this.
~-**##""makeList()""##** - see ArrayToList
Additions:
The new utility method **##makeList()##** is so far only a draft form (see ArrayToList); it is 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 method:
~-**##""makeList()""##** - see ArrayToList
~-**##""makeList()""##** - see ArrayToList
Deletions:
~-**##""makeList()""##** - //later//
Additions:
CategoryDevelopmentFormatters
Deletions:
Additions:
~-AdvancedFormOpen
~-GenerateUniqueId
>>This is the development page (//stub//) for an advanced Wikka formatter and other code "responsible" for generating valid XHTML in Wikka pages..::c::
The code written by JavaWoman (tested and ready to be 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 ##id##s 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 **id**s//), 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 [[WikkaCore Wikka core]]:
===The core: [[WikkaCore 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()""##==
The new utility method **##makeList()##** is so far only a draft form; it is 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 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 this utility, and work is in progress to adapt them to do this.
===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:
~- better closing of open tags at end of document, including open indents and lists (a long-standing bug!);
~- escaping single & (not part of an entity) (another long-standing problem);
~- ability to nest one type of float within another (so a right float can contain a left float and vice versa)
~- handling ids (and making them unique) as provided in embedded code, using the ##""makeId()""## method;
~- creating ids for headings based on content ('afterburner' type formatting so this //includes// originally embedded code); this code not only uses the ##""makeId()""## method but also the ##html_entity_decode()## method in PHP versions older than 4.3.
==Heading ids==
Creating ids for headings is (you guessed it) the first (and necessary) piece of the puzzle to enable generating [[TableofcontentsAction page TOC]]s, but other bits will be needed for that as well, such as actually **gathering** the references to headings (and their levels), and the ability to **link** to page fragments (something our [[WikkaCode current core]] does not support yet). So: we cannot generate TOCs - yet - but we are getting there; the code is also designed to make it possible to extend it to generate TOCs not just for headings, but also for things like images, tables and code blocks.
A method for generating a TOC has not been decided yet (we may even provide alternatives), but one thing we //certainly// need is ids for headings (see TableofcontentsAction for more background on this); and even if we do not (yet) generate a TOC, being able to link to a page fragment (the obvious next step) will be useful in itself.
Some thought went into the method of generating the ids: Ideally they should be 'recognizable' so creating links **to** a page fragment with a heading wil be easy, and they should be as 'constant' as possible so a link to a section //remains// a link to //that// section, even if that is moved to a different position on the page, or another is inserted before it. This implies that all methods that simply generate a sequential id will not fulfill our requirements. We also don't burden the writer with coming up with ids (or even needing to think about them): they should be able to just concentrate on the **content**. Instead, we use following approach:
~-The actual content of the heading is the basis for the id: this makes it very likely the id wil remain the same even if page sections are re-arranged or new sections inserted.
~-A heading may contain images; if the images have an alt text, they are replaced by this (after all, alt text is meant for precisely that: to replace an image where it cannot be shown!); all other tags are simply stripped.
~-A heading may also contain entity references; where possible these are translated into ASCII letters while all other ones are removed.
~-Any character (except whitespace) that is not valid in an id is then removed: the result is a string that consists only of characters valid for an id - but it could now possibly be an empty string
~-A valid id can only contain letters, numbers, dashes, underscores and periods, and must start with an (ASCII) letter; this implies that spaces (and whitespace in general) is not allowed. However, the ##""makeId()""## method tackles this by first transforming all whitespace into underscores.
~-The resulting string is examined for uniqueness within the group of "heading" ids; if necessary, a sequence number is added, or a new id hash is generated.
The result is an id that is almost always derived directly from the heading content, giving a high chance that it will remain constant even if the page content is re-arranged: thus it provides a reliable target for a link.
~-**##html_entity_decode()##** - //later//
~-**##""FormOpen()""##** - See AdvancedFormOpen
~-**##""makeId()""##** - see GenerateUniqueId
~-**##""makeList()""##** - //later//
~-The Formatter - //later
~-GenerateUniqueId
>>This is the development page (//stub//) for an advanced Wikka formatter and other code "responsible" for generating valid XHTML in Wikka pages..::c::
The code written by JavaWoman (tested and ready to be 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 ##id##s 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 **id**s//), 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 [[WikkaCore Wikka core]]:
===The core: [[WikkaCore 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()""##==
The new utility method **##makeList()##** is so far only a draft form; it is 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 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 this utility, and work is in progress to adapt them to do this.
===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:
~- better closing of open tags at end of document, including open indents and lists (a long-standing bug!);
~- escaping single & (not part of an entity) (another long-standing problem);
~- ability to nest one type of float within another (so a right float can contain a left float and vice versa)
~- handling ids (and making them unique) as provided in embedded code, using the ##""makeId()""## method;
~- creating ids for headings based on content ('afterburner' type formatting so this //includes// originally embedded code); this code not only uses the ##""makeId()""## method but also the ##html_entity_decode()## method in PHP versions older than 4.3.
==Heading ids==
Creating ids for headings is (you guessed it) the first (and necessary) piece of the puzzle to enable generating [[TableofcontentsAction page TOC]]s, but other bits will be needed for that as well, such as actually **gathering** the references to headings (and their levels), and the ability to **link** to page fragments (something our [[WikkaCode current core]] does not support yet). So: we cannot generate TOCs - yet - but we are getting there; the code is also designed to make it possible to extend it to generate TOCs not just for headings, but also for things like images, tables and code blocks.
A method for generating a TOC has not been decided yet (we may even provide alternatives), but one thing we //certainly// need is ids for headings (see TableofcontentsAction for more background on this); and even if we do not (yet) generate a TOC, being able to link to a page fragment (the obvious next step) will be useful in itself.
Some thought went into the method of generating the ids: Ideally they should be 'recognizable' so creating links **to** a page fragment with a heading wil be easy, and they should be as 'constant' as possible so a link to a section //remains// a link to //that// section, even if that is moved to a different position on the page, or another is inserted before it. This implies that all methods that simply generate a sequential id will not fulfill our requirements. We also don't burden the writer with coming up with ids (or even needing to think about them): they should be able to just concentrate on the **content**. Instead, we use following approach:
~-The actual content of the heading is the basis for the id: this makes it very likely the id wil remain the same even if page sections are re-arranged or new sections inserted.
~-A heading may contain images; if the images have an alt text, they are replaced by this (after all, alt text is meant for precisely that: to replace an image where it cannot be shown!); all other tags are simply stripped.
~-A heading may also contain entity references; where possible these are translated into ASCII letters while all other ones are removed.
~-Any character (except whitespace) that is not valid in an id is then removed: the result is a string that consists only of characters valid for an id - but it could now possibly be an empty string
~-A valid id can only contain letters, numbers, dashes, underscores and periods, and must start with an (ASCII) letter; this implies that spaces (and whitespace in general) is not allowed. However, the ##""makeId()""## method tackles this by first transforming all whitespace into underscores.
~-The resulting string is examined for uniqueness within the group of "heading" ids; if necessary, a sequence number is added, or a new id hash is generated.
The result is an id that is almost always derived directly from the heading content, giving a high chance that it will remain constant even if the page content is re-arranged: thus it provides a reliable target for a link.
~-**##html_entity_decode()##** - //later//
~-**##""FormOpen()""##** - See AdvancedFormOpen
~-**##""makeId()""##** - see GenerateUniqueId
~-**##""makeList()""##** - //later//
~-The Formatter - //later
Deletions:
The code written by JavaWoman (tested and ready to be installed on this server as a beta feature) addresses several issues of the current formatter. In particular, it fixes a number of small formatting bugs, and adds new important features - like automatic generation of ##id##'s for headers and forms - required for XHTML compliance and for extensions like //anchors//, //TOC//'s and advanced styling through CSS.
====What's new ====
==wikka.php==
~- compatibility code (like ##mysql_real_escape##) used by ##wakka.php## when generating ids for headings;
~- revised ##""FormOpen()""## using ##makeId()##;
~-**##makeId()##** and its supporting code:
~~//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).//
~-a first draft of **##makeList()##** to generate a list from an array (only 'flat' arrays supported for now);
~~// 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.
//
== ./formatters/wakka.php==
~- better closing of open tags at end of document, including open indents and lists;
~- escaping single & (not part of an entity);
~- handling ids (and making them unique) in embedded code;
~- creating ids for headings based on content ('afterburner' type so this includes originally embedded code)
(forthcoming)
Additions:
~~//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:
~-a first draft of **##makeList()##** to generate a list from an array (only 'flat' arrays supported for now);
~~// 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.
//
~-a first draft of **##makeList()##** to generate a list from an array (only 'flat' arrays supported for now);
~~// 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.
//
Deletions:
~-a first draft of ##makeList()## to generate a list from an array (only 'flat' arrays supported for now);
Additions:
~-**##makeId()##** and its supporting code:
~~//Although - given Wikka accepts can use 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).//
~~//Although - given Wikka accepts can use 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).//
Deletions:
Additions:
~-TableofcontentsAction
Additions:
=====Advanced Formatter=====
>>==See also:==
~-WantedFormatters
~-WikkaExtensibleMarkup
~-AcronymFormatter
>>This is the development page (//stub//) for an advanced Wikka formatter.::c::
The code written by JavaWoman (tested and ready to be installed on this server as a beta feature) addresses several issues of the current formatter. In particular, it fixes a number of small formatting bugs, and adds new important features - like automatic generation of ##id##'s for headers and forms - required for XHTML compliance and for extensions like //anchors//, //TOC//'s and advanced styling through CSS.
====What's new ====
==wikka.php==
~- compatibility code (like ##mysql_real_escape##) used by ##wakka.php## when generating ids for headings;
~- revised ##""FormOpen()""## using ##makeId()##;
~-##makeId()## and its supporting code;
~-a first draft of ##makeList()## to generate a list from an array (only 'flat' arrays supported for now);
== ./formatters/wakka.php==
~- using single quotes wherever possible making regexes and generated HTML easier to read;
~- better closing of open tags at end of document, including open indents and lists;
~- escaping single & (not part of an entity);
~- handling ids (and making them unique) in embedded code;
~- creating ids for headings based on content ('afterburner' type so this includes originally embedded code)
====The code ====
(forthcoming)
----
>>==See also:==
~-WantedFormatters
~-WikkaExtensibleMarkup
~-AcronymFormatter
>>This is the development page (//stub//) for an advanced Wikka formatter.::c::
The code written by JavaWoman (tested and ready to be installed on this server as a beta feature) addresses several issues of the current formatter. In particular, it fixes a number of small formatting bugs, and adds new important features - like automatic generation of ##id##'s for headers and forms - required for XHTML compliance and for extensions like //anchors//, //TOC//'s and advanced styling through CSS.
====What's new ====
==wikka.php==
~- compatibility code (like ##mysql_real_escape##) used by ##wakka.php## when generating ids for headings;
~- revised ##""FormOpen()""## using ##makeId()##;
~-##makeId()## and its supporting code;
~-a first draft of ##makeList()## to generate a list from an array (only 'flat' arrays supported for now);
== ./formatters/wakka.php==
~- using single quotes wherever possible making regexes and generated HTML easier to read;
~- better closing of open tags at end of document, including open indents and lists;
~- escaping single & (not part of an entity);
~- handling ids (and making them unique) in embedded code;
~- creating ids for headings based on content ('afterburner' type so this includes originally embedded code)
====The code ====
(forthcoming)
----
Deletions:
>>==See also:==
Documentation: xxxxxActionInfo.>>This is the development page for the xxxxx action.::c::
//This page is a **template**. It belongs to CategoryTemplate (which contains more handy templates). To create an action development page, [[http://wikka.jsnx.com/ActionTemplate/clone clone this page]] to a page called **xxxxxAction** (where xxxxx is the (capitalized) name of the action), replace all occurrences of 'xxxxx' with the name of the action and replace this paragraph with the actual content.//
----
