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.




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;
        <!--BEGIN CONTENT -->
        <!-- END CONTENT -->



Defines a Sub or GlobalSub which will run after page Variable processing but before tag interpolation. A

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



Defines a Sub or GlobalSub which will run after page Variable processing but before tag interpolation. A


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.


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:

  1. 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.
  2. 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.
  3. 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.)


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.