3.59. Pragma
Sets the default value of an Interchange pragma. The directive is set like this:
Pragma my_pragma_name
To enable a pragma for only a particular page, set it anywhere in the page:
[pragma my_pragma_name]
To disable a pragma for a particular page, set it anywhere in the page:
[pragma my_pragma_name 0]
Descriptions of each pragma follow.
dynamic_variables
dynamic_variables_file_only
init_page
Defines a Sub or GlobalSub which will run before page Variable processing. A *reference* to the contents of the page is passed to the routine.
For instance, if a page was found that did not have a @_VARIABLE_@ in it, you could wrap it with a template:
Pragma init_page=wrap_page
Sub <<EOS
sub wrap_page {
my $pref = shift;
return if $$pref =~ m{\@_[A-Z]\w+_\@};
$$pref =~ m{<!--+ title:\s*(.*?)\s+-->}
and $Scratch->{page_title} = $1;
$$pref = <<EOF;
\@_MYTEMPLATE_TOP_\@
<!--BEGIN CONTENT -->
$$pref
<!-- END CONTENT -->
\@_MYTEMPLATE_BOTTOM_\@
EOF
return;
}
EOS
post_page
Defines a Sub or GlobalSub which will run after page Variable processing but before tag interpolation. A
- reference* to the contents of the page is passed to the routine.
Example -- you want your users to be able to edit pages and just put in <A href="someotherpage.html">. You can use post_page to handle this. To do so, put in catalog.cfg:
Pragma post_page=relative_urls
### Take hrefs like <A HREF="about.html"> and make relative to current
### directory
Sub <<EOR
sub relative_urls {
my $page = shift;
my @dirs = split "/", $Tag->var('MV_PAGE', 1);
pop @dirs;
my $basedir = join "/", @dirs;
$basedir ||= '';
$basedir .= '/' if $basedir;
my $sub = sub {
my ($entire, $pre, $url) = @_;
return $entire if $url =~ /^\w+:/;
my($page, $form) = split /\?/, $url, 2;
my $u = $Tag->area({
href => "$basedir$page",
form => $form,
});
return qq{$pre"$u"};
};
$$page =~ s{
(
(
<a \s+ (?:[^>]+?\s+)?
href \s*=\s*
)
(["']) ([^\s"'>]+) \3
)}
{
$sub->($1,$2,$4)
}gsiex;
return;
}
EOR
pre_page
Defines a Sub or GlobalSub which will run after page Variable processing but before tag interpolation. A
- reference* to the contents of the page is passed to the routine.
no_image_rewrite
Prevents image locations in pages from being altered by Interchange. Added in Interchange 4.7.0.
Interchange normally rewrites image locations to point to ImageDir. This applies to image locations mentioned in <img src="...">, <input src="...">, <body background="...">, <table background="...">, and <tr/th/td background="...">.
When this pragma is not set, the following tag:
<img src="fancy.gif">
Would, assuming an ImageDir set to /foundation/images, be transformed into:
<img src="/foundation/images/fancy.gif">
When pragma no_image_rewrite is set, the <img> tag would remain unchanged.
safe_data
By default Interchange does not allow data returned from databases to be reparsed for Interchange tags. Setting the safe_data pragma eliminates this restriction.
If for some reason you want to have tags in your database, for example, to use [page ...] for catalog-internal hyperlinks in your product descriptions, you need to enable safe_data. Some things to consider:
- It may be better to use the safe_data attribute available to certain tags instead of the pragma, or perhaps to use [pragma] for a whole page or [tag pragma] ... [/tag] for a small block, instead of a catalog-wide Pragma directive.
- In any case it is strongly recommended that you surround the area with [restrict] ... [/restrict] tags to allow only the specific (hopefully relatively safe) set of tags you expect to appear, such as [page] or [area]. Expect security compromises if you allow [calc] or [perl], or other extremely powerful tags.
- Be certain that you know everywhere the data in your database will be used. Will it always be possible to reparse for tags? What about when it's used to create an emailed plain-text receipt -- will a literal '[page ...]' tag show up in the product description on the receipt? Would the desired output of '<a href="...">' be any better in a plaintext situation? What if you access your database from applications other than Interchange? You'll then have to decide what to do with such tags; perhaps you can simply strip them, but will the missing tag output cause you any trouble?
In short, safe_data is disabled by default for a reason, and you should be very careful if you decide to enable it.
(Watch out for parse order with [tag pragma] or [restrict] when used with lists that retrieve data from the database, as in [PREFIX-*] and the flypage. Loops parse before regular tags like [tag] and [restrict], and thus aren't affected by it.)
strip_white
Set this to strip whitespace from the tops of HTML pages output by Interchange. Such whitespace usually comes from Interchange tags at the top of the page. The pragma's purpose is mostly to make 'view source' in the browser a slightly more tolerable experience.
Default is off; whitespace is unchanged.