If your Textpattern CMS instance is customised in any way, and it’s very likely it will be customised, then you may occasion have to troubleshoot to resolve problems with your code. Although Textpattern tags are generally straightforward to use and adapt for your particular site, even seasoned professionals come unstuck on occasion. If something is not working as you expect it to, or you’re not entirely sure why something’s happening the way it is, a tag trace is useful.
A tag trace is useful insofar as it outputs a bunch of diagnostic information into the browser page source as a comment. Textpattern support folks, myself included, will ask for a tag trace if the answer is not immediately obvious from your question. If you want to have a good understanding of how Textpattern works then the process of running a tag trace is a very valuable thing to know. Before I explain, it’s important to know that this tag trace is useful for Textpattern diagnostics. Your readers won’t need it, and appending a bunch of text to the end of a web page will make it larger. More text in a page means the browser has more to download and process, and the end user will have to wait longer for the page to finalise loading. In addition, Textpattern does additional work to construct the tag trace, and that work is computationally expensive compared to building a standard page layout. To that end, consider a tag trace to be a one-off thing to perform when you’re troubleshooting, and not for your website users.
To enable a tag trace, go to the admin-side of Textpattern and then visit Admin → Preferences → and find Production Status in your localised language. There are three options here, again in your localised language where appropriate:
For a tag trace, choose Debugging, then click or tap Save. Then, visit the URL on your site that’s causing you a problem. It it’s a Textpattern-powered URL, a tag trace will appear at the end of the page source. Depending on your page and form constructs, it could be trivial, big or enormous. A tag trace starts with the database stats and activity:
<!-- Runtime: 0.0237 --> <!-- Query time: 0.006405 --> <!-- Queries: 16 --> <!-- Memory: 4899Kb, <txp:if_article_category number="2"> --> <!-- txp tag trace: [SQL (0.00047492980957): select name, data from txp_lang where lang='en-gb' AND ( event='public' OR event='common')] [SQL (0.000107049942017): select name, code, version from txp_plugin where status = 1 AND type IN (0,1,5) order by load_order] [SQL (0.000123977661133): select page, css from txp_section where name = 'default' limit 1] [SQL (0.000401973724365): select host from txp_log where ip='192.168.1.1' limit 1] [SQL (0.000334978103638): insert into txp_log set `time`=now(),page='/',ip='192.168.1.1',host='test.example.org',refer='',status='200',method='GET'] [SQL (0.000152111053467): select user_html from txp_page where name='default'] [Page: default]
…and then jumps into your Textpattern tags:
<txp:lang /> <txp:text item="lang_dir" /> <txp:page_title /> <txp:if_search> [<txp:if_search>: false] <txp:if_category> [<txp:if_category>: false] <txp:if_author> [<txp:if_author>: false] </txp:if_author> </txp:if_category> </txp:if_search>
Note the use of square brackets: this indicates the outcome of `txp:if_` tags. In the example above, all the `txp:if_` tags evaluate to `false`. Further down the tag trace is another chunk of text:
<txp:if_section name=""> [<txp:if_section name="">: true] <txp:site_url /> </txp:if_section>
Note the `true` evaluation. This text checks to see if the URL being viewed is the root of the website, and it is – hence the `true` evaluation. When you tally up the tag evaluation with the code you’ve written, it’s often clear where something has gone wrong. Knowing how to do this tag trace and either examining it before your ask for help, or alternatively provide it with your support question will often save you time and illicit a more prompt response. When you’re done troubleshooting, switch the mode back to Live and your site will purr happily without bolting on reams of diagnostic text.