Web Specific Concepts

Screen Sizes in BrightWeb

BrightWeb provides support for form aspects similar to BrightForms running on Windows and Android platforms.

Applications may be specified to run in certain aspects in order to support devices with different screen sizes (form factors) depending on the device or browser being used. This is achieved via defining aspects with associated 'client device identifiers' for each aspect defined in the project.

When remote client browsers (sometimes referred as remote agents) communicate with BrightWeb using HTTP protocol, they transmit information regarding its capabilities including browser name, version, operating system they run on. This is called User Agent ID.  

When a device connects BrightWeb, its User Agent ID is checked against the identifiers listed for the aspects, and if there's a match, then the appropriate form aspect will be displayed. In other words, each client browsers identifiers are logically "OR"ed to find a matching aspect.

Each client browser identifier may also contain a number of specific matching user agent attributes, all of which need to be present in the User Agent ID for the identifier to match. These strings are separated by the special $#BS#$ value separators. In other words, client browser identifier attributes separated by the system value separators are logically "AND"ed. For example, if a form aspect is to be displayed only by a Firefox browser client running on Windows platform, then the client browser identifier may be "Windows$#BS#$Firefox".

The User Agent ID containing the device identifier used for this process may be retrieved via several means, such as via the diagnostics screen with no application/web mode privileges, the 'Licensed Web Users' node in the Servers panel, or via the System.GetUserAgent() object method within an expression.

Therefore, for example, if a project is designed to run on a smartphone with smaller screen and a tablet with a larger screen, then two aspects would be created - one listing all identifiers the smaller aspect is designed for, and another listing identifiers for devices with the larger screen space. If the device is not specified in the form's properties, the default aspect will be used. For more information on defining and implementing a project's aspects, please refer to the BrightBuilder > Form Aspects chapter of this documentation.

Furthermore, along with the User Agent string definition, the initial pixel scaling of the aspect when rendered in a web browser may be set for each identifier. The values range from any value greater than 0 to 2.5 the pixels displayed in the WYSIWYG form editor, and will be applied where applicable - usually on mobile device browsers when each form loads. The default scaling value is 1.5.

Auto Resizing Forms

BrightWeb, by default, renders the forms as they are laid out at design time by using the pixel co-ordinates specified for each control element on forms. This means that, especially when using desktop or tablet browsers, forms may not use the available screen space effectively. When the browser window is maximised there could be empty form areas that could have been used better. Using aspects as mentioned above by the use of User Agent strings alleviates the issue to a degree. But if there are many form factors that the application needs to support, then the use of aspects may not be practical.

As of Version 9.2.0, BrightWeb supports the Web App Auto Resized BSP project property to help developers somewhat to solve this issue by proportionally resizing the size and location of controls on forms.

The algorithm for this feature is very simple and easy to understand :

Form heights and widths defined at design time are assumed to be 100% by 100%. Simply, when the project's Web App Auto Resized property is turned on, each control's size and position on the form are converted into percentage values in relation to the form's height and width when web forms are rendered by BrightWeb.

The screen shots below try to demonstrate this.

Listview Blocking

 

By default listview controls display all the records in the query result, and the listview entries are navigated through the vertical scroll bar. This may be cumbersome and not desirable in certain user scenarios and sometimes not possible on certain browsers. Therefore a special mechanism is needed to bypass this issue and provide a more web friendly listview data display. This is done through the listvew control's web blocking properties.

Blocking is a feature unique to the web platform, and can be enabled via the 'Blocking Enabled' property for listview controls. Enabling this property will segment the listview query's result into 'blocks' which may then be navigated through at the bottom of the control. The user may then browse through records without needing to scroll; they may simply tap or click through via block navigation. The block size may be set by the 'Block Size Display' property of the control.

Implementing a blocked listview is more suited to web applications and has greater device compatibility, as scrolling and scroll positions do not need to be processed. There are also benefits regarding server load - a smaller record set is displayed each time, and thus forms and actions will load quicker than an 'unblocked' or typical listview. It allows processing of large sets of data much easier and quicker for the end user, and should be considered when porting or creating new web applications.

Wrapping Content in Cell

The web platform may not adhere to defined column widths if the contents of the cells are too large. In these scenarios, the defined length will be exceeded in order to accommodate the extra data, at the expense of the neighbouring cells. Depending on the content shown, this may be an undesired effect.

In order to alleviate this effect, there is a web only property - 'Wrap Content in Cell'. Activating this property will enforce column width definitions, and have over extending string values wrap across lines. As a result, column widths will be uniform with this property on, but rows may extend over more than one line to accommodate the data.

 

Listview - Web Action

While listview's single click and double click actions still exist in web mode, it is not obvious to a web user or sometimes not practical to use. The double click action, for instance, may even not be possible on all devices, especially on touch screen devices. Furthermore, a single or a double click action may not be precise enough, and result in unwanted accidental behaviour by end users.

Specifying an action under the listview 'Web Action' column property will allow the data cell contents to become clickable (tap-able) as a web link. When the listview's row is clicked, it will become selected, then run the expression (selected with the drop down) or form open action (selected with the ellipsis) specified as the column property.

This feature offers an intuitive web alternative to row selection, and offers greater compatibility across multiple device types operating via BrightWeb.

Note that each column in a listview can have a different web action defined for it. This mean that you can run different expressions or open different forms for each column of the listview. This provides more flexibility and context sensitivity given the listview column that triggers the web action configured.

 

DateTime in BrightWeb

DateTime controls by default, allows the selection of any year via drop down menu. The viewable years for selection is based on the current selection, with years 20 years before and after the currently selected date being shown. As with DateTimes in BrightForms, a new date time with no assignment will default to the DateTime of 'now'.

If the dates of selection is to be finite, the 'Web Year Range' web-only properties of the control may be used to specify specific start and end dates. With all values populated, the user may only select dates within the year ranges specified. When initialised, the date time with 'Web Year Range' properties enabled will display the earliest displayable date by default, rather than the value of 'now'.

Linking to URLs

Labels may be set to link to URLs in the web platform, and is specified by the 'Web Link' property. For more information, please refer to the Appendix > Form Control Properties - Label chapter of the documentation. URLs will be opened in a new window or tab on user click.

Please note to supply the correct protocol for the URL, such as mailto:, http: etc. If no protocol is supplied, the string provided will be appended to BrightServer's web URL.

The URL may also be set through expressions via the label's Form Control Object Method Label.SetWebLink().

Emailing in BrightWeb

Emailing via BrightWeb needs to do so by specifying the sender's email address, SMTP server address and the optional port number, if the default SMPT port is not used. For example:

Alternatively, a link with the mailto: protocol may also be specified to send emails, such as defining the link as follows:

When the user clicks on the link, BrightWeb will launch the default email client software running on the device.

File Submission in Web

In web mode, edit controls may be set to accept file uploads from the client device. This is set via the 'Web - File Input' property of the edit control.

 

Once a file is uploaded, the edit control may then be used to reference the data from the client. At this stage the edit control will contain the binary blob value which is the content of the file uploaded.

For example, an expression may have the following line to load the uploaded image file into a scribble control:

Please note that some devices, such as the Apple iPad, have policy restrictions on this operation, and thus do not support it.

Mark Files For Download

The System.MarkFileForDownload() method allows users to download files from the server's filesystem. The method takes in two parameters - one specifying the file's location, and the other specifying the filename the user will be prompted to initially save the file as.

A common example where this method would be used would be in conjunction with Reports generated on the server. Using the reports object's PrintToPDF() method, a PDF may be generated and saved to the local filesystem, then the file may be specified to be downloaded by the user. For more information, please refer to the PrintToPDF section of the Printing Reports tutorial.

The location of files both saved and loaded by these methods may be used relative to the BrightServer executable. For example, if BrightServer is running as a service, and the filepath './example.pdf' is used to create a PDF file, it will be located in the 'service' folder of the BrightServer installation directory. Similarly, '../data/example.pdf' will write the file to the 'data' folder of the installation directory.

Close Current Form On Open

In BrightWeb, forms may be set to close upon opening a child form. This allows any parent form to close upon opening a child form and loading it in the browser, keeping the number of loaded forms is kept to a minimum for the web application, with resources active for only the form rendered in the browser. This feature may be utilised when designing applications with numerous forms, with each form accessible from one another without interlinked or dependant logic.

The 'Web - Close Current Form Before Opening Child Form' option in the Open Form Dialog activates this feature. By default, this setting is set off, such that BrightWeb performs similarly to BrightForms on Window and Android platforms.

While facilitating efficiency and simplicity in web applications, this feature may not be suitable in all projects. As the parent form and all other opened forms are lost once the child form opens, there will be no option to close the form with the BrightWeb toolbar; only Logout will be shown. Furthermore, as there is no closing of the form, any expressions set as Action - Close, and the Form.Close() method itself should not be used, as there will be no previous form to return to.

Instead of being able to rely on previously opened forms for application navigation, like in BrightForms applications, each form must contain means to progress through the application; navigation is thus dependant on each child form opened via this option. One way to facilitate this navigation, Menus in Web, or Global Menus may be used.

Browser/Device User Agent

The user agent string of a device is a string that identifies both the device model and the browser BrightWeb is currently being run on. It is used when setting BrightWeb's aspects, licensing, and may also be retrieved in expressions using the System.GetUserAgent() method.

The System.GetUserAgent() method in particular should be noted, as while any client browser may access and run applications via BrightWeb, devices with policy issues may impact consistency across platforms. An example of this is the iPad, where browser file selection and uploads are not supported.

In instances such as these where the device or the browser may present compatibility issues, System.GetUserAgent() may be used to determine the browser type and device being used to run the application, and implement branching behaviour where necessary. For example the following code could be used to determine if a device was an iPad or iPhone.