Working with QPR Portal templates
Working with QPR Portal templates
04.02.2016 - 13:05
This article describes basics of editing QPR Portal template files, divided into following sections:
- Applying changes from a patch file
- Applying changes from template files
- Clearing QPR Portal template cache
- Clearing web browsers cache
- Comparing template files using WinMerge
- Finding errors in installed template changes
- Removing installed portal changes
- Best practises in working with templates.
Applying changes from a patch file
A patch file is a file with suffix .patch. The patch file describes differences (changes) between two files (or between files in a folder). Patch files have been genered by comparing original files of QPR Suite release with files where the changes have been implemented. Use following guidelines to make changes described by a patch file:
- Lines that are added, start with a plus sign (+)
- Lines that are removed, start with a minus sign (-)
- For changed files there is the original line with a minus sign and changed file with plus sign
- Lines with no plus or minus signs, are have no differences. They can be used to identify the location of the changed files.
Applying changes from template files
For some accelerators there are the whole changes template files available. If you have an environment where there are no customizations already installed, it's easiest to use the files, which just replace the orinal files. Please take into account that if the replaced files contain previously installed changes, those are lost if the files are just copied. The best way for that case is to use e.g. WinMerge to move the changes.
Clearing QPR Portal template cache
QPR Portal template files in C:\ProgramData\QPR Software\ are cached in QPR WAS (Web Application Server) memory to improve performance (no need to read the files from disk for every page request). When template changes have been installed, QPR Portal template cache needs to be cleared, for the changes to take effect. This can be done by opening url http://SERVER/QPR2015-1/Portal/QPR.Isapi.dll?QPRWAS&*cleartemplatecache, where SERVER is the name of QPR server. Note that https may be in use, and installation path (QPR2015-1) may other than default. See the exact url from QPR Portal's url. Note that clearing QPR Portal template cache doesn't have any effect on changes in IIS published files (in C:\inetpub\wwwroot\), because those files are not processed by WAS (for more information see the next chapter).
Clearing web browsers cache
In addition to QPR WAS, the web browser may cache files (usually javasript and css files). Usually IIS published files(in C:\inetpub\wwwroot\) are cached. If there are changes for those files, clearing web browser's cache may be needed for the changes to take effect. It depends on browser, how the cache is cleared.
- Internet Explorer: [node/https://www.google.com/#q=internet+explorer+clear+cache https://www.google.com/#q=internet+explorer+clear+cache]
- Firefox: [node/https://www.google.com/#q=firefox+clear+cache https://www.google.com/#q=firefox+clear+cache]
Comparing template files using WinMerge
WinMerge is a tool for comparing files and it's ideal for working with QPR Portal templates! WinMerge can be downloaded in http://winmerge.org. WinMerge is able to e.g.
- compare files and folders
- move changes from a file to other
- create patch files
Finding errors in installed template changes
When installing template changes manually, human errors are common (e.g. a change is inserted to a wrong line or a plus sign from a patch file is forgot to remove). When there are errors, customizations don't work or usually even the whole portal stops working. One way to find errors is to generate a patch file of the changed templates (e.g. using WinMerge) and compare that patch with the patch file provided with the installation instructions. If the changes have been installed properly, both patch files should be identical.
Removing installed portal changes
The easiest way to remove installed portal changes, is to use WinMerge. Compare the templates with original templates (by default stored in C:\Program Files\QPR Software Plc\QPR 2015.1 Servers\Web Application Server\Templates\). Put the original templates in the left side and changed in the right side. Right click the change in the left side, and select Copy to Right.
An alternative way is to remove changes manually by based in the installation instructions and doing the reverse.
Best practises in working with templates
When installing portal changes, it's advisable to add a note next to the change, to be able to identify which customization it is. When the templates are compared using diff, it's indeed easy to see that there is a change, but if the change is not documented, it may be hard to say what functionality it is related to.
For javascript changes, a comment can be used, such as
// Customization #001, External Report Menu
For html changes, use html comments, e.g.
<!-- Customization #001, External Report Menu -->
(These commenting syntaxes should not be mixed - otherwise portal may stop working.)
If you have a separate technical documentation for the QPR system, you can only use customization id number, which is explained in the documentation. E.g. removing the customization is a lot easier, when all changes can be searched by id number.