Snippet Limitations with 0.9.6

One limitation I found with the current method of snippet handling in MODx 0.9.6 is that a snippet cannot modify the current document output. I ran into this problem when I was working a Table Of Contents snippet that automatically injects ids into the <h*> tags of the current document for completely automated TOCs (much like how the mediawiki engine handles them). My question is will this limitation be eliminated in the core rewrite of 0.9.7?

If you want to modify the final output of a page in it’s entirety, you’d need to use a plugin attached to an event that occurs after all parsing is completed. A snippet, if called as the absolute last item on a page, would only be able to manipulate the final output if called uncached and during the last phase of processing, otherwise, it would only be acting on the partial content produced at that point in the parsing process. Since it would be quite unpredictable to decide when to manipulate the cacheable document content vs. the rendered document output, which are very separate and indispensable parts of the core engine, I do not see a reliable way of doing this except in very controlled situations where you intentionally force that snippet to be parsed last.

But I also don’t see injecting content as the best way to build such table of contents. Perhaps I’m missing part of the requirements though...

Yeah, what kind of TOC do you need?

Do you need it for some kind of Ajax magic?
I believe you can "inject" ids to any element you want via DOM-Scripting (JS). That would have to be at the end of the HTML, obviously.
You would basically query the HTML tree, and change/add stuff for those elements that you need.

Typically, in MODx you’d rather use Ditto for a regular TOC I guess...

Thanks Jason. For both commenters, here’s the TOC I’m creating. I’m not an AJAXer because I need to cater to a very large set of browsers, that is why the ids need to be hardcoded when sent to the browser. I solved my problem using a plugin quite some time ago but my ideal setup would be to use a snippet so that it would be easier for the editor to add a quick TOC to their page (much like the way MediaWiki uses the "[tt]__TOC__[/tt]" placeholder).

Let me start by saying the way I use TOC is not relative to the entire MODx site. I’m talking about a single page. Take for instance the following page generated by mediawiki: http://wiki.modxcms.com/index.php/Snippet_Toolkit.

You’ll notice that TOC is generated automatically. Now, since MW’s content is completely dynamic, adding a TOC is fairly simple. But since I have hardcoded <h*> tags in my MODx document, I need a method to add the required id parameter so that users/browsers can jump to that part of the document, which, of course, is simple using a plugin. The problem with using a plugin is that I need to set a custom placeholder in the document where I want the TOC to be located, this is the part where ideally I would like the snippet call to be. Does that make sense?

I’ll do some more research to see if this is possible and post my results. This really a "back burner" issue though. Thanks!

Well, technically speaking you don’t necessarily need IDs, but simple anchors.

I guess you could write something useful with those newish (since PHP 5) XML functions - if the document is XHTML and well-formed (all tags closed properly etc.)

e.g. http://ch2.php.net/manual/en/function.domdocument-create-attribute.php
http://www.topxml.com/php_xml_dom/dom_document_function_createcomment.asp

another question related to it:
if you use a plugin, which searches for <h*> tag, injects an anchor and fills a placeholder (?) with an TOC, how can you control on which pages the plugin should be executed?
Is there any possibility to choose on which pages a plugin should be executed and on which it shouldn’t?

Quote from: raum at Jul 11, 2007, 02:18 PM

another question related to it:
if you use a plugin, which searches for <h*> tag, injects an anchor and fills a placeholder (?) with an TOC, how can you control on which pages the plugin should be executed?
Is there any possibility to choose on which pages a plugin should be executed and on which it shouldn’t?

I wrote my own placeholder format: <!--toc:[options go here]:--> that the plugin searches for whenever a document is loaded. If it doesn’t find the placeholder then it stops.

I’ll be releasing this plugin soon. It’s built on my snippet toolkit script, which is still in testing. I estimate that as soon as Jason finishes transport packaging for 0.9.7 I will package the 8 MODx snippets/modules/plugins I created with my toolkit and release them all to the public.

Quote from: ganeshXL at Jul 11, 2007, 01:09 PM

Well, technically speaking you don’t necessarily need IDs, but simple anchors.

I guess you could write something useful with those newish (since PHP 5) XML functions - if the document is XHTML and well-formed (all tags closed properly etc.)

The problem is not that I don’t know how to insert the ids, it’s that when I do so using a snippet, those insertions are lost. Apparently, only plugins are allowed to edit the entire document Output.

I guess you could simply insert a "container" TV where you have your regular content, and then a snippet that first parses the TV, inserts all the stuff you want, and displays the "final" page (incl. TOC, anchors, IDs...)

Or: Use one doc per "chapter", all in one folder, and for the page you want to display, use two Ditto calls: one for the TOC, one for the actual content further down...
with custom Ditto-templates of course.

(these are just workaround suggestions, of course...)

Quote from: sirlancelot at Jul 11, 2007, 02:38 PM

The problem is not that I don’t know how to insert the ids, it’s that when I do so using a snippet, those insertions are lost. Apparently, only plugins are allowed to edit the entire document Output.

This is because you would have to work on the local variable $documentSource that is used to represent the content passed to the evalSnippets() function called from parseDocumentSource(). Plugins are provided a way to do this via $modx->documentOutput, but this a hackish approach IMHO. I’ll review the way 0.9.7 handles this and make sure there is a way to access the current state of the content/output via snippets; right now, the only issue would be deciding when to manipulate the content vs. the output, but I have an idea how to resolve that so the reference to the output available for mutation is consistent regardless of when in the process the snippet is parsed.