Textpattern: Context in depth Page 8 of 8 «
Developer notes
Advanced Txp users and plugin developers may be interested in details of the mechanisms Txp uses to pass context to and from tags.
Txp variables for page context
Hoist by my own petard, I am now stuck between two meanings for “global”: global as in context vs. global as in PHP variable. For this page, I will revert to my alternate term “page context” to refer to the global context, using “global” in the PHP sense.
Each page-context element has an associated global variable. The preText() function in publish.php is where Txp translates the URL into values for these variables, thus establishing the page context. (They are all listed, near the top of the function, as arguments to makeOut().) Each variable has the same name as its corresponding query string parameter.
The following table shows each variable, with a brief description, and also the core tags, if any, for displaying the value directly and for checking for it in the page context.
| Name | Description | Output tag | Page-context tag |
|---|---|---|---|
id |
article ID | article_id |
if_individual_article |
s |
section | section |
if_section |
c |
category | category |
if_category |
context |
category content type | if_category |
|
q |
search query | search_term |
if_search |
m |
search match type | ||
pg |
page number | ||
p |
image ID | ||
month |
date | ||
author |
article or image author | if_author |
They are available as global variables throughout script execution. (As a rule you should never change the value of a core global.)
You can get the value of any page-context global with the page_url tag, setting its type attribute to the variable name. E.g., <txp:page_url type="p" /> returns the value of the $p global. By combining this technique with variable and if_variable, you can make tags to show and test for any page-context element, no plugins or raw PHP required. For example:
<txp:variable name="global_image_id" value='<txp:page_url type="p" />' />Depending on the condition you want to check, this may be preferable even for elements with built-in tags. For example, if_individual_article evaluates to true if the $id global has a value, except when inside an article_custom tag. That’s because it checks against the $is_article_list global, not $id. If, for some reason, you need to check for page-level article context from within a custom list, if_individual_article is no help and you need to check $id directly.
Txp arrays for passing current context
Txp uses a different set of global variables for passing data between tags. For example, images loops over its set of images, outputting each one by populating the global $thisimage array (i.e., creating a local context for the image), then parsing the form (or images container-tag contents). The image-context-sensitive tags inside the form use the data in $thisimage. After the last image, images resets $thisimage to its original value.
A reasonably complete list of such context arrays includes:
$thisarticle
$thisimage
$thislink
$thisfile
$thispage
$thiscomment
$thiscategory
$thissection
When there is page-level article context (i.e., an individual article page), $thisarticle is populated in preText(), before template processing. This means that all article data is available at any point in the page template. It is the only one of these arrays that is ever populated before the template begins.
In all other cases (including article list pages), you must create local context by adding a suitable tag to the page template, as in the images example above.
Page-level image context, i.e., the $p global, is a special case: a tag sensitive to page-level image context (currently just image_display) doesn’t use the $thisimage array. $thisimage is new in Txp 4.3.0 and this behavior may change.
Pagination context is also a special case, in that once $thispage is set, it cannot be overridden (not by any current core tags, that is). article does not need to be configured to do this; it automatically attempts to set $thispage (unless type="sticky"). The other tags capable of setting $thispage — images, file_download_list, and linklist — only attempt to do so if both limit and pageby are set. The first such tag sets the pagination context for the page, and that’s it.
Posted 2011-01-09 (last modified 2017-02-18)
