This is the base class for the Session class that is included in all web projects. Each user session gets its own instance of WebSession that you can access using the Session method.







script As String


URL As String, InNewWindow As Boolean = False


page As WebPage



viewName As String, implicitOnly As Boolean = False



name As String



index As Integer




index As Integer







pageName As String, implicitOnly As Boolean






key As String, value As String


Key As String


Key As String


name As String, data As String, replace As Boolean = False




name As String





name As String



zeroBasedIndex As Integer








ByRef errorMessage As String, ByRef sendAsHTML As Boolean


isDarkMode As Boolean, userPrefersDarkMode As Boolean



visible As Boolean


name As String, data As String


errorMessage As String, userDetails As String




angle As Integer


ByRef HTMLHeader As String


key As String, value As String



error As RuntimeException







Determines which the style in which the user interface will be drawn. If Auto is selected, it will be drawn based upon the settings of the OS.





Property descriptions


AllowTabOrderWrap As Boolean

Setting this property after the Opening event will raise an UnsupportedOperationException.


ClientHeight As Integer

The height of the client's browser when the session began.

This property is read-only.

If your app has different sized layouts for different sized browsers (both desktop and mobile browsers for example), the ClientHeight (and ClientWidth) property can be used to determine which layout to show.


ClientTime As DateTime

This property is read-only.


ClientWidth As Integer

The width of the client's browser when the session beqan.

This property is read-only.

If you app has different sized layouts for different sized browsers (both desktop and mobile browsers for example), the ClientWidth (and ClientHeight) property can be used to determine which layout to show.


ColorMode As ColorModes

Indicates how the user interface will be drawn (Auto, Light or Dark). Auto means that it will use the OS setting.


ConfirmDisconnectMessage As String

If the user is about to move away from the application, the app will display a message informing the user of this and asking them if they wish to stay on the page or not. This property allows you to provide your own custom message. If it is left empty, no confirmation dialog box will be displayed.


It is up to the browser to display a generic confirmation text or your custom message.


Cookies As WebCookieManager

This property is read-only.

The class instance should be accessed directly rather than copied to a variable and accessed. For example, to get the number of cookies:

Var cookieCount As Integer
cookieCount = Session.Cookies.Count


CurrentPage As WebPage

Sets the Session page:

Var page As New MainPage
Session.CurrentPage = page


DisconnectMessage As String

When the connection is dropped between the user and the application and cannot be reestablished, the app will display a message informing the user. This property allows you to provide your own custom message.


Hashtag As String

A tag associated with a bookmarked page. Hashtags are also called anchors or URL fragments.The developer may change this at any time and the browser's URL field will update immediately without causing a page reload. If the user creates a bookmark, any tag supplied will be saved with it. The developer can read this value in the Session.Opening event and display different content accordingly.


Identifier As String

Returns the unique session identifier string.

This property is read-only.


InterruptionMessage As String

If the connection is interrupted, the app will inform the user that it is trying to reestablish the connection. This property allows you to provide your own custom message.


IsDarkMode As Boolean

If True, the user's browser is set to Dark Mode.

This property is read-only.


LanguageCode As String

When a browser connects to a web application and a new session is created, this property is set to the IETF Language Code provided by the browser. This code is used to help determine how dynamic constants will be rendered in your web application. One advantage to this system is that if you do not provide a translation for the user's language, you can offer them a choice and set this value to a supported language code. You can either use raw IETF language codes or the constants from the Localization module.


LanguageRightToLeft As Boolean

Indicates that the browser should draw the current language Right-to-Left In certain cases, languages are typically drawn from right to left. These languages include Arabic, Farsi, Hebrew, Urdu and Yiddish. If the LanguageCode property is set to any of these languages, this property will be automatically set to True.

This property is read-only.


Platform As String

Specifies the platform being used for this session.

This property is read-only.


RemoteAddress As String

The session's client IP address.

This property is read-only.

Displays the IP address of the client browser:

MessageBox("IP Address = " + Self.RemoteAddress)


ScaleFactor As Double

Reflects the ScaleFactor of the current session.

This property is read-only.


SendEventsInBatches As Boolean

If True, this experimental feature will send events in groups which has two potentially beneficial effects. First, layouts with many controls may be more responsive. Second, the events arrive in a specific order allowing you as the developer to be able to rely upon that order in your code.


This feature is experimental so use it with caution. Please provide us with feedback on your experience with it.


URL As String

Returns the URL to the session.

This property is read-only.


UserPrefersDarkMode As Boolean

If True, the device is in dark mode.

This property is read-only.


UserTimeout As Integer

The number of seconds the end-user can be idle before the UserTimedOut event fires. Set this value to zero to disable the timeout. The default value is 0 seconds. Whether or not the user is idle is determined by the Mouse, Key and Touch events on the browser itself.

This example is in the Opening event:

Self.UserTimeout = 30

Method descriptions


ExecuteJavaScript(script As String)

Executes the JavaScript passed.


GotoURL(URL As String, inNewWindow As Boolean = False)

Opens the passed URL in place of the current web page or downloads a file. If InNewWindow is True, the browser is asked to open the URL in a new window.

If the browser has popup windows disabled and InNewWindow is True, the method silently fails and the page is not shown.

If InNewWindow is False, the running web app is replaced with the specified URL. If you want to display an external web site within your web app, use the WebHTMLViewer control.

Display a web site in a new popup window:

Session.GotoURL("", True)


HasPage(page As WebPage) As Boolean

Returns True if the page passed is currently instantiated within the current WebSession.


HasPageNamed(viewName As String, implicitOnly As Boolean = False) As Boolean

Returns True if the pageName passed is currently instantiated within the current WebSession. If implicitOnly is true then only implicit instances of pages are considered.


Header(name As String) As String

Returns the value of the HTTP header specified.


HeaderAt(index As Integer)

Returns the HTML header at the index passed.


HeaderCount As Integer

Returns the number of HTTP headers sent when the session was created.


PageAt(index As Integer) As WebPage

Returns the instance of the WebPage at the index passed.


PageCount As Integer

Returns the number of open pages in the session.


Pages As Iterable

Allows you to iterate through all the webpages of a WebSession.


PageWithName(pageName As String, implicitOnly As Boolean) As WebPage

Attempts to find a page in the session with the name supplied in PageName. If ImplicitOnly is true, this method will return only the implicit instance version of the page. If ImplicitInstance is false, this method will return the first page which matches name.



Ends the session.

WebSession.Quit sends a message to the browser to close and tells the WebSession object that it has expired. There is still a short period of time where the session will be alive though, at least until the next time the framework looks for expired sessions.

WebSession.Quit does not end the session if called from the WebSession.Opening event.


RawHeaders As String

Returns the raw header information.

The raw header contains information about the browser, platform and other settings.

Sample raw header:

Host: Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Cookie:sessionid=fc827d5d805d8088f85a20d035d0d939; ToDoUser=Paul User-Agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/537.75.14 Accept-Language:en-us Accept-Encoding:gzip, deflate Connection:keep-alive

Displays the raw header information in a Text Area. This code is in the Shown event handler:

Me.Text = Session.RawHeaders


RecordData(key As String, value As String)

Stores a key/value pair on the browser itself.

This data is stored outside the scope of the system and is persistent for all intents and purposes. It is however up to the browser how long to keep the data.


RemoveData(key As String)

Removes the Key/Value pair saved via the RecordData method.


RequestData(key As String)

Requests the Key/Value pair saved via the RecordData method. The data is also returned via the RequestedData event.


SaveState(name As String, data As String, replace As Boolean = False)

Saves the Name/Data pair to a per-session stack so you can restore the page when the user returns via their browser's Back button.

When the user navigates between pages, the HashTagChanged event will then fire and pass back to you the Name/Data pair you previously saved from the top of the stack. The Name is automatically used as the page's hashtag. The data is whatever you need to restore the contents of the page. It can be in any form that String supports.

You can call SaveState at any time while a page is present. Passing True for the Replace parameter, replaces the Name/Data pair saved the last time SaveState was called with the new Name/Data pair.

Data is only removed from this stack when you save a new state in the middle of the stack. For instance, if you were to save the state five times, press BACK twice and save again, it would remove the old fourth and fifth items and add the new one to the end.

The stack is stored client-side with the browser.


Secure As Boolean

Gets the SSL status of the WebPage.


URLParameter(name As String) As String

Returns the value of the specified URL parameter. If the parameter was specified more than once, the value will be a comma separated list of values.

The URL parameter are the special values that are passed along with the URL after the "?" character. For example:

Additional parameters are separated by the "&" character. Note that all parameters must be URL encoded (%20 instead of spaces, for example).

If the requested URL parameter is not available, this function returns "".

For URLs that contain a port number, you have to include a "/" before the first parameter:

This code in the Session.Opening event handler displays the URL parameters in a Text Area on the main web page:

If Self.URLParameterCount > 0 Then
  Var parameterName, value As String
  For i As Integer = 0 To Self.URLParameterCount - 1
    parameterName = Self.URLParameterName(i)
    value = Self.URLParameter(parameterName)
    WebPage1.TextArea1.AppendText(parameterName + " = " + value + EndOfLine)
End If


URLParameterCount As Integer

Returns the number of parameters that were specified in the URL


URLParameterExists(name As String) As Boolean

Returns True if the specified parameter was in the URL.


URLParameterName(zeroBasedIndex As Integer) As String

Returns the name of the URL parameter based on the specified index.

Event descriptions



The window in which the app is running has been maximized, has gained the focus or the tab in which the app is running has been made frontmost.


AllowUnsupportedBrowser(ByRef errorMessage As String, ByRef sendAsHTML As Boolean)

Called when an unsupported browser connects to the web application.

By default, if you do nothing in this event, an unsupported browser will be shown an error page containing a list of links to the browsers we support.

If you wish to override this behavior, you can:

  • Set the ErrorMessage property. You may use either plain text or HTML in this field.

  • If you wish to use HTML in the ErrorMessage property, you must set the SendAsHTML property to True.

  • If you wish to allow the browser to connect anyway, you may return True.

The default page for unsupported browsers shows a list of browsers that we do support with links to download them.

Web apps run best on modern open-standards browsers. This includes Apple Safari and Google Chrome. Web applications should also work well in Firefox and in Internet Explorer 8 and above.


AppearanceChanged(isDarkMode As Boolean, userPrefersDarkMode As Boolean)

The browser's appearance has changed from light mode to dark mode or the inverse.

userPrefersDarkMode will be True if the device is dark mode.



The current session is closing.

This is where you do any cleanup after as the session is in the process of closing.

A session begins to close automatically when the user navigates away from your app. This could be by navigating to another URL or by closing the tab or window. You can manually end a session by redirecting the user away from the app yourself using ShowURL. After the user navigates away, the session automatically closes when the UserTimeOut property value is reached. The default is 3 minutes. If the user returns to your app (via Back or re-entering the URL) before the timeout, then the session will still be available for use.


Deactivated(visible As Boolean)

The window in which the app is running has been minimized, has lost the focus or the tab in which the app is running is no longer frontmost.

If Visible is true, the page is still visible to the user. The ability to detect this is dependent upon the browser supporting this capability.


HashtagChanged(name As String, data As String)

Called when the user modifies the Hashtag in the browser address bar or when SaveState is called.

The Hashtag feature is not limited to just simple bookmarking. For example, a single page with a list of records could change the tag whenever the record changes. By implementing the HashtagChanged event, the current record can be changed only by entering the correct tag in the URL.

Displays the hash tag that the user entered in the address bar:

MessageBox("Hashtag = " + Self.HashTag)


JavaScriptError(errorMessage As String, userDetails As String) As Boolean

A JavaScript error ErrorMessage occurred.

A JavaScript error indicates the web browser and the server app are out of sync. When this happens you should usually record the ErrorMessage and UserDetails and close the Session. Further interaction with the browser is not recommended, but since your app is still running on the server, you can save the results to a file or database.

By default, the framework will also write the ErrorMessage and UserDetails to a text file named Errors.log next to your web application. Returning True will prevent the error from being written to this file.

If the web application cannot create Errors.log, it will silently fail, but when running in Debug mode a message is written to the Messages area: "Could not log to errors.log, IOException."



The session has started. This is a good place to do any initialization that is session/user specific.


OrientationChanged(angle As Integer)

Fires when the connected device orientation changes.

Angle can be these values:

  • 0 = Portrait

  • 90 = Landscape Left

  • 180 = Upside Down

  • -90 = Landscape Right


PreparingSession(ByRef HTMLHeader As String)

The event occurs before the Opening event which allows you to modify the HTMLHeader if necessary to do things like adding custom Javascript libraries, fonts, etc.


RequestedData(key As String, value As String)

Fires in response to the RequestData method being called.

This event fires asynchronously in response to the RequestData method.



Called if/when the user moves their browser between screens if the ScaleFactor has changed. Note: The built-in controls automatically request new images when ScaleFactor changes.


UnhandledException(error As RuntimeException) As Boolean

Receives otherwise missed exceptions — exceptions that could have been caught in an Exception statement using one of the Runtime exception handlers.

If the appropriate Exception statement is missing, the runtime exception error triggers this event and allows you to handle exceptions here. See the example.

Returns a Boolean. If it returns True, the standard alert indicating an unhandled exception and quit behavior are suppressed. Return False to allow the default unhandled exception error processing to occur. See the RuntimeException class.

This code in the UnhandledException event of the WebSession class “catches” the unhandled OutOfBoundsException. Of course, it catches all unhandled OutOfBoundsExceptions throughout the application, so it doesn't know where the error occurred. You could instead place an Exception statement within a DesktopButton.Pressed event so that you can provide more specific diagnostics.

Function UnhandledException(error As RuntimeException) As Boolean
  If error <> Nil Then
    Var type As String = Introspection.GetType(error).Name
    MessageBox(type + EndOfLine + EndOfLine + String.FromArray(error.Stack, EndOfLine))
  End If
End Function



The user closed the tab or window in which the app was running.



The user's browser has been idle for the period specified by the UserTimeout property.


Use the Session object to access the current user session.

To refer to the current Session from within the Session object, use Self instead of Session as the prefix, especially in the Opening event because it may return Nil.


If your application is going to connect to a database server, you will want to store the database connection in a property of the Session class. This will allow your application to make connections to the server on a user-by-user basis.

Query parameters

To access the query parameters, use the URLParameter methods to retrieve the query parameters from the Session object.


Web projects on all supported operating systems.

See also

Object parent class; Session, WebSessionContext classes.