3.4 Advanced Tag Transformation

The WebForms class provides a group of advanced methods for transforming existing HTML elements. Unlike methods that modify individual properties such as SetClass, SetStyle, or SetText, these methods operate at the tag level.

Tag transformation can swap two element, reflect the structure of another tag into an existing element, or morph an existing element using a tag or an element selected through an OutputPlace.

The following methods belong to this group:

3.4.1 SwapTag

The SwapTag method swaps two elements. The element specified by InputPlace is moved to the position of the element specified by OutputPlace, while the OutputPlace element is moved to the original position of InputPlace.

After execution, Textbox1 occupies the original position of Textbox2, and Textbox2 occupies the original position of Textbox1.

SwapTag is useful when two elements need to exchange their positions in the DOM while preserving each element as a separate element.

3.4.2 SetReflection

The SetReflection method applies the structure of a specified tag to the target element.

This method is useful when the source is expressed directly as a tag definition rather than being selected from an existing element in the document.

3.4.3 SetReflectionByOutputPlace

The SetReflectionByOutputPlace method performs reflection using an element selected through an OutputPlace.

The distinction between SetReflection and SetReflectionByOutputPlace is the source of the operation. The first receives a tag directly, while the second receives an OutputPlace that identifies the source.

Reflection Example

Consider an existing user card and a template containing an alternative card structure:

The server can instruct WebFormsJS to reflect the template onto the existing card:

The resulting element keeps the original element's existing structure where the reflection operation does not replace it, while the structure obtained from the source is incorporated into the target. In the example, the original user information remains and the additional structure from the template is reflected into the target element.

Note: SetReflectionByOutputPlace uses the source selected by OutputPlace. This makes it possible to keep reusable HTML structures in the document and use them as transformation sources without constructing the complete structure in the server-side code.

3.4.4 SetMorph

The SetMorph method morphs the target element using a specified tag. Morphing is a tag-level transformation in which the existing element is transformed while preserving the parts of its DOM state that the morph operation is designed to retain.

The important distinction is that morphing is intended for transforming an existing DOM element while retaining the applicable existing DOM state, rather than simply assigning individual properties one by one.

3.4.5 SetMorphByOutputPlace

The SetMorphByOutputPlace method performs the morph operation using a source selected through an OutputPlace.

Morph Example

The following example defines an existing user card and a second card inside a <template> element:

The server only needs to identify the target and the source:

The morph operation transforms the existing userCard using the structure represented by userCardTemplate. The resulting element can therefore acquire the new classes, attributes, styles, and child structure while retaining the appropriate DOM state of the existing element.

3.4.6 Reflection and Morphing

Reflection and Morph both provide tag-level transformation, but they represent different transformation strategies.

The ByOutputPlace variants are particularly useful with reusable HTML structures such as <template> elements. The source structure can remain in the page while the server controls when and where it is applied.

3.4.7 Using Templates as Transformation Sources

A major use case for these methods is separating the HTML structure from the server-side transformation command.

Instead of constructing a complete replacement structure in C#, the developer can place the desired structure in a <template> element and use its identifier as the OutputPlace.

The server can then reference the template:

This approach keeps the HTML structure in HTML while the server determines when the transformation occurs. It also allows the same source structure to be reused by multiple server-generated Action Control sequences.

Note: When a <template> element is used as an OutputPlace, WebFormsJS processes the template content as the source structure rather than treating the <template> element itself as the resulting application target.

3.4.8 When to Use Tag Transformation

Use the ordinary Add, Set, Insert, and Delete methods when only individual properties or small portions of an element need to change.

Use the tag transformation methods when the operation concerns the structure of an existing element as a whole.

These operations extend the DOM manipulation capabilities of the WebForms class from property-level changes to structural transformations. The server therefore does not need to reconstruct an entire page or component. It can issue a precise transformation command, and WebFormsJS performs the corresponding DOM operation in the browser.