WebForms Core can execute Action Controls that are stored directly inside HTML comments. A WebForms Core HTML comment begins with <!--[webforms] and contains Action Controls that can be read and executed by WebFormsJS.
These Action Controls can be present in the initial HTML page or can be delivered later as part of an HTML response from the server. When WebFormsJS encounters a WebForms Core comment, it reads the Action Controls contained in the comment and executes them according to the execution flow defined by the Action Controls.
Comment Events provide an important offline capability in WebForms Core. The Action Controls required for an interaction can be delivered to the browser in advance as part of the HTML document. When the user later triggers the associated event, WebFormsJS can execute those already available Action Controls without requesting them from the server again.
This makes it possible to prepare client-side behavior during the initial page load. The server defines the behavior and sends the Action Controls to the browser, while WebFormsJS stores the executable commands as part of the page and executes them when required.
The same mechanism also applies when a subsequent server response contains a WebForms Core comment. The newly delivered Action Controls become available in the HTML document and can subsequently be executed by WebFormsJS.
SetCommentEvent associates an HTML event with an Action Control execution section identified by an Index.
The method is defined as:
The InputPlace identifies the element on which the HTML event is assigned. HtmlEvent specifies the event. Index identifies the point in the Action Control sequence from which execution begins.
SetCommentEventListener provides the same mechanism using an HTML event listener.
Its definition is:
The difference is that SetCommentEvent uses an HTML event, while SetCommentEventListener uses an event listener.
A Comment Event normally references an Index created with StartIndex.
In this structure, the Comment Events are defined first. The Action Control sections are then created using StartIndex.
StartIndex creates a named execution boundary in the Action Control sequence:
The name supplied to StartIndex is then used by SetCommentEvent to identify where WebFormsJS should begin execution.
Action Controls can also be placed before the first StartIndex. These are not part of a later indexed event section. They belong to the initial Action Control sequence and can therefore be executed when the HTML comment is initially processed by WebFormsJS.
For this reason, StartIndex should normally be created after any Action Controls that are intended to execute during the initial processing of the comment.
WebFormsJS reads the Action Controls in the HTML comment sequentially. When it reaches the requested Index, execution begins from that point.
After execution begins at an Index, WebFormsJS continues reading the Action Controls one by one. Execution stops when it reaches the next Index or when it reaches the end of the Action Control sequence.
For example:
If the event points to message, WebFormsJS starts at message and executes the Action Controls until it reaches text.
If the event points to text, execution starts at text and continues until color.
If the event points to color, execution starts at color and continues until the end because there is no following Index.
If SetCommentEvent is called without an Index, the Action Controls within the HTML comment are executed starting from the beginning—either until an index is reached or until the end.
This scenario is useful when the Action Control involves initialization tasks and we want to re-execute the initialization logic.
However, when a comment contains several independent operations, using named indexes is recommended.
Several Comment Events can reference different indexes within the same HTML comment.
The HTML comment generated by the WebForms class contains one Action Control sequence with several indexed sections. Each event points to one of those sections.
The following example demonstrates the recommended structure for multiple offline Comment Events.
The important point in this example is the order of definition.
StartIndex.StartIndex is the same name referenced by the corresponding Comment Event.The generated WebForms Core comment can be included directly in the initial HTML response.
When the page is initially processed, WebFormsJS reads the comment and recognizes the Action Controls and their indexes. Later, when MessageButton triggers its Comment Event, WebFormsJS can execute the section beginning at message without obtaining that Action Control sequence from the server.
A server can also return HTML containing a WebForms Core comment in a later response.
WebFormsJS processes the returned HTML and can subsequently execute the Action Controls contained in the comment. Therefore, Comment Events are not limited to commands embedded in the initial page.
Because the Action Controls can be delivered before they are needed, Comment Events can be used to implement interactions that continue to work without a new server request.
For example, an application can deliver several predefined operations during the initial page load:
Once these commands have been delivered to the browser, WebFormsJS can execute the corresponding sections locally when the events occur.
The Comment Event execution model can be summarized as follows:
SetCommentEvent or SetCommentEventListener.StartIndex.<!--[webforms] ... --> HTML comment.Comment Events connect browser events to Action Controls that are already present in an HTML document. Their main purpose is to allow WebFormsJS to execute predefined Action Controls without requiring a new server request to obtain those commands.
SetCommentEvent and SetCommentEventListener normally reference an Index created by StartIndex. The Comment Event definitions can be created first, followed by the indexed Action Control sections.
Action Controls placed before the first StartIndex can be used for initial execution. Once an Index is encountered, it defines the beginning of an independently executable section. When WebFormsJS starts from that Index, it executes Action Controls sequentially until the next Index or until the end of the comment.
This combination of HTML comments, Action Controls, indexes, and browser events provides WebForms Core with a practical mechanism for predefined and offline-capable browser behavior.
