Darren Ferguson - Blog

08 April 2009 at 08:00

Tips for easier TeamSite templating development

Tags: Perl , XSLT , XML , GUI , Internet explorer , Microsoft Windows , Solaris , Linux , Perl interpreter , interpreter , decent Perl programmer , Java , DTD
Author: Darren Ferguson

I’ve worked with Interwoven TeamSite for some time and over the years fellow developers have frequently complained how difficult it is to develop TeamSite presentation templates. I’ve never really seen these issues and I think a lot of it is down to developer laziness.

Logging, error trapping and step by step debugging are all available but some seem to prefer to complain about how tough templates are to debug rather than invest some time and work out how to make their life easier.

Are you sick of this message?

Comment: Could not process template:
/.iwmnt/default/main/my/branch/default/WORKAREA/default/templatedata/category/type/presentation/html.tpl

If so the following post contains some tips on stress free template development.

1. Install TeamSite locally

If your company has a support account with Interwoven get them to obtain you a development license and install TeamSite on your workstation. It doesn’t matter if you install a Windows, Solaris or Linux version locally – any code you write should be cross platform.

The benefit here is much quicker access to log files and code, it will just make your whole development experience quicker.

2. Use XSLT

TeamSite 6.7 supports XSLT and so do earlier versions by using the iwov_xslt tag in your presentation templates.

If you use XSLT for presentation you can copy your TeamSite DCRs locally and run your XSLT transformations against them independently of the TeamSite server. I use jEdit and the XSLT plugin to do this. Once you’ve perfected your XSLT you upload it to your TeamSite server.

You may find that you miss some of the tags and helper functions that standard TeamSite  presentation templates provide, but if you do I’d firmly suggest that the logic you are performing would be better placed as either formAPI code or validation rules in your data capture template.

Note: The iwov_xslt tag has some major issues, it doesn’t support UTF-8 and sometimes chops the first line off your output, but any half decent Perl programmer can get under the bonnet and fix these.

3. Make sure your TPL is valid XML

Simple enough right? It never ceases to amaze me when really bright developers ask me to debug their TPL and it contains mismatched tags or illegal characters.

TIP: Rename the TPL with an .xml file extension and drop it into Internet explorer. IE will complain if the TPL is not well formed XML.

You can also validate it against the appropriate DTD which is in iw-home/local/config.

4. Use Logging

By logging I don’t mean this:

open FILE, ">/tmp/debug.txt";
print FILE "debug message";
close FILE;

Use Log4Perl. It is distributed with TeamSite and is a fully featured logging package. Log4Perl is a Log4J clone and offers many powerful features. Covering the use of Log4Perl is way to lengthy for this post, instead check out this excellent article at perl.com.

5. Learn how to use the iwpt_compile.ipl script

Lots of TeamSite developers don’t realise that you can run your page generation from the command line. This will give you a more specific reason as to what is wrong with your presentation template than the standard error message from the GUI.

Run iwpt_compile.ipl in iw-home/bin and you will get the following usage information:

Syntax:  iwpt_compile.ipl -v |         (Note: command-line options wrapped for readability)
                          -h |
                          -pt presentation_file
                          [-ofile outfile]
                          [-smartwrite]
                          [-manifest filename]
                          [-oprefix basename_prefix]
                          [-ocode filename.ipl]
                          [-umask umask  (note: UNIX only)]
                          [tag-specific args (eg: -iw_pt-dcr filename)]
                          [-oenc  output_encoding_name (default: -oenc UTF-8)]
                          [-osenc os_encoding_name (default: -osenc UTF-8)]

         Notes:

             o  Extensive online HTML-based is available at:
                    http://support.interwoven.com/library/devel/tst/pt/
                and http://<your_local_teamsite_machine>/iw/help/tst/pt/

             o  For a complete list of available output encodings, type:
                    iwpt_compile.ipl -h -oenc

             o  Common tag-specific flags:
                    -iw_pt-dcr <dcr>
                    -iw_pt-arg <arg>
                    -iw_pt-preview
                    -iw_include-location <dir>

In most scenarios you'll just need to specify the following arguments:

• -iw_pt-dcr
• -iw_include-location
• -pt
• -ocode

-iw_include-location should be the full path of your TeamSite Workarea and -ocode should be the name of an output file to produce.

The output file is actually just a Perl script which will dump the result of your TPL generation to the standard out.

You may get an error executing iwpt_compile.ipl or you may get an error when you run the resulting output file, but either way the message you receive should be more useful than the standard message you get via the GUI.

6. Trap errors with Perl eval

As Java uses try/catch blocks Perl uses eval.

Consider the following Perl:

my $x = 10;
my $y = $x/0;

print "value of y is $y\n but this will never get printed";

The illegal division by zero causes Perl to throw an error and die. To stop the script from dying we can do the following.

eval {
	my $x = 10;
	my $y = $x/0;
	print "value of y is $y\n";
};

if($@) { print $@; }

print "\nand the script keeps running\n";

If you were to run the above script you'd see that Perl "catches" the error and continues to run. eval Will cope with any problems that your secript may encounter including syntax error and mis-spelling of keywords. Should eval cause the Perl interpreter to throw an error the descriptive error message is stored in the Perl special variable $@.

Finally consider this TPL extract which shows how you can use the Perl eval block in a TeamSite template to figure our why a Perl block is failing

eval {
	my $x = 10;
	my $y = $x/0;
	iwpt_output("value of y is $y\n");
};

if($@) {
	iwpt_output($@);
	$logger->warn($@);
}

iwpt_output "\nand the script keeps running\n";

From the snippet above you should be able to see how you can quickly add an eval block to a TPL Perl block to determine what is causing it to fail.

7. Use step by step debugging

If you find yourself at this stage it is a sign that your presentation logic is over complicated and you should really take a step back and question what you are doing.

If step by step debugging is the only option for you then here you can run Perl in debug mode by using the –d flag when starting the interpreter.

I’ve met lots of people who believe you can’t step by step debug Perl whereas in reality it is in incredibly simple to do. I use Activestate Komodo IDE to do my step by step debugging, it is a commercial product and reasonably expensive and to be honest I *only* use it for debugging.

A guide on how to set up Komodo for debugging is here.

In Conclusion

So that is all from me for now. I should have written this post years ago. Hopefully with XSLT template support in TeamSite 6.7 legacy Perl presentation templates will start to fade away, but there are so many old school templates out there that we’ll be supporting them for many years to come yet.

If you have any more TeamSite templating hints and tips or think that anything above is unclear or innacurate, please get in touch.

Written by: Darren Ferguson