Reaching functional equivalence when migrating to .NETHTML5
The article describes how to use the debugging panel, migration hints and resource splitting in order to reach full functional equivalency between the original XSLT (WINWEB) version and targeted JQT (.NETHTML5) version.
This article continues the series of articles describing the migration process from XSLT based VWG projects to the new .NETHTML5 (JQT) version. At this point you should already know how to run the tool to convert .xslt resources to .jqt.js resources with Xslt2jQuery.exe converter. If you are not familiar with this tool please see the Related Articles section below.
The next step after the automatic migration with Xslt2jQuery has completed would be achieving functional equivalency. The strict definition of "functional equivalency" is achieving equivalent UI and logic performance with same application response to all logic activities performed by an end user.
There are multiple sources for possible non-equivalence between XSLT and JQT versions of the same project. The primary reasons are:
- Incomplete auto conversion of XSLT to JQT
To reach the equivalence we need a tool to evaluate the differences between the XSLT and JQT version of a project. The .NETHTML5 (JQT) version contains build-in debugger panel with a few additional toolbar buttons providing this functionality. The primary tool to use will be comparison between two HTML fragments rendered with XSLT and, as opposite, JQT rendering engines.
As already described in the first article in this series, the VWG client side UI is built from XML response transformed to DHTML fragment. The transformation is done by the XSLT processor or by JQT rendering engine. So, to ensure the applications' functional equivalency we need to compare the rendering engines transformation results.
The only mode allowing to compare rendering results is "JQT(keep XSLT)" mode. In this mode a received XML response will be rendered with both XSLT and JQT rendering engines. The outcome DHTML fragments will be compared on the fly. The comparison provides valuable pieces of information:
- Time elapsed for transformation for each of the rendering engines
- Comparison status: "Same" - for equivalent fragments or "Different" for the different DHTML fragments.
To visualize the difference you need to double click the row in the debugger panel. This view is the most convenient way to locate and take care of possible functional non-equivalences.
The Debugger Panel is not turned on by default. Open the application's Web.Config file, find system.diagnostics/switches section and add or update the switch value to '1'. Refresh the application window. The resulting web.config should be similar to the fragment below:
0 - Disabled
1 - Enabled
<add name="VWG_ShowDebuggerSwitch" value="1"/>
The figure demonstrates turned on debugger panel with additional toolbar buttons:
Actions available with toolbar buttons:
- Clear all debugging messages.
- Switch between XSLT and JQT rendering engines. The entire window will be redrawn with rendering results of target engine. The switch allows experiencing the difference between engines and checking specific functionality faster.
- Turn ON the comparison between rendering results. Turned off by default. When turned off - only result of selected rendering engine applied to avoid performance impact.
- Toggle position of Debugger Panel between bottom-aligned-horizontal (the default) to right-aligned-vertical.
- Filter "Events" rows, to see only QA:XSLT/JQT rows. Allows more focused view when debugging functional equivalence.
- Turn ON on-the-fly rendering results comparison evaluation. IE only. Used to show immediately status of rendering results comparison in IE. When turned off you need to double click the row to evaluate the status and to see the difference. When turned on - some performance slowdown will be felt.
- An example of row with information regarding rendering results comparison: Render engine, elapsed time per engine(summary), Status. Double click the row to visualize DHTML fragment differences.
More detailed description of JQT rendering engine available in this article, visit also JQT pluign page. The additional plugin responsible for comparison of HTML fragments and visualizing the differences described in this article and plugin page.Migration hints
The project migration is a continuous process requiring side by side maintenance for both XSLT and JQT versions. Because the Xslt2jQuery.exe converter is a one way conversion tool, it is recommended to maintain the XSLT version of the resource instead of the JQT version. Thus, at least in transition time, the continuous updates and fixes should be converted to JQT using the same conversion process.
To reach fully equivalent JQT based project sometimes we need to change default behavior of Xslt2jQuery convertor. That happens because sometimes we want to correct the conversion results to achieve performance boost or functional change. Migration hint is a tool to serve this goal.
The hint is an XML instruction that is added to original XSLT resource and interpreted by Xslt2jQuery converter.
<migration-ignore> XSLT fragment </migration-ignore>
The simplest hint orders to completely ignore the XSLT fragment. The fragment isn't processed by the Xslt2jQuery converter.
The hint is used in conjunction with migration-write hint to replace some XSLT implementation with a more efficient or a different JQT implementation.
The hint used independently or in conjunction with migration-ignore to add additional, more efficient, compact or relocated code fragment.
<migration-write type=“elements”> XSLT fragment </migration-write>
The hint orders the convertor to add the XSLT fragment to input stream and processes it as it was part of original XSLT resource.
Two additional hints added in form of migration-select and migration-test attributes of XSLT instructions: xsl:for-each and xsl:if .
The hint orders to convertor to ignore the original select/test expression and use as-is the expression from migration-select or migration-test attribute.
The additional hint to provide alternative indexing of iterated elements is also added in form of migration-index attribute.
The hint used in conjuction with other hints, for example see the fragment below:
<xsl:for-each select="../Day" migration-index="intDay">
<xsl:variable name="prmPosition" select="position()" migration-select="intDay+1" ></xsl>
<xsl:if test="position()>1" migration-test="intDay >0">
<xsl:attribute name="style">border-left:1px solid black;</xsl:attribute>
The XSLT fragment iterates Day elements. To track index of Day element we will use the migration-index hint to declare index variable intDay. Once declared it could be used in migration-write, migration-select, migration-test hints. This hint is only efficient way to track element position.Migration hints - examples
Below are a few examples available for each migration hint (open file and use search text to highlight the usage):
- migration-ignore - check this XSLT file
- migration-write - check this XSLT file
- migration-write type='elements' - check this XSLT file
- migration-select - check this XSLT file
- migration-test - check this XSLT file
Using migration hints as described above in conjunction with Debugger Panel helper tools it's possible to solve majority of functional differences between XSLT and JQT based projects.Resources split with [name].jqv.[ext]
To arrange the file content in JQT modes let's create another file AAA.jqv.js that will contain different code suitable only for JQT modes.
On mode switch the next sequence of commands will be issued:
- Copy AAA.js to AAA.bk.js
- Replace AAA.js content with AAA.jqv.js content
When the switch is completed, the AAA.js contains JQT mode relevant content.
On mode switch to XSLT, the next sequence of commands issued returning the state of file backward:
- Replace AAA.js content with AAA.bk.js content
- AAA.bk.js deleted
When the switch is completed, the AAA.js contains XSLT mode relevant content.
A few clarifications regarding jqv resource splitting:
Resources split - examples
- [name].jqv.[ext] files aren't included in the project (shouldn't be included, but SVN controlled)
- [name].[ext] files have to be included in the processed project
- [name].jqv.[ext] will be processed only if its parent file [name].[ext] exists
- [name].jqv.[ext] replaces entirely the parent file [name].[ext] (that's backuped to .bk file before that)
- .jqv extention should be one before last extention in multipart extension file names, like in aaaaa.bb.cc.jqv.htm, for the parent file aaaaa.bb.cc.htm
- [name].bk.[ext] files are created only once, if you multiple times repeat switch to JQT modes, without switch back to XSLT, the .bk files aren't overwritten
- be careful, the [name].bk.[ext] files replace its parent files [name].[ext] when switching back to XSLT mode, so don't loose the changes
- jqv means versioned
A few examples to demonstrate the resources split:
1. The folder contains Resources.xml and Resources.jqv.xml files that are both processed when switching to JQT modes.
You can see that Resources.xml and Resources.jqv.xml contain different content regarding the rendering mode.
2. The folder contains CommonSkin.Common.Aux.JQTSplit.js and CommonSkin.Common.Aux.JQTSplit.jqv.js files.Summary
You can see that jqv version contains different implementation of the Aux_DecodeText function.
Reaching functional equivalence is the first and most important step in migration to .NETHTML5 (JQT) version. The tools described above allow to debug the differences, track performance changes and maintain both XSLT and JQT versions of the project in transitioning period.
The articles related to this articles:
About the author
Learn the basics of how to migrate your custom-control to the new .NETHTML5 version of Visual WebGui
Developers, Theme, XML, XSLT, 2. Intermediate, 3. Advanced, Customization, v6.4 and Later
The JQT template engine is a robust jQuery template engine extension. It was created to provide powerful templating capabilities which are compatible (migratable) from XSLT. The JQT project includes runtime APIs which provide powerful capabilities and a XSLT migrator. The XSLT migrator can take XS...
The plugin provides functionality to compare two DOM nodes and build a well looking HTML page to visualize the difference.