Client Profiles

Wisej.NET has a unique and extremely powerful responsive system that is not limited to CSS and the media selectors used by plain HTML+CSS systems. The responsive system in Wisej is based on two features: Responsive Properties and Client Profiles.

Client Profiles are a set of device-related properties associated to a name that are matched to the client device when the page is loaded or the browser is resized.

Responsive Properties are standard .NET properties available at design time (serializable) that are decorated with the [ResponsiveProperty] attribute. These properties are capable of holding multiple values associated with a Client Profile.

The process is simple, Wisej reads the client profiles in ClientProfiles.json, and from the top down matches the properties with the current information received from the browser; the first match becomes the Application.ActiveProfile and fires the ResponsiveProfileChanged event.

When the ActiveProfile changes, all the [ResponsiveProperties] are updated with the value their value associated to the Client Profile. For example, the Visible property or a button can hold the value true when the Client Profile is "Default" and the value false when the Client Profile is "Galaxy Tablet", or the Display property of a Button or TabControl can be Both on Desktops and Icon on Phone devices.

Custom ClientProfiles.json

You can define your custom client profiles by adding the ClientProfiles.json file to the project. Click Add -> New Item, select Wisej.NET 3 and select ClientProfiles:

It will add the file ClientProfiles.json containing the pre-configured profiles:

/**
 * Client Profiles
 *
 * You can add additional profiles or modify the default ones by
 * placing a ClientProfiles.json file in the /bin directory of the
 * application.
 *
 * Or add it to the root files and set it to: "EmbeddedResource", or "Content" or "Copy if newer".
 *
 * Profiles with names matching the names in the default file will
 * override the corresponding matching profile definition.
 *
 * Profile Properties:
 *
 *	name:            The name of the profile.
 *	minWidth:        The minimum width of browser in pixels.
 *	maxWidth:        The maximum width of browser in pixels.
 *	minScreenWidth:  The minimum width of the device in pixels.
 *	maxScreenWidth:  The maximum width of the device in pixels.
 *	device:          A string or regular expression to match the name of the device returned by the client browser ("Mobile", "Tablet" or "Desktop").
 *	userAgent:       A string or regular expression to match the user-agent string returned by the client browser.
 *	landscape:       A boolean flag that indicates that the profile matches devices in landscape mode.
 */
{
    "profiles": [
        {
            "name": "Phone",
            "device": "Mobile",
            "landscape": false
        },
        {
            "name": "Phone (Landscape)",
            "device": "Mobile",
            "landscape": true
        },
        {
            "name": "Tablet",
            "device": "Tablet",
            "landscape": false
        },
        {
            "name": "Tablet (Landscape)",
            "device": "Tablet",
            "landscape": true
        },
        {
            "name": "Small Desktop",
            "device": "Desktop",
            "maxWidth":  1024
        }
    ]
}

Property	Description
name	Unique name assigned to the profile. I.e. "Large Monitor", "Galaxy Tablet", "Airport Kiosk", etc.
minWidth	When > 0 this is the minimum browser width required to qualify the profile. I.e. set it to 500 and it will qualify only when the browser width is >= 500px.
maxWidth	When > 0 this is the maximum browser width required to qualify the profile. I.e. set it to 1500 and it will qualify only when the browser width is <= 1500px.
minScreenWidth	When > 0 this is the minimum screen width required to qualify the profile. I.e. set it to 500 and it will qualify only when the screen width is >= 500px.
maxScreenWidth	When > 0 this is the maximum screen width required to qualify the profile. I.e. set it to 1500 and it will qualify only when the screen width is <= 1500px.
device	A regular expression that matches the type of device detected by the browser. The value returned by the browser can only be: "Desktop", "Mobile", or "Tablet". If you set this value to "Desktop", this profile will qualify only for desktops. If you set it to a regular expression like this "(Tablet)|(Mobile)" it will qualify for either a "Tablet" or a "Mobile".
userAgent	This is also a regular expression applied to the user agent returned by the browser. You can use this property to detect a specific OS version, or specific browser.
landscape	This is a simple boolean that is true when the width of the browser is bigger than the height.

When using the Chrome mobile emulator and switch to a mobile from a desktop, you may have to hit refresh to update client profiles based on screen width or user agents since these two properties don't change dynamically.

ResponsiveProfileChanged

The ResponsiveProfileChanged event is fired on:

• Application

• ContainerControl (Form, Page, Desktop, UserControl)

• DataGridView

• LIstView

Handling this event allows your code to adapt the controls to the client profile in any way possible. While responsive properties are useful and easy to use (especially at design time), they are limited. In code, handling this event, you can adjust the control without limitations.