Class

WebSession


Description

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.

Methods

Name

Parameters

Returns

Shared

ExecuteJavaScript

script As String

HasPage

page As WebPage

Boolean

HasPageNamed

viewName As String, implicitOnly As Boolean = False

Boolean

Header

name As String

String

HeaderAt

index As Integer

HeaderCount

Integer

PageAt

index As Integer

WebPage

PageCount

Integer

Pages

Iterable

PageWithName

pageName As String, implicitOnly As Boolean

WebPage

Quit

RawHeaders

String

RecordData

key As String, value As String

RemoveData

Key As String

RequestData

Key As String

SaveState

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

Secure

Boolean

URLParameter

name As String

String

URLParameterCount

Integer

URLParameterExists

name As String

Boolean

URLParameterName

zeroBasedIndex As Integer

String

Property descriptions


WebSession.AllowTabOrderWrap

AllowTabOrderWrap As Boolean

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


WebSession.ClientHeight

ClientHeight As Integer

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

This property is read-only.

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


WebSession.ClientTime

ClientTime As DateTime

This property is read-only.


WebSession.ClientWidth

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.


WebSession.ConfirmDisconnectMessage

ConfirmDisconnectMessage As String

Whether this message appears and how it appears is determined by the web browser. You should only set this property in the Inspector. Changing it in code will not likely do anything.

The dialog may also not appear if the user has not interacted with the page in some way.


WebSession.Cookies

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

WebSession.CurrentPage

CurrentPage As WebPage

Sets the Session page:

Var page As New MainPage
Session.CurrentPage = page

WebSession.DisconnectMessage

DisconnectMessage As String


WebSession.Hashtag

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.Open event and display different content accordingly.


WebSession.Identifier

Identifier As String

Returns the unique session identifier string.

This property is read-only.


WebSession.InterruptionMessage

InterruptionMessage As String


WebSession.IsDarkMode

IsDarkMode As Boolean

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

This property is read-only.


WebSession.LanguageCode

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.

This property is read-only.


WebSession.LanguageRightToLeft

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.


WebSession.Platform

Platform As String

Specifies the platform being used for this session.

This property is read-only.


WebSession.RemoteAddress

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)

WebSession.ScaleFactor

ScaleFactor As Double

Reflects the ScaleFactor of the current session.

This property is read-only.


WebSession.URL

URL As String

Returns the URL to the session.

This property is read-only.


WebSession.UserTimeout

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


WebSession.ExecuteJavaScript

ExecuteJavaScript(script As String)

Executes the JavaScript passed.


WebSession.HasPage

HasPage(page As WebPage) As Boolean

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


WebSession.HasPageNamed

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.


WebSession.Header

Header(name As String) As String

Returns the value of the HTTP header specified.


WebSession.HeaderAt

HeaderAt(index As Integer)

Returns the HTML header at the index passed.


WebSession.HeaderCount

HeaderCount As Integer

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


WebSession.PageAt

PageAt(index As Integer) As WebPage

Returns the instance of the WebPage at the index passed.


WebSession.PageCount

PageCount As Integer

Returns the number of open pages in the session.


WebSession.Pages

Pages As Iterable

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


WebSession.PageWithName

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.


WebSession.Quit

Quit

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


WebSession.RawHeaders

RawHeaders As String

Returns the raw header information.

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

Sample raw header:

Host:127.0.0.1:8080 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

WebSession.RecordData

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.


WebSession.RemoveData

RemoveData(key As String)

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


WebSession.RequestData

RequestData(key As String)

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


WebSession.SaveState

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 </api/web/websession> 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.


WebSession.Secure

Secure As Boolean

Gets the SSL status of the WebPage.


WebSession.URLParameter

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:

http://example.com?my_favorite_number=42&my_name=Ford

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.Open 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)
  Next
End If

WebSession.URLParameterCount

URLParameterCount As Integer

Returns the number of parameters that were specified in the URL


WebSession.URLParameterExists

URLParameterExists(name As String) As Boolean

Returns True if the specified parameter was in the URL.


WebSession.URLParameterName

URLParameterName(zeroBasedIndex As Integer) As String

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

Event descriptions


WebSession.Activated

Activated

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.


WebSession.AllowUnsupportedBrowser

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.


WebSession.AppearanceChanged

AppearanceChanged(isDarkMode As Boolean)

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


WebSession.Closing

Closing

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.


WebSession.Deactivated

Deactivated

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.


WebSession.HashtagChanged

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)

WebSession.JavaScriptError

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


WebSession.Opening

Opening

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


WebSession.OrientationChanged

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


WebSession.PreparingSession

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.


WebSession.RequestedData

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.


WebSession.ScaleFactorChanged

ScaleFactorChanged

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.


WebSession.UnhandledException

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

WebSession.UserDisconnected

UserDisconnected

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


WebSession.UserTimedOut

UserTimedOut

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

Notes

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.


Databases

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.

Compatibility

Web projects on all supported operating systems.

See also

Object parent class; Session, WebSessionContext classes.