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. ## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |-----------------------------------------------------------------|-----------------------------------------------|-----------|--------| | `AllowTabOrderWrap` | `Boolean` | | | | `ClientHeight` | `Integer` | ✓ | | | `ClientTime` | `DateTime` | ✓ | | | `ClientWidth` | `Integer` | ✓ | | | `ColorMode` | `ColorModes` | | | | `ConfirmDisconnectMessage` | `String` | | | | `Cookies` | `WebCookieManager` | ✓ | | | `CurrentPage` | `WebPage` | | | | `DisconnectMessage` | `String` | | | | `Hashtag` | `String` | | | | `Identifier` | `String` | ✓ | | | `InterruptionMessage` | `String` | | | | `IsDarkMode` | `Boolean` | ✓ | | | `LanguageCode` | `String` | | | | `LanguageRightToLeft` | `Boolean` | ✓ | | | `LazyLoadDependencies` | `Boolean` | | | | `Platform` | `String` | ✓ | | | `RemoteAddress` | `String` | ✓ | | | `ScaleFactor` | `Double` | ✓ | | | `SendEventsInBatches` | `Boolean` | | | | `Title` | `String` | | | | `URL` | `String` | ✓ | | | `UserPrefersDarkMode` | `Boolean` | ✓ | | | `UserTimeout` | `Integer` | | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |-----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|--------| | `ExecuteJavaScript` | script As `String` | | | | `GotoURL` | URL As `String`, inNewWindow As `Boolean` = `False` | | | | `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` | | ## Events

table-centered_column_4

| Name | Parameters | Returns | |---------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| | `Activated` | | | | `AllowUnsupportedBrowser` | `ByRef` errorMessage As `String`, `ByRef` sendAsHTML As `Boolean` | | | `AppearanceChanged` | isDarkMode As `Boolean`, userPrefersDarkMode As `Boolean` | | | `Closing` | appQuitting As `Boolean` | | | `Deactivated` | visible As `Boolean` | | | `HashtagChanged` | name As `String`, data As `String` | | | `JavaScriptError` | errorMessage As `String`, userDetails As `String` | `Boolean` | | `Opening` | | | | `OrientationChanged` | angle As `Integer` | | | `PreparingSession` | `ByRef` HTMLHeader As `String` | | | `RequestedData` | key As `String`, value As `String` | | | `ScaleFactorChanged` | | | | `UnhandledException` | error As `RuntimeException` | `Boolean` | | `UserDisconnected` | | | | `UserTimedOut` | | | ## Enumerations

forsearch

WebSession.ColorModes ### ColorModes > 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. > > | Enum | > |-------| > | Auto | > | Dark | > | Light | ## Property descriptions

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

WebSession.AllowTabOrderWrap **AllowTabOrderWrap** As `Boolean` > Setting this property after the `Opening` event will raise an UnsupportedOperationException.

forsearch

WebSession.ClientHeight **ClientHeight** As `Integer` > The height of the client's browser when the session began. > > 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. > > This property is updated anytime the browser window is resized. > > This property is read-only.

forsearch

WebSession.ClientTime **ClientTime** As `DateTime` > Returns a current time DateTime object, with the user's time zone. > > This property is read-only.

forsearch

WebSession.ClientWidth **ClientWidth** As `Integer` > The width of the client's browser when the session beqan. > > 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. > > This property is updated anytime the browser window is resized. > > This property is read-only.

forsearch

WebSession.ColorMode **ColorMode** As `ColorModes` > Indicates how the user interface will be drawn (Auto, Light or Dark). Auto means that it will use the OS setting.

forsearch

WebSession.ConfirmDisconnectMessage **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. > >

> >

> > Note > >

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

forsearch

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: > > ``` xojo > Var cookieCount As Integer > cookieCount = Session.Cookies.Count > ```

forsearch

WebSession.CurrentPage **CurrentPage** As `WebPage` > Sets the Session page: > > ``` xojo > Var page As New MainPage > Session.CurrentPage = page > ```

forsearch

WebSession.DisconnectMessage **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.

forsearch

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

forsearch

WebSession.Identifier **Identifier** As `String` > Returns the unique session identifier string. > > This property is read-only.

forsearch

WebSession.InterruptionMessage **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.

forsearch

WebSession.IsDarkMode **IsDarkMode** As `Boolean` > If `True`, the user's browser is set to Dark Mode. > > This property is read-only.

forsearch

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.

forsearch

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.

forsearch

WebSession.LazyLoadDependencies **LazyLoadDependencies** As `Boolean` > If `True`, this experimental feature will only load the libraries upon which the web framework depends to manage the client side webpage as needed. For example, the library used to manage maps will only be loaded if the page has a `WebMapViewer` on it. This results in webpages loading faster. > >

> >

> > Important > >

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

forsearch

WebSession.Platform **Platform** As `String` > Specifies the platform being used for this session. > > This property is read-only.

forsearch

WebSession.RemoteAddress **RemoteAddress** As `String` > The session's client IP address. > > This property is read-only. > > Displays the IP address of the client browser: > > ``` xojo > MessageBox("IP Address = " + Self.RemoteAddress) > ```

forsearch

WebSession.ScaleFactor **ScaleFactor** As `Double` > Reflects the ScaleFactor of the current session. > > This property is read-only.

forsearch

WebSession.SendEventsInBatches **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. > >

> >

> > Important > >

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

forsearch

WebSession.Title **Title** As `String` > The title of the session. The title that appears in the browser is the title fo the currently displayed page. As pages are shown, the title updates accordingly. > > If it isn't empty, it will override the current `WebPage.Title` property.

forsearch

WebSession.URL **URL** As `String` > Returns the URL to the session. > > This property is read-only.

forsearch

WebSession.UserPrefersDarkMode **UserPrefersDarkMode** As `Boolean` > If `True`, the device is in dark mode. > > This property is read-only.

forsearch

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 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: > > ``` xojo > Self.UserTimeout = 30 > ``` ## Method descriptions

forsearch

WebSession.ExecuteJavaScript **ExecuteJavaScript**(script As `String`) > Executes the JavaScript passed.

forsearch

WebSession.GotoURL **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: > > ``` xojo > Session.GotoURL("http://www.wikipedia.org", True) > ```

forsearch

WebSession.HasPage **HasPage**(page As `WebPage`) As `Boolean` > Returns `True` if the `page` passed is currently instantiated within the current WebSession.

forsearch

WebSession.HasPageNamed **HasPageNamed**(viewName As `String`, implicitOnly As `Boolean` = `False`) As `Boolean` > Returns `True` if the *viewName* passed is currently instantiated within the current WebSession. If *implicitOnly* is `True` then only implicit instances of pages are considered.

forsearch

WebSession.Header **Header**(name As `String`) As `String` > Returns the value of the HTTP header specified.

forsearch

WebSession.HeaderAt **HeaderAt**(index As `Integer`) > Returns the HTML header at the *index* passed.

forsearch

WebSession.HeaderCount **HeaderCount** As `Integer` > Returns the number of HTTP headers sent when the session was created.

forsearch

WebSession.PageAt **PageAt**(index As `Integer`) As `WebPage` > Returns the instance of the `WebPage` at the *index* passed.

forsearch

WebSession.PageCount **PageCount** As `Integer` > Returns the number of open pages in the session.

forsearch

WebSession.Pages **Pages** As `Iterable` > Allows you to iterate through all the `webpages` of a WebSession.

forsearch

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 *implicitOnly* is `False`, this method will return the first page which matches name.

forsearch

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

forsearch

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: > > ``` xojo > Me.Text = Session.RawHeaders > ```

forsearch

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.

forsearch

WebSession.RemoveData **RemoveData**(key As `String`) > Removes the Key/Value pair saved via the `RecordData` method.

forsearch

WebSession.RequestData **RequestData**(key As `String`) > Requests the Key/Value pair saved via the `RecordData` method. The data is also returned via the `RequestedData` event.

forsearch

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

forsearch

WebSession.Secure **Secure** As `Boolean` > Gets the SSL status of the WebPage.

forsearch

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: > > ``` plain > 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: > > ``` plain > http://127.0.0.1:8080/?test=hello > ``` > > This code in the Session.Opening event handler displays the URL parameters in a Text Area on the main web page: > > ``` xojo > 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.Text = WebPage1.TextArea1.Text + parameterName + " = " + value + EndOfLine > Next > End If > ```

forsearch

WebSession.URLParameterCount **URLParameterCount** As `Integer` > Returns the number of parameters that were specified in the URL

forsearch

WebSession.URLParameterExists **URLParameterExists**(name As `String`) As `Boolean` > Returns `True` if the specified parameter was in the URL.

forsearch

WebSession.URLParameterName **URLParameterName**(zeroBasedIndex As `Integer`) As `String` > Returns the name of the URL parameter based on the specified index. ## Event descriptions

forsearch

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.

forsearch

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.

forsearch

WebSession.AppearanceChanged **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.

forsearch

WebSession.Closing **Closing**(appQuitting As `Boolean`) > The current session is closing. > > This is where you do any cleanup after as the session is in the process of closing. *appQuitting* will be `True` if (and only if) the developer is calling the `WebApplication.Quit` method. > > 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.

forsearch

WebSession.Deactivated **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.

forsearch

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: > > ``` xojo > MessageBox("Hashtag = " + Self.HashTag) > ```

forsearch

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

forsearch

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

forsearch

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

forsearch

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.

forsearch

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.

forsearch

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

forsearch

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. > > ``` xojo > 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 > ```

forsearch

WebSession.UserDisconnected **UserDisconnected** > The user closed the tab or window in which the app was running.

forsearch

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 | | | |-----------------------|-----| | **Project Types** | Web | | **Operating Systems** | All |

`Object` parent class; `Session`, `WebSessionContext` classes.