3.2 Fetch Helper Class

The Fetch class provides a collection of expressions for obtaining values from the browser and using those values during WebForms Core execution.

Unlike methods that directly modify the DOM, Fetch methods represent values that are evaluated by WebFormsJS in the browser. The resulting value can then be used by other WebForms operations such as SetText, Message, conditions, loops, storage operations, and other Action Controls.

The Fetch class is a static helper class. Its methods do not directly execute browser operations on the server. Instead, they generate compact Fetch expressions that are interpreted by WebFormsJS.

Note: Fetch expressions are intended to be used as values inside WebForms commands. They are evaluated by WebFormsJS at execution time, so their result can depend on the current browser state, DOM, event, URL, storage, or other client-side data.

3.2.1. Basic Usage

A Fetch expression can be passed to a WebForms method as its value.

form.SetText("Tag1", Fetch.GetText("Tag2"));

In this example, WebFormsJS obtains the text of Tag2 and uses the returned value as the new text of Tag1.

Fetch expressions can also be used with Message.

form.Message(Fetch.GetText("Tag1"));

This displays the value obtained from Tag1.

The following sections describe the Fetch members available in the Fetch class.

3.2.2. Method

The Method section provides Fetch expressions for random values, string transformations, URI encoding, JavaScript methods, module methods, WebAssembly methods, scripts, and loading external resources.

3.2.2.1 Random

Method	Arguments	Description
Random(int MaxValue)	MaxValue	Generates a random value using the specified maximum value.
Random(int MinValue, int MaxValue)	MinValue, MaxValue	Generates a random value within the specified range.

Example:

form.Message(Fetch.Random(15, 35));

A random value between the specified limits is evaluated in the browser and passed to the message operation.

3.2.2.2 SpaceToChar

Method	Arguments	Description
SpaceToChar(string Text, string Character = "-")	Text, Character	Replaces spaces in the specified text with the specified character.

Example:

form.SetText("Tag1", Fetch.SpaceToChar("Hello World", "_"));

The resulting value is Hello_World.

3.2.2.3 URI Encoding

Method	Arguments	Description
EncodeURI(string Text)	Text	Encodes the specified text as a URI value.
DecodeURI(string Text)	Text	Decodes a URI-encoded value.

Example:

form.Message(Fetch.EncodeURI("Hello World & Test"));

Decoding can be performed with:

form.SetText("Tag1", Fetch.DecodeURI("Hello%20World%20%26%20Test"));

3.2.2.4 Method

Method invokes a method available in the WebFormsJS execution environment.

Method	Arguments
Method(string MethodName, object[] Args = null)	MethodName: method name Args: optional argument array

Without arguments:

form.Message(Fetch.Method("TestMethod"));

With arguments:

form.SetText("Tag1", Fetch.Method("TestMethod", ["Hello", "World"]));

The use of object[] allows arguments to be passed without converting their values into a single string before the expression is generated.

3.2.2.5 ModuleMethod

ModuleMethod invokes a method exported by a loaded JavaScript module.

Method	Arguments
ModuleMethod(string MethodName, object[] Args = null)	MethodName: exported module method name Args: optional argument array

The module must first be loaded using the WebForms module mechanism.

form.LoadModule("/script/module/math-utils.js", []); form.SetText( "Tag1", Fetch.ModuleMethod("multiply", [12, 26]) );

The returned value can then be consumed by another WebForms operation.

3.2.2.6 WasmMethod

WasmMethod invokes a method from a WebAssembly module.

Argument	Description
WasmLanguage	The WebAssembly language identifier.
WasmUrl	URL of the WebAssembly module.
MethodName	Name of the WebAssembly method.
Args	Optional argument array.

The method signature is:

WasmMethod(string WasmLanguage, string WasmUrl, string MethodName, object[] Args = null)

The method name may include a class name separated by a period when required by the WebAssembly module.

Example:

form.SetText( "Tag1", Fetch.WasmMethod( WasmLanguage.Rust, "/web-assembly/hello_world_bg.wasm", "add", [100, 105] ) );

3.2.2.7 Script

Script creates a Fetch expression containing JavaScript code.

Method	Arguments
Script(string ScriptText)	ScriptText: JavaScript source code

Example:

form.Message(Fetch.Script("confirm('Accept?');"));

The script is executed by the browser runtime as part of the Fetch expression.

3.2.2.8 LoadUrl

LoadUrl loads the content of a URL.

Method	Arguments
LoadUrl(string Url, bool FetchScript = false)	Url: resource URL FetchScript: whether associated script content should also be fetched

Example:

form.SetText("Tag1", Fetch.LoadUrl("/api/one_line.txt"));

3.2.2.9 LoadHtml

LoadHtml loads HTML from a URL. It can optionally process scripts and can specify an Input Place for the fetched content.

Argument	Description
Url	URL containing the HTML.
FetchInputPlace	Optional Input Place associated with the fetched HTML.
FetchScript	Determines whether scripts associated with the fetched content are processed.

LoadHtml(string Url, string FetchInputPlace = "", bool FetchScript = false)

Example:

form.SetText( "Tag1", Fetch.LoadHtml("/api/page_and_script", "Tag1", true) );

3.2.2.10 LoadLine

LoadLine obtains a specific line from a text resource.

Method	Arguments
LoadLine(string Url, int Line)	Url: text resource URL Line: line number

form.SetText("Tag1", Fetch.LoadLine("/api/sample.txt", 5));

3.2.2.11 LoadINI

LoadINI loads a value from an INI resource.

Method	Arguments
LoadINI(string Url, string Name, bool IsINILike = false)	Url: resource URL Name: key name IsINILike: enables INI-like processing

form.SetText("Tag1", Fetch.LoadINI("/api/fa.ini", "about"));

3.2.2.12 LoadJSON

LoadJSON obtains a value from a JSON resource.

LoadJSON(string Url, string Name)

Name can represent a name or a nested path. The current implementation supports indexed nested paths such as Student[8].Name, with nested path indexes starting at zero.

form.SetText( "Tag1", Fetch.LoadJSON("/api/article.json", "article.title") );

3.2.2.13 LoadXML

LoadXML obtains a value from an XML resource using an XPath expression.

LoadXML(string Url, string Name)

The Name argument can contain an XPath expression. XPath indexes in this Fetch operation start at one.

form.SetText( "Tag1", Fetch.LoadXML( "/api/rss.xml", "/rss/channel/item[2]/title" ) );

3.2.3. Method Existence

The following methods check whether methods are available in the browser execution environment.

Method	Argument	Result
HasMethod(string MethodName)	Method name	Boolean result
HasModuleMethod(string MethodName)	Module method name	Boolean result

Example:

form.Message( Fetch.HasMethod("TestMethod") );

For a module method:

form.SetText( "Tag1", Fetch.HasModuleMethod("hello") );

The source explicitly describes HasMethod as checking a method name that can represent either a check function or variable.

3.2.4. Modifier State

GetModifierState checks the state of a keyboard modifier or lock key in the current browser event context.

GetModifierState(string Modifier)

Supported modifier names in the current implementation include:

• Alt
• AltGraph
• Control
• Meta
• Shift
• CapsLock
• NumLock
• ScrollLock

Example:

form.Message( Fetch.GetModifierState("Control") );

This expression returns a Boolean value indicating whether the specified modifier is active.

3.2.5. Math

The Math method provides mathematical operations through the browser runtime.

Math(string MethodName, object[] Args = null)

MethodName identifies the mathematical operation and Args contains its arguments.

Examples:

form.Message(Fetch.Math("max", [12, 26])); form.Message(Fetch.Math("min", [12, 26])); form.Message(Fetch.Math("abs", [-25])); form.Message(Fetch.Math("pow", [2, 8]));

These examples demonstrate maximum, minimum, absolute value, and power operations.

3.2.6. Date

The Date section provides browser date and time values.

Member	Description
DateYear	Current year.
DateMonth	Current month.
DateDay	Current day.
DateDate	Current date.
DateHours	Current hour.
DateMinutes	Current minute.
DateSeconds	Current second.
DateMilliseconds	Current millisecond.

Note: JavaScript months start at index 0, while the WebForms Core DateMonth Fetch value uses month numbering starting at 1.

Example:

form.Message(Fetch.DateYear); form.SetText("Tag1", Fetch.DateDate);

3.2.7. String

The String section provides simple predefined string values.

Member	Description
Space	Represents a space character.
AtSign	Represents the @ character.

Example:

form.SetText("Tag1", Fetch.Space);

The members are defined as Fetch constants in the source.

3.2.8. Tag

The Tag section provides Fetch expressions for obtaining properties and state from an HTML element identified by an Input Place.

Method	Argument	Description
GetId	InputPlace	Gets the element ID.
GetName	InputPlace	Gets the element name.
GetValue	InputPlace	Gets the element value.
GetValueLength	InputPlace	Gets the value length.
GetClass	InputPlace	Gets the class value.
GetStyle	InputPlace	Gets the style value.
GetTitle	InputPlace	Gets the title.
GetLabel	InputPlace	Gets the associated label value.
GetText	InputPlace	Gets the element text.
GetOuterText	InputPlace	Gets outer text.
GetTextLength	InputPlace	Gets text length.
GetAttribute	InputPlace, Attribute	Gets an attribute value.
GetWidth	InputPlace	Gets element width.
GetHeight	InputPlace	Gets element height.
GetIsReadOnly	InputPlace	Gets read-only state.
GetSelectedIndex	InputPlace	Gets selected index.
GetIndex	InputPlace	Gets the element index.
GetTextAlign	InputPlace	Gets text alignment.
GetNodeLength	InputPlace	Gets node length.
GetIsVisible	InputPlace	Gets visibility state.

These methods are all defined in the Tag section of the Fetch class.

3.2.8.1 Reading Element Text

A common use is reading text from one element and assigning it to another.

form.SetText("Tag2", Fetch.GetText("Tag1"));

3.2.8.2 Reading an Input Value

form.Message(Fetch.GetValue("Input1"));

3.2.8.3 Reading an Attribute

form.SetText( "Tag2", Fetch.GetAttribute("Tag1", "title") );

3.2.8.4 Reading Element Dimensions

form.Message(Fetch.GetWidth("Tag1")); form.Message(Fetch.GetHeight("Tag1"));

3.2.8.5 Reading Element State

form.Message(Fetch.GetIsVisible("Tag1")); form.Message(Fetch.GetIsReadOnly("Input1"));

3.2.9. Save and Cache

The Save and Cache section provides Fetch expressions for accessing browser-side saved values and cache values.

Method	Arguments	Description
HasHash	Hash	Checks a hash value.
Cookie	Key	Gets a cookie value.
Save	Key, optional replacement value	Gets or replaces a saved value.
SaveThenRemove	Key	Gets a saved value and removes it.
SaveLength	Key	Gets saved value length.
Cache	Key, optional replacement value	Gets or replaces a cached value.
CacheThenRemove	Key	Gets a cached value and removes it.
CacheLength	Key	Gets cached value length.
SaveLine	Key, Line	Gets a specific saved line.
SaveLineConsume	Key	Gets and consumes a saved line.
SaveINI	Key, INIKey	Gets a direct key from saved INI data.
CacheLine	Key, Line	Gets a specific cached line.
CacheLineConsume	Key	Gets and consumes a cached line.
CacheINI	Key, INIKey	Gets a direct key from cached INI data.

The complete Save and Cache section and its signatures are defined in the Fetch implementation.

3.2.9.1 Save

form.AddSaveValue("TestSave", "Hello"); form.SetText( "Tag1", Fetch.Save("TestSave") );

3.2.9.2 Cache

form.AddCacheValue("TestCache", "Hello"); form.Message( Fetch.Cache("TestCache") );

3.2.9.3 Saved Lines

form.AddSaveValue( "LineTest", "Line 0\nLine 1\nLine 2" ); form.SetText( "Tag1", Fetch.SaveLine("LineTest", 1) );

The Line argument identifies the requested line. The implementation also supports negative indexes for line access.

3.2.9.4 Saved INI Values

form.SetText( "Tag1", Fetch.SaveINI("Settings", "name") );

The source specifies that the INI key used by SaveINI is a direct key.

3.2.10. Format Storage

Format Storage Fetch expressions read data from a browser-side format storage and can select data according to its format.

Method	Arguments	Description
FormatStore	Key	Gets the stored format data.
FormatStoreByXMLQuery	Key, XPath	Gets data using an XPath query.
FormatStoreByJSONQuery	Key, Query	Gets data using a JSON query.
FormatStoreByINI	Key, Name	Gets an INI value.
FormatStoreByText	Key, Line	Gets a text line.
FormatStoreByVariable	Key	Gets a variable value.

These methods are defined directly under the Format Storage section of the Fetch class.

Example:

form.SetText( "Tag1", Fetch.FormatStoreByJSONQuery("data", "article.title") );

3.2.11. State

HasState checks whether a browser state exists for a specified path.

HasState(string Path)

The path can include path, query, and hash components according to the WebForms Core state format.

Example:

form.Message( Fetch.HasState("/fetch?q1=val1&q2=val2") );

The current implementation exposes this method under the State section.

3.2.12. SSE

SSEIsConnected checks whether an SSE connection exists for the specified path.

SSEIsConnected(string Path)

Example:

form.Message( Fetch.SSEIsConnected("/events") );

The method is defined under the SSE section of the Fetch class.

3.2.13. WebSockets

WebSocketsIsConnected checks the connection state of a WebSocket path.

WebSocketsIsConnected(string Path = "")

The path is optional.

Example:

form.Message( Fetch.WebSocketsIsConnected("/chat") );

The Fetch class defines this method under the WebSockets section.

3.2.14. Document

The Document section currently provides the TabIsActive constant.

Member	Description
TabIsActive	Indicates whether the current browser tab is active.

Example:

form.Message(Fetch.TabIsActive);

The member is defined as @da in the Fetch class.

3.2.15. Window

The Window section provides Fetch values related to the browser URL, history, selection, and scrolling.

Member	Description
Href	Current complete URL.
PathName	Current URL path.
Query(string Name = "*")	Gets a query-string value.
Hash	Current URL hash.
Host	Current host.
HostName	Current hostname.
Port	Current port.
Origin	Current origin.
GetSelection	Current browser text selection.
ScrollX	Horizontal scroll position.
ScrollY	Vertical scroll position.
Segment(int Index)	Gets a URL path segment.
HashSegment(int Index)	Gets a hash path segment.

The Window members are defined directly in the Fetch class.

3.2.15.1 URL

form.SetText("Tag1", Fetch.Href); form.Message(Fetch.PathName); form.Message(Fetch.Host);

3.2.15.2 Query

Without an argument, Query() retrieves the query information according to the Fetch implementation. With a name, it targets a specific query parameter.

form.Message(Fetch.Query("id"));

3.2.15.3 URL Segments

form.Message(Fetch.Segment(0)); form.Message(Fetch.Segment(1));

HashSegment is used for hash paths. The source specifies that the hash path must start with the tilde character when this operation is used, for example #~/Segment1/Segment2.

form.Message(Fetch.HashSegment(0));

3.2.15.4 Scrolling and Selection

form.Message(Fetch.ScrollX); form.Message(Fetch.ScrollY); form.Message(Fetch.GetSelection);

3.2.16. Navigator

The Navigator section provides information exposed by the browser navigator environment.

Member	Description
ClipboardText	Clipboard text.
GeoLatitude	Geographical latitude.
GeoLongitude	Geographical longitude.
Language	Browser language.
IsOnLine	Browser online state.
UserAgent	Browser user-agent information.

These members are defined as constants in the Fetch implementation.

Example:

form.Message(Fetch.Language); form.Message(Fetch.IsOnLine); form.SetText("Tag1", Fetch.UserAgent);

3.2.17. Screen

The Screen section provides information about the current screen and screen orientation.

Member	Description
ScreenWidth	Screen width.
ScreenHeight	Screen height.
ScreenOrientationType	Screen orientation type.
ScreenOrientationAngle	Screen orientation angle.

Example:

form.Message(Fetch.ScreenWidth); form.Message(Fetch.ScreenHeight); form.Message(Fetch.ScreenOrientationType); form.Message(Fetch.ScreenOrientationAngle);

The four members are defined in the Fetch Screen section.

3.2.18. Performance

The Performance section provides browser performance timing values.

Member	Description
TimeOrigin	Performance time origin.
PerformanceNow	Current high-resolution performance timestamp.

Example:

form.Message(Fetch.TimeOrigin); form.Message(Fetch.PerformanceNow);

These values are exposed by the Fetch class under the Performance section.

3.2.19. Event

The Event section provides Fetch values associated with the current browser event.

Member	Description
Event	Current event object/value.
EventSerialize	Serialized event data.
EventKey	Keyboard event key.
EventWhich	Event key/code information.
EventClientX	Client X coordinate.
EventClientY	Client Y coordinate.
EventPageX	Page X coordinate.
EventPageY	Page Y coordinate.
EventOffsetX	Offset X coordinate.
EventOffsetY	Offset Y coordinate.
EventDeltaY	Vertical wheel delta.

The complete set of event Fetch constants is defined in the source.

3.2.19.1 Event Key

form.Message(Fetch.EventKey);

3.2.19.2 Event Coordinates

form.Message(Fetch.EventClientX); form.Message(Fetch.EventClientY); form.Message(Fetch.EventPageX); form.Message(Fetch.EventPageY);

3.2.19.3 Event Serialization

form.Message(Fetch.EventSerialize);

Event Fetch expressions are especially useful inside event-driven WebForms execution because the value is obtained from the event currently being processed by WebFormsJS.

3.2.20. Fetch Expressions and WebForms Execution

Fetch expressions become particularly powerful when they are combined with WebForms commands.

For example, an event can read the value of an input and display it without writing application-specific JavaScript.

form.Message(Fetch.GetValue("Input1"));

A value can also be transferred from one element to another:

form.SetText( "Output", Fetch.GetValue("Input1") );

Browser information can be displayed in the same way:

form.SetText("Output", Fetch.PathName);

And a value returned by a module or WebAssembly method can become the input of another WebForms operation:

form.SetText( "Output", Fetch.ModuleMethod("multiply", [12, 26]) );

3.2.21. Fetch in Conditions and Execution Flow

Fetch expressions are not limited to DOM output. Because they produce values inside the WebForms execution environment, they can also participate in conditions and other execution-flow operations.

For example, browser state can be checked through a Fetch expression:

form.IsTrue( Fetch.HasState("/fetch?q1=val1") );

Similarly, method availability can be tested:

form.IsTrue( Fetch.HasMethod("TestMethod") );

This allows the browser to provide runtime information to the WebForms execution flow without requiring a separate application-specific JavaScript implementation.

3.2.22. Fetch and the Browser Runtime

Fetch expressions illustrate an important part of the WebForms Core execution model. The server-side WebForms class can construct an Action Control containing a Fetch expression without knowing the current browser value.

For example:

form.SetText("Status", Fetch.GetValue("Input1"));

The server does not need to know the value of Input1. WebFormsJS resolves the expression in the browser when the Action Control is executed.

The same model applies to values such as the current URL, event coordinates, screen dimensions, browser language, DOM properties, saved values, cache values, and results returned from JavaScript modules or WebAssembly.

3.2.23. Complete Fetch Demonstration

The following example demonstrates several Fetch categories using Message and SetText.

WebForms form = new WebForms(); form.Message(Fetch.Random(15, 35)); form.Message(Fetch.SpaceToChar("Hello World", "_")); form.Message(Fetch.EncodeURI("Hello World & Test")); form.SetText( "Tag1", Fetch.GetText("Tag2") ); form.Message( Fetch.GetValue("Input1") ); form.Message( Fetch.GetAttribute("Tag1", "title") ); form.Message(Fetch.DateDate); form.Message(Fetch.PathName); form.Message(Fetch.ScreenWidth); form.Message(Fetch.Language); form.Message(Fetch.IsOnLine); form.Message(Fetch.EventKey); form.Message(Fetch.EventClientX); form.Message(Fetch.EventClientY); Write(form.ExportToHtmlComment());

In this example, the server generates the WebForms commands, while the actual Fetch values are resolved by WebFormsJS at runtime.

3.2.24. Fetch API Reference

The following table summarizes all public members currently grouped inside the Fetch class.

Section	Members
Method	Random, SpaceToChar, EncodeURI, DecodeURI, Method, ModuleMethod, WasmMethod, Script, LoadUrl, LoadHtml, LoadLine, LoadINI, LoadJSON, LoadXML
Method Existence	HasMethod, HasModuleMethod
Modifier State	GetModifierState
Math	Math
Date	DateYear, DateMonth, DateDay, DateDate, DateHours, DateMinutes, DateSeconds, DateMilliseconds
String	Space, AtSign
Tag	GetId, GetName, GetValue, GetValueLength, GetClass, GetStyle, GetTitle, GetLabel, GetText, GetOuterText, GetTextLength, GetAttribute, GetWidth, GetHeight, GetIsReadOnly, GetSelectedIndex, GetIndex, GetTextAlign, GetNodeLength, GetIsVisible
Save and Cache	HasHash, Cookie, Save, SaveThenRemove, SaveLength, Cache, CacheThenRemove, CacheLength, SaveLine, SaveLineConsume, SaveINI, CacheLine, CacheLineConsume, CacheINI
Format Storage	FormatStore, FormatStoreByXMLQuery, FormatStoreByJSONQuery, FormatStoreByINI, FormatStoreByText, FormatStoreByVariable
State	HasState
SSE	SSEIsConnected
WebSockets	WebSocketsIsConnected
Document	TabIsActive
Window	Href, PathName, Query, Hash, Host, HostName, Port, Origin, GetSelection, ScrollX, ScrollY, Segment, HashSegment
Navigator	ClipboardText, GeoLatitude, GeoLongitude, Language, IsOnLine, UserAgent
Screen	ScreenWidth, ScreenHeight, ScreenOrientationType, ScreenOrientationAngle
Performance	TimeOrigin, PerformanceNow
Event	Event, EventSerialize, EventKey, EventWhich, EventClientX, EventClientY, EventPageX, EventPageY, EventOffsetX, EventOffsetY, EventDeltaY

3.2.25. Summary

The Fetch class provides the value-oriented side of WebForms Core execution. While WebForms methods describe what operation should be performed, Fetch expressions describe where the value used by that operation should come from.

This includes values from the DOM, browser window, document, navigator, screen, current event, browser storage, format storage, URL, state, SSE, WebSockets, JavaScript methods, JavaScript modules, WebAssembly, external resources, and mathematical or date operations.

The important characteristic is that these values are resolved by WebFormsJS in the browser. The server can therefore construct a command such as SetText without first obtaining the browser value itself.

Fetch consequently forms an important bridge between server-generated Action Controls and the live browser environment.