Adding your own pages to Ipac/Hip

Though many Ipac installations have tabs/sub-tabs linking directly to external web content I have yet to see a site that has fitted its own content within the Ipac structure (save for modifying the news.xsl file) though I have to say I haven't looked too far and wide for examples. Below is a step by step guide to a method I have used for adding custom content within the Ipac setup.

Note. There is a simpler method of achieving the same effect that was brought to my attention by Paul Roberts. As both methods have their advantages I add some explanation of the differences at the end of this guide

There are essentially three steps:

• Create the sub-tab you will use.
• Create a custom xsl file.
• Amend xsltransformer.xml to include your custom xsl file.

Creating the sub-tab

On your ipac admin pages go to

• Customize - Interface - Tabset
• Select the appropriate tabset
• Choose Edit sub-tab
• Select the tab to add the sub-tab to
• Add the details as appropriate and click Next

• Select sub-tab type as Search Page. (Only options I got were search page and URL. I think this is because the parent tab is a Search tab.)
• Select the Add a Page option

• Choose Add Page from the top of the table listing your existing defined pages
• Fill in the fields appropriately

• You will be returned to the table of defined pages with your new entry at the bottom of the table
• Click Return to Tab Editor
• Pick your page from the drop down list and click Next

• Choose Custom, fill in the 2 fields and click Next
• The template name can be whatever you want but do note it for later steps

• The message Sub-tab added succesfully should appear
• Click OK then Done then Done

Creating a custom XSL file

I used the file news.xsl as the template for my customisation. This is in the default xsl folder where all the xsl files reside (/opt/dynix/xsl/xsl on our Unix based 2.1.1 system but paths will vary according to your OS and ipac version). Make a copy of the file in the same directory and rename it. Call it what you want but for future reference it may be best to name it according to its function. Avoid any names that dynix currently uses for xsl files (or may choose to use in future).

• Change the line <xsl:template match="news"> to <xsl:template match="whateveryoucalledyourcustomtemplate">

• Add your code to the area under the comment about user-defined XSL
• Your code must be valid x(m/s/htm)l unless you cheat with a CDATA section but if you know about those you probably are comfortable enough with xml anyway

You can of course make your xsl (and the resultant html) as complex as you wish. I have kept it simple for the purposes of experimentation and because news.xsl and copies thereof provide a nice framework for basic content.

Amending xsltransformer.xml

If you go to your new subtab prior to this step you will likely see just the ipac tabs and footer but no middle content. This is because the xsl transformer needs to know to load your custom xsl file. The relevant file to carry this out is xsltransformer.xml and this lives in the xsl folder above the xsl folder containing all the xsl files (confusing, huh?). That's /opt/dynix/xsl on our system. As this is a XML file you can open it in any editor dealing with plain text files.

• In xsltransformer.xml make a note of the relevant template set(s) for the profile(s) you are changing
• In my example the profile is hweb and the accompanying template set is mweb (confusing part II, huh?)

• Further down the file in the relevant template set(s) add <Include> lines for your custom xsl files
• The <Include> lines are added under the searchresponse.xsl root file as they are defined as search pages
• The include type is the template name
• You will see in the screenshot below two previous custom pages I have added - pin.xsl and canned.xsl

With all that done, you now need to stop ipac/hzapp (depending on what version you are on) and stop the xsl processor. Restart the xsl processor, restart ipac/hzapp, navigate to your new sub-tab and you should see your custom screen. The image below shows the screen built up from this example.

Alternative methods

The alternative method mentioned at the head of the page is similar in many respects to the steps outlined above. You still create a sub-tab in the same way, pointing to your custom XSL template. The major difference is that your custom XSL is not in a separate file but is one of a number of discrete templates within searchinput.xsl which is part of the default installation. You can copy and adapt one of the existing templates in there already in much the same way as news.xsl was adapted in the main example above. As your custom template is in a discrete section within the larger file there should not be any difficulty re-applying it post-upgrade. Because searchinput.xsl is already declared in xsltransformer.xml there is no need for step 3 of the guide above.

Notes

Though my experience of the speed with which Ipac recognises updated/modified XSL files has seemed to differ between different versions of the software I am confident in saying that changes to any custom XSL files should be recognised quite quickly and without the need to stop and start either Ipac/Hip itself or the XSL processor. This should allow quite a bit of flexibility in the type of content that one might wish to present on a custom Ipac page.

The process above seems fairly upgrade-friendly. Our system was upgraded from 2.1 to 2.1.1 following this change and the only work I had to redo was that in step 3. Step 1 is OK as the changes it makes are in the admin database which should migrate unscathed to a new version. Step 2 will be fine provided dynix do not produce an xsl file with the same name as your custom one and provided the xsl files still live in the same place on the system. The latter would not be true for those upgrading from 2.03.01 to 2.1 but it's a simple case of transferring your custom xsl file to the new default location for xsl files.

The example above was put together on a machine running Solaris 9 and Hip v2.1.1 but I have also done this on an ipac test server running Windows 2000 and ipac v2.02.50 so I believe the steps are transferable between operating systems and ipac/hip versions (though I have no knowledge of versions pre 2.02.50 (is anyone using such old versions still?). Also of course Dynix may alter future versions of Hip in such a way that these instructions no longer work. I don't believe this is too likely but it is a risk we run with any customisations we make to the system.

In the same way that dynix will not be held responsible for any stylesheet customisations that customers make I can offer no support if things go wrong following the above instructions. Disclaimer aside, once I had figured this out it is actually a fairly simple process. I will help answer questions where I can but modifications to your ipac system are made at your own risk.

As proof of concept I was going to put together these instructions under a sub-tab on Hip on our backup server. I decided not to in the end as I would have to remove the sub-tab if we needed to use that server as our live system (as was the case following a hardware failure on the current live system recently). However, I have no reason to doubt that this would have worked just as well as the simple example that is provided.

Any feedback welcome. I would also enjoy seeing any links to custom pages that people do create using these instructions.

Robert Day - Cambridgeshire Libraries, UK - robert.day@cambridgeshire.gov.uk - Dec 2003