Search KB Filter article types
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.
Categories: Extensions
Tags: Architects, Developers, HTML5, JavaScript, XML, XSLT
Revision: 1
Posted: 17/April/2011
Updated: 28/April/2011
Status: Publish
Types: Article


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
  • Performance and functional issues originated from substantial differences of XSLT and JavaScript rendering engines.
Debugger Panel

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:

  1. Clear all debugging messages.
  2. 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.
  3. 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.
  4. Toggle position of Debugger Panel between bottom-aligned-horizontal (the default) to right-aligned-vertical.
  5. Filter "Events" rows, to see only QA:XSLT/JQT rows. Allows more focused view when debugging functional equivalence.
  6. 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.
  7. 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.

<migration-write> JavaScript fragment </migration-write>

The hint orders to convertor to add JavaScript fragment to output stream.
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.
Used when it’s more convenient to write XSLT then JavaScript. The convertor applies XSLT/JS variables optimization for this fragment.

Two additional hints added in form of migration-select and migration-test attributes of XSLT instructions: xsl:for-each and xsl:if .

<xsl:for-each select=“XPath” migration-select=“JavaScript code”> XSLT Fragment </xsl:for-each>

<xsl:if test=“XPath” migration-test=“JavaScript code”> XSLT Fragment </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 hint used independently to provide alternatively implemented, more efficient, correct or compact JavaScript code in expression.
The XSLT fragment will be converted to JavaScript without changes.

The additional hint to provide alternative indexing of iterated elements is also added in form of migration-index attribute.

<xsl:for-each select=“XPath” migration-index=“JavaScript Variable name”> XSLT Fragment </xsl:for-each>

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]

The additional issue rising when an XSLT based project is being migrated to JQT is separation of resources. Imagine a project with multiple JavaScript or HTML resources that are only partially relevant in targeted JQT version or, in opposite, some resources should be included only in JQT version of the project. To allow such kind of control over the resources regarding the mode, Xslt2jQuery.exe switcher recognizes files with special extension [filename].jqv.[ext] . These files are taken into account when switching to JQT/JQT(keep xslt) mode.

Let's assume we have a file: AAA.js and it contains some JavaScript code suitable for XSLT mode.
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:

  1. Copy AAA.js to AAA.bk.js
  2. 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:

  1. Replace AAA.js content with AAA.bk.js content
  2. AAA.bk.js deleted

When the switch is completed, the AAA.js contains XSLT mode relevant content.

A few clarifications regarding jqv resource splitting:

  • [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, for the parent file
  • [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
Resources split - examples

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.
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

Related Articles

Title Update Author
Learn the basics of how to migrate your custom-control to the new .NETHTML5 version of Visual WebGui
Tags: Developers, Theme, XML, XSLT, 2. Intermediate, 3. Advanced, Customization, v6.4 and Later
26/April/2011    2011/04/26
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...
Tags: Architects, Developers, Visual WebGui Pipeline, JavaScript, 2. Intermediate, 3. Advanced, Customization, Optimizing Performance, jQuery, v6.4 and Later
27/Feb/2011    2011/02/27
The plugin provides functionality to compare two DOM nodes and build a well looking HTML page to visualize the difference.
Tags: Developers, JavaScript, 2. Intermediate
01/March/2011    2011/03/01