Template Tags category listing. ­ Textpattern CMS

FAQ: Template Tags

How do I do if_not_something?

QUESTION:

Is there a <txp:if_not_... /> tag?



ANSWER:

Textpattern includes a number of conditional txp:if_… tags.

All of the built-in conditional tags support the <txp:else /> tag. It works like this:

<txp:if_section name="about">
This section is "about"
<txp:else />
This section is not "about"
</txp:if_section>

To do if not section, simply leave the first part empty:

<txp:if_section name="about">
<txp:else />
This section is not "about"
</txp:if_section>

The same technique can be used with any <txp:if_...> tag.

if_category vs. if_article_category

QUESTION:

What’s the difference between <txp:if_category> and <txp:if_article_category>?
<txp:if_category> doesn’t seem to work!



ANSWER:

The txp:if_category tag refers to the URL of the current page – i.e. the ?c=mycategory part, if it’s present.

The txp:if_article_category tag refers to the categories associated with the current article in an article list or on an individual article page.

Is there a tag or attribute for..

QUESTION:

Is there a tag that does xyz?
What attributes are supported by which tags?



ANSWER:

The documentation at Textpattern Documentation is detailed and helpful. Even experienced users will probably learn something they didn’t already know.

The Textpattern Tag Reference describes almost every tag, organised by function. (It also includes an alphabetical tag list.)

Brand new tags and attributes might not be listed. Textpattern Documentation is a community effort, so if you find something missing, consider submitting some documentation yourself

How do I change the appearance of..

QUESTION:

How do I change the appearance of a particular tag?
How do I change the markup used by a particular tag?



ANSWER:

Most tags that display content with markup support some (though not necessarily all) of the following attributes:

  • wraptag – a tag that wraps around content; typically ul by default
  • classCSS class applied to the wraptag; typically uses the tag name by default
  • break – a tag used to wrap or separate each item in a list (of articles, links, etc); typically li by default
  • breakclassCSS class applied to each break tag

It’s not necessary to include < and > in these attributes. If you use the tag names only, Textpattern will handle common self-closing tags correctly. For example:

<txp:section_list wraptag="div" break="br" />

produces something like this, with <br /> tags following each item:

<div class="section_list">
<a href="/section1/">section1</a><br />
<a href="/section2/">section2</a><br />
</div>

While this:

<txp:section_list wraptag="ol" break="li" />

produces <li> tags that surround each item:

<ol class="section_list">
<li><a href="/section1/">section1</a></li>
<li><a href="/section2/">section2</a></li>
</ol>

A detailed list of tags and their supported attributes can be found in the Textpattern Tag Reference. The Attribute Cross Reference lists the tags that support each attribute.

How do I create navigation links?

QUESTION:

How do I link to sections?
How do I link to categories?
How do I link to static pages?
How do I make a menu of section links?



ANSWER:

Sections are usually the topmost navigation elements of your web site (more on site structure here). If you want a simple, automatic list of links to sections, use the section_list tag:

<txp:section_list wraptag="ul" break="li" />

This puts the links in an unordered list, so you can use CSS to alter the layout as required (see A List Apart for some examples).

For a popup selection list, use the popup tag:

<txp:popup type="s" />

If you want more control over the content of the list (to omit certain sections, or use a specific order), the best way is with the <txp:section /> tag (requires Textpattern 4.0.2+):

<ul>
<txp:section wraptag="li" link=1 title=1 name="about" />
<txp:section wraptag="li" link=1 title=1 name="articles" />
<txp:section wraptag="li" link=1 title=1 name="news" />
<txp:section wraptag="li" link=1 title=1 name="contact" />
</ul>

If you’ve created static pages, like an about or contact page, you can link to them by linking to the associated section:

<txp:section link=1 title=1 name="about" />
<txp:section link=1 title=1 name="contact" />

Category links are specified in a similar way. There’s a category_list tag:

<txp:category_list wraptag="ul" break="li" />

The popup tag can also be used for categories:

<txp:popup type="c" />

Please note however that categories are independent of sections. Both of these tags will link to a list of articles in all sections that belong to the selected category.

For more control, you can use the category tag (also requires Textpattern 4.0.2+):

<ul>
<txp:category wraptag="li" link=1 title=1 name="products" />
<txp:category wraptag="li" link=1 title=1 name="weather" />
<txp:category wraptag="li" link=1 title=1 name="photos" />
</ul>

Problems with nested txp:if_.. tags

QUESTION:

Some of my <txp:if_..> tags show up in the HTML output
Nested <txp:if_..> tags aren’t working as expected
Do nested tags work?



ANSWER:

Textpattern version 4.0.7 and later supports nested tags (i.e. one tag inside another) without any constraint.

Older versions of Textpattern had limited capabilities in this area. Upgrading to the latest Textpattern release is the recommended solution.

Nesting a tag inside itself did not work in older Textpattern releases before 4.0.7:

<txp:if_foo>
<txp:if_foo>
...
</txp:if_foo>
</txp:if_foo>

If an upgrade is beyond consideration, there are other ways to nest tags: To work around the problem, put the inner block in a Misc form and use output_form, like this:

<txp:if_foo>
<txp:output_form form="myform" />
</txp:if_foo>

myform:

<txp:if_foo>
...
</txp:if_foo>

Can I use PHP code in article bodies?

If the admin configuration option “allow_article_php_scripting” is on, < txp:php> @< /txp:php>@ is supported in article bodies. By default, PHP scripts are only run when the author of the article is a publisher or editor.

The user premissions required for PHP code in article bodies are defined in lib/admin_config.php, as 'article.php':

'article.php' => '1,2',

To allow different user levels to run PHP code in their articles, edit the levels (the comma-separated numbers) on that line. But be careful: this is a PHP file, so the syntax must be correct.

Textile

If you are using Textile, be sure to escape it:

notextile. <txp:php> // your PHP code </txp:php>

or you will end up with nasty errors like:

Parse error: parse error, unexpected ‘&’ in /path/to/your/site/textpattern/publish/taghandlers.php(2688) : eval()‘d code on line 2

Warning

By giving someone permission to run PHP code, you effectively give them permission to bypass all of Textpattern’s built-in security. Any user with permission to run PHP code can, intentionally or accidentally, modify or delete anything in your database, crash your site, and so on.

Using PHP code in Textpattern

QUESTION:

Why doesn’t $thisarticle work in my PHP code?
<?php ... ?> doesn’t work anymore!



ANSWER:

You can use PHP code in a Textpattern page template or form like this:

<txp:php>echo 'Hello world'; </txp:php>

Make sure you use <txp:php></txp:php> instead of <?php ... ?> or <? ... ?>.

There is an Advanced Preference that can be used to disable PHP code.

PHP code will also work inside an article body if Textpattern is configured to allow it. If you are using Textile, be sure to escape it:

notextile. <txp:php> // your PHP code </txp:php>

We strongly recommend you set your Production Status to Debugging when adding or modifying PHP code in Textpattern.

You can include() an external script, provided you understand how variable scope and include paths work. Your PHP code will not be executed in the global scope, so you’ll have to explicitly use the global keyword.

When including or opening a file from PHP, you’ll need
To see the current working directory and include path:

<txp:php>var_dump(getcwd(), get_include_path());</txp:php>

If your file resides in Textpattern’s admin folder, you can use the defined constant txpath to refer to that path – i.e. include(txpath.'/myfile.php');.

Please be aware that any PHP code you run from Textpattern, whether included directly in a page or in a separate file, will share database connections, function, variable and class names and so on with Textpattern. PHP doesn’t support separate namespaces, so it’s up to you to ensure there are no clashes.

Some caveats to be aware of when using <txp:php>:

Variable Scope

Your PHP code will not be executed in the global scope, so you’ll need to explicitly declare global variables as required. If you want to pass data between separate <txp:php> blocks, you’ll need to do something like this:

<txp:php>
global $foo;

$foo = 'bar';
</txp:php>
<txp:php>
global $foo;

echo $foo;
</txp:php>

Escaping to XHTML

While you can use multiple PHP blocks on a single page, each <txp:php>...</txp:php> block must be a valid block of code by itself. This means you can’t escape from PHP to HTML and back like you can with <?php ... ?>. This will not work:

<txp:php>if ($something) {</txp:php>
foo
<txp:php>}</txp:php>

Use something like this instead:

<txp:php>
if ($something) {
echo 'foo';
}
</txp:php>

Debugging

Other than the caveats listed above, Textpattern doesn’t interfere with your PHP code. If your code isn’t working as expected, you’ll need to use standard debugging techniques to find out what’s wrong.

If you’ve followed the recommendations above and set Production Status to Debug, Textpattern will set PHP’s error reporting settings to display all errors, warnings and notices. This should help you find errors like misnamed variables.

For other problems, the most effective debugging technique is also the simplest: good old fashioned debug printing. Use PHP functions like print(), var_dump() and var_export() to display important data at key points in your code.

Textpattern provides a handy function called dmp() that will display a message or array surrounded by <pre>...</pre> tags for easy viewing. For example:

<txp:php>
dmp('My php code');

global $thisarticle;

dmp($thisarticle);
</txp:php>

dmp() uses the print_r() function to display arrays, and print() for everything else.

PHP debugging techniques are described in more detail in this article.

Can I use txp tags in articles?

QUESTION:

Can I use Textpattern tags in article bodies?



ANSWER:

Some, but not all. In particular, <txp:article /> and <txp:article_custom /> usually won’t work at all, and are likely to fail in subtle ways if they do.

How do I use a custom date format?

QUESTION:

None of the date formats match the standard ones used in my locale.
My favorite date/time format isn’t in the list!
How do I use a custom date format for article or comment timestamps?



ANSWER:

Use <txp:posted format="%Y-%m-%d" /> or similar. See the PHP manual for a list of format specifiers.

Please note that Windows supports only a limited subset of format specifiers.

For information about displaying times and dates in different languages, see How do I display time and date formats in my local language?.

My dates look like 'Y m d'!

QUESTION:<txp:posted format="Y-m-d" /> doesn’t work!
My timestamp formats are broken after upgrading – they all show “Y-m-d”!

ANSWER:

The format characters changed around the RC3 release. The date() formats like ‘Y-m-d’ no longer work; they now use strftime() format characters instead.

The simplest fix is to go to textpattern > admin > preferences, select a new date format, and save the settings.

Why aren't the right articles showing up on my page?

QUESTION:

Why isn’t search working properly?
New articles don’t show up on my front page
Section and category browsing doesn’t work
‘older’ and ‘newer’ links don’t work



ANSWER:

These and similar problems are most commonly caused by replacing the <txp:article /> tag with <txp:article_custom />.

Always use <txp:article /> as the main article tag on your page. <txp:article_custom /> is for specialized use such as sidebars; think of it as an advanced version of <txp:recent_articles />.

For more information about the difference between the two tags, see FAQ: What does article_custom do?.

How do I change the output of txp:recent_articles?

Use <txp:article_custom /> instead, and create or edit a form to control the output. You can use any article tag in that form: <txp:title />, <txp:posted />, etc.

For detailed examples, see Customizing txp:recent_articles.