Textpattern Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Textpattern Troubleshooting: Common Issues and Fixes

Debug analytics issues on Textpattern CMS — Txp tag conflicts with JavaScript, page template structure, plugin loading order, and article-level...

Textpattern CMS is a PHP-based CMS with its own XML-like tag language (Txp tags). Analytics issues on Textpattern primarily involve Txp tag parsing interfering with JavaScript, the page/form template hierarchy not including tracking code on all page types, and plugin conflicts.

Textpattern-Specific Debugging Approach

Textpattern uses a page template + form template system. Pages define the overall layout, and forms are reusable template fragments. Analytics code placement depends on understanding this hierarchy.

Check Template Output

# SSH into your Textpattern server

# Check rendered page for analytics
curl -s http://your-txp-site.com/ | grep -iE "gtag|gtm|analytics" | head -5

# Check the Textpattern diagnostic log
# In Textpattern admin: Admin > Diagnostics > check for warnings

Verify Page Template Structure

In Textpattern admin > Presentation > Pages, check your page templates. The analytics code should be in the page template that serves as the main layout, not in a section-specific template.

<!-- Example Textpattern page template structure -->
<!-- Check: Presentation > Pages > default -->
<html>
<head>
  <txp:css />
  <!-- Analytics code should be here -->
</head>
<body>
  <txp:output_form form="header" />
  <txp:article />
  <txp:output_form form="footer" />
</body>
</html>

Most Common Textpattern Analytics Issues

1. Txp Tag Parser Interfering with JavaScript

Symptoms: JavaScript errors in the console. Analytics code partially rendered or with unexpected content injected.

Root cause: Textpattern's tag parser processes all template content for <txp:> tags. While standard JavaScript does not typically conflict, certain patterns (especially in template strings or XML-like comments) can trigger the parser.

Fix: Place analytics JavaScript in a Textpattern form and include it, or use an external JS file:

<!-- In Presentation > Forms > create "analytics" form -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXX');
</script>

<!-- In your page template's <head>: -->
<txp:output_form form="analytics" />

2. Section-Specific Page Templates Missing Tracking

Symptoms: Analytics works on the homepage and default section but not on other sections (blog, about, contact).

Root cause: Textpattern assigns page templates per section. Each section can use a different page template. If analytics is only in the "default" page template, sections using other templates are untracked.

Diagnosis:

# Check which page template each section uses
# In Textpattern admin: Presentation > Sections
# Each section shows its assigned Page template

Fix: Either add analytics to all page templates, or use a shared form:

<!-- Create an "analytics" form (Presentation > Forms) with your tracking code -->
<!-- Then include it in EVERY page template's <head>: -->
<txp:output_form form="analytics" />

3. Article Forms Not Contributing to Head

Symptoms: Article-level tracking code (e.g., specific content dimensions) does not appear in the <head>.

Root cause: Textpattern article forms render inside <txp:article />, which is typically in the <body>. You cannot inject into <head> from an article form.

Fix: Use Textpattern's <txp:variable> system to pass data from articles to the page head:

<!-- In your article form, set a variable: -->
<txp:variable name="article_category" value='<txp:category1 />' />

<!-- In your page template <head>, read it: -->
<script>
var articleData = {
  category: '<txp:variable name="article_category" />'
};
gtag('event', 'page_view', { content_group: articleData.category });
</script>

4. Plugin Loading Order Conflicts

Symptoms: Analytics plugin is installed but does not output tracking code, or outputs it in the wrong location.

Root cause: Textpattern plugins have a load order (1-9). If an analytics plugin depends on another plugin's output, the load order matters.

Diagnosis:

# In Textpattern admin: Admin > Plugins
# Check the Order column for your analytics plugin
# Lower numbers load first

Fix: Set your analytics plugin's load order to 1 (loads first) to ensure it runs before any potentially conflicting plugins.

5. Clean URL Routing Affecting Page Path Tracking

Symptoms: GA shows URLs with /section/article-title structure that does not match the visible clean URLs.

Root cause: Textpattern's URL structure depends on the Permanent link mode setting (Admin > Preferences > Site). Different modes produce different URL patterns.

Fix: Verify your permanent link mode and ensure GA receives consistent paths:

// Use the canonical URL if available
var trackPath = document.querySelector('link[rel="canonical"]')?.href
  ? new URL(document.querySelector('link[rel="canonical"]').href).pathname
  : window.location.pathname;

gtag('config', 'G-XXXXXXX', { page_path: trackPath });

Environment Considerations

  • Flat learning curve: Textpattern is simple but its tag language has quirks. Always test template changes in preview before publishing
  • Shared hosting: Most Textpattern sites run on shared hosting. No CLI tools are available — all changes through the admin panel
  • Plugin ecosystem: Textpattern's plugin repository is small. Many analytics integrations are manual theme edits
  • PHP version: Textpattern 4.8+ requires PHP 7.2+. Older versions may have different template parsing behavior
  • No Composer: Textpattern does not use Composer. Plugins are installed via the admin panel's plugin installer

Performance Issues

  • LCP Issues - Template parsing and MySQL query overhead
  • CLS Issues - Layout shifts from plugin-injected content and form rendering

Tracking Issues

  • Events Not Firing - Debug section-specific template gaps, tag parser conflicts, and plugin load order
返回顶部