Protx Support: Custom Templates

Getting Started

The Protx VSP Form and VSP Server systems allow you to customise not only the look and feel of the payment pages presented to your customers, but also the design of the completion e-mails, error pages and 3D-secure frame pages.

You can download our payment page templates here.

The templates are XSLT version 2 code, with no customised tags or non-standard additions. You can find a wealth of help on XSLT on the Internet and in numerous paper publications. Your web developers will be able to help you if you are unfamiliar with XLST. If you do not have a Web Developer, Protx have a number of partners in your area that will be able to help (please refer to our partners list at (http://www.protx.com/partners_find_business.asp)

This kit not only provides the Protx Default XSLT templates, the XML to populate them, and all images used on our pages, but also provides everything you need to render the XLST templates into HTML pages during testing (using the freeware versions of Saxon (http://saxon.sourceforge.net/) and Kernow (http://sourceforge.net/projects/kernowforsaxon/)).

All you need to use the renderers is the Java runtime version 1.4 or higher. The latest Java runtimes can be found at http://java.sun.com/

Once you've installed the Java runtime, you're ready to go.

Rendering a Template

To render a template, follow these simple steps:

Double click the Kernow.bat batch file in the CustomTemplates folder (if you are using windows, otherwise copy the contents of that file onto your command line and execute them)

Select the "Single File" tab.

Check the "Send Output to File" checkbox

Click the ... button next to the XML file edit box and browse to "CustomTemplates/XML/card_confirmation.xml"

Click the ... button next to the Stylesheet file edit box and browse to "CustomTemplates/XSLT/card_confirmation.xslt"

Click the ... button next to the OutputFile edit box and browse to "CustomTemplates/HTML and create a new file called card_confirmation.html"

Click "Run".

A bar should appear whilst the system is working, then a message saying "Done in xx milliseconds" should appear.

Now open your web browser and browse directly to "CustomTemplates/HTML/card_confirmation.html" file.

This will display the order confirmation page.(N.B. On some browsers you will need to click to allow Active Content to run if you wish to see the Javascript mousovers etc. working)

It's a simple as that. When you are changing the XLST pages, any mistakes you make in the XSLT or XHTML code will be reported in the bottom window of the Kernow page when you click Run. The line number and position are displayed with each error, so it's very easy to debug your code.

Editing the Templates

The following templates are included in this kit:

card_selection.xslt - This is the initial screen presented to your customers that asks them to click on an image to select the card type they wish to use.

card_details.xslt - The second payment page, which asks for the card number, expiry date, card holder name and so forth. It also has pop-up links to static HTML information pages in the images folder. Feel free to change these, or add other simular pop-ups that you think may help your customers.

card_confirmation.xslt - The third payment page, which displays the full order summary (including basket contents where they have been passed) and a summary of the chosen card.

card_authentication.xslt - The frame page surrounding the bank 3D-Secure pages which may be presented to your customers if you have enabled 3D-Secure on your account. This now has a "skip3d" button to allow users to continue even if 3D-Authentication fails.

authorisation.xslt - The "Authorising please wait" screen displayed for the few seconds that Protx are talking to your acquiring bank to obtain an authorisation.

error.xslt - The error screen displayed by VSP Server and Form if a problem has occurred with a transaction.

3d_callback.xslt, 3d_redirect.xslt - Simple forwarding pages which do not really need modification. They only display during the 3D-Secure process if a customer has JavaScript turned off. Their role is to post 3D-secure information from Protx to the Issuing bank and back again. You may wish to change the text, but do not change the function or the 3D-Secure process will not work.

VSP Form only: form_response.xslt - The page displayed to VSP Form customers if there are errors during transaction registration or completion. This provides a link back to your FailureURL page to prevent the customers being stranded on the Protx site.

VSP Form only: customer_email.xslt - The e-mail sent to your customer when a transaction completes successfully.

VSP Form only: vendor_email.xslt - The e-mail sent to your VendorEMail address whenever a transaction completes.

The files are all multiple language compliant. You'll notice they obtain the text to display on the screen from the i18n.xml file included with the templates. If you wish to create pages that support multiple languages, you should add additional text entries in this file and when your templates work in English, create a <texts xml:lang="xx"> (where "xx" is the language, e.g. "fr" or "de") with the same text labels, but their contents translated. Protx will provide additional language translations for our default templates as we create them.

To edit the templates, simply open the XSLT file in your preferred editor and change the layout at your leisure. We use DreamWeaver at Protx, but many XSLT editors are available on the net (including freeware editors).

The images you can change are all included in the "CustomTemplates/images/YourImages folder". Place any additional images or pop-ups in that folder, or subfolders thereof. Don't try to access images from anywhere else. Your templates will not work on our systems if you do so.

You'll notice that the Protx logo and the javascript code is loaded from the images/protx folder. You cannot change this code or the images there (when your templates are uploaded, nothing from this folder will be uploaded to our servers) but you can use the javascript mouseover and pop-up functions in your code.

The support team will validate your templates, but cannot offer to debug them for you. Please ask your web-developers for help if you are experiencing difficulties with XSLT or the multi-language support.

Dos and Don'ts

The templates are extremely flexible and allow you to completely customise the look and feel of the pages, but there are some rules you must follow:

Do not change FORM field contents - If an edit box called "CardNumber" is rendered on a page inside a Form called "Continue", then your page must also have an edit box called "CardNumber" inside a Form called "Continue". You can change how that box displays, but not the fact that a box needs to be there. Also if a page contains three forms which submit different data, you should ensure your page behaves identically.

No additional Javascript - Protx ONLY allow the pop-up and mouseover functions we've provided for you. No other javascript is allowed.

Do not reference externally - We do not allow templates that reference code or images that are not on our server. All references should be to local documents placed in the "YourImages folder".

Do not navigate away from the payment pages - We do not allow links or redirects to pages before or after the payment pages. Once on the Protx site, the customer must complete the payment process either by a successful transaction or by cancelling.

Do not embed active content - ActiveX controls, streaming content, large movie files etc. will not be supported.

Include the Protx Logo in card_selection.xslt - Somewhere on your card-selection screen, you must include the Protx logo. It is optional on subsequent screens.

Do not modify the javascript files or logos in the "images/protx folder" - As mentioned above, these are provided for your reference and use, but will not be uploaded with your templates, so changing them will not help you.

Do not modify the XML file - This are example files used for template creation. The real XML used by your templates on our test and live systems is generated dynamically. If you try to add fields to the XML and reference them, then these changes will not be transferred to live.

ALWAYS INCLUDE NOSCRIPT SECTIONS for every <SCRIPT> section in your templates. If you only use our mouseover functions to submit pages, for example, customers without Javascript enabled will not be able to submit the pages and their payments will not be taken. You do not have to use Javascript on your pages at all, if you do not wish to.

Getting your templates to Protx

When you are happy that your pages work correctly on your local machine (and have tested with Javascript enabled AND disabled), zip up the contents of your XSLT and YourImages folders and e-mail them, along with your VSP Vendor Name to templates@protx.com.

The team there will validate them against the rules above, and if everything is okay, upload them to the test server for you. This process can take up to 72 hours. Once the team has come back to you, log into your Test VSP Admin screens and set your templates to Custom in the Account Administration area, then test them.

Unfortunately we cannot debug your XSLT code for you. Our team can only validate your templates against the rules above, not correct the XSLT itself (although we will validate that the XSLT is valid using the same tools we've provided to you). If you need help with XSLT, your web developer should be able to provide it.

If you are happy with them on the test server, email that address again and ask for your templates to be set live. The team will upload them for you and let you know when they are there. Again, you can set them live in your Live VSP Admin area.

If you have questions about templates, please e-mail support@protx.com (include your VSP Vendor Name) and we'll do our best to help you.