Porting desktop apps to web apps

To create a web version of an existing desktop app, there are several things to consider. Obviously, you cannot use your project exactly as it is as desktop apps and web apps are different project types. Since you cannot change the type of a project, you will need to create a new web app project in order to create a web app.

But with an appropriate design and understanding of the UI differences, you will find that you can create a web app easily, re-using (or even sharing) a significant amount of non-UI code.

User interface

../../_images/porting_desktop_apps_to_web_apps_eddie's_electronics_desktop_window_layout.png

The user interface for a web app is completely different than the user interface for a desktop app. Not all of the desktop controls have equivalent web controls (DesktopGroupBox, for example) and not all the features of the desktop controls are available in web controls (such as DesktopListBox vs WebListBox). There are also web controls that do not have an equivalent desktop control (for example, WebMapViewer).

In addition, web apps do not have a concept of a Menu Bar, which is something that almost every desktop app uses, so you'll want to re-think how you present this information to the user.

Because of these differences, you are going to need to completely re-implement your existing desktop user interface using web app controls. Keeping your UI and business logic code separate can make this transition easier.

Web pages replace windows

Generally speaking, each window in a desktop app can be designed as a web page in a web app. You use the Show method to display different pages based on user actions, similar to how you might show additional windows. Keep in mind that a web app can only show a single page at one time. If your desktop app relied on having multiple visible windows, then you will need to rethink that design and come up with an alternative. In most cases your layouts should not change much.

Dialogs

../../_images/porting_desktop_apps_to_web_apps_eddie's_electronics_web_page_layout.png

Dialogs in desktop apps can use the MessageDialog class or be modal windows. In web apps, those options are not available. To create a dialog in a web app, you instead add a WebDialog to your project and add your layout to it. Then you add this web dialog to the page or pages on which it should appear and call it using Show where appropriate.

When the dialog is closed, its Dismissed event handler is called where you can determine what action to take.

Unlike desktop app dialogs, Web dialogs are not modal. After you call Show to display the dialog, the rest of the code in your method runs without waiting for the dialog to close.

Shown event handler

In desktop apps, you often use the Open event handler to do initial setup of your controls or windows. In web apps, you should instead use the Shown event handler.

Control appearance

In desktop apps, you can modify the style of a control by changing properties on it for color, font, etc. With web apps, you can do this as well. In some cases the control will have specific properties available and in others you will use the control's Style property. Web projects use Bootstrap themes to provide the overall appearance of controls.

Multiple users

One fundamental difference between desktop and web apps is that desktop apps are designed to be used by a single user at a time while web apps are designed to be used by many users at a time. Sessions and Cookies can help with this.

Latency

With a web app, your Xojo code runs on the server where the web app is installed and not in the user's web browser. This means that there is a delay, slight in some cases and more significant in others, between when an action is taken on the browser, when the Xojo code runs on the server and then when the result of that code appears back on the browser. It's what is called “round trip” and it depends on network traffic, how physically far a user is from your app and among other things, how long it takes for your app to respond. The result is that you 're going to have to think asynchronously when designing.

Sessions

Having to deal with multiple users means you may need to manage global data differently. In desktop apps, public properties and methods on the App object are global to the entire app, which can often be useful.

In a web app, the App is also global to the entire app, which means it is globally available to all users of the web app. This is usually not the behavior you want. Instead you want data to be specific to each user (aka Session) that is connected to the web app.

So you do not want to store global information that is specific to the current user, such as the UserName that was used to log in, in the App object. Instead, web apps have a concept called a WebSession. Each user that connects to your web app gets its own WebSession in the form of a Session object. Use the Session object to manage global information just for the user. For example, saving the UserName to a property on the Session means that it is only visible to the one user.

Cookies

Most apps need to save preferences or settings of some kind. With web apps, you can easily do this using Cookies, a web technology that provides a way for a web browser to save settings that can be later requested by the web app. Cookies are part of the WebSession. This code saves the user name in a Cookie:

Session.Cookies.Set("UserName") = UserNameField.Text

Log in

If you've saved a cookie containing the UserName as shown above you may want your web app to retrieve it so that it can pre-populate the UserName field on a login form. This code (in the Shown event handler for the page) fetches the saved Cookie and uses it to pre-fill a UserName field:

UserNameField.Text = Session.Cookies.Value("UserName")

Databases

Database desktop apps often keep a global reference to the database as a property of the App object. With a web app, you should instead use Session to store a property for the database reference. Each user that connects to the web app will then have their own connection to the database so that transactions work properly and so that you can isolate database access to prevent other users ' data from being visible.

For example, a desktop app may use the App.Open event handler to connect to the database once when the app starts and save the connection to a public DB property that is accessed throughout the app as App.DB. In a web app, you would instead do the connection in the Session.Opening event handler and save the connection to a public DB property that is accessed throughout the session as Session.DB.

For desktop apps, if you want to allow multiple users to access a database (using multiple installations of the desktop app), then you usually want to use a database server.

With web apps, you may find that you do not always need a database server. Because your web app is itself running as a server, SQLite is often more than sufficient for handling light to medium web app loads.

Circular references

You 'll need to be careful not to create circular references up and down the Session structure. For instance, Session hierarchy looks like this:

Session
- Pages
  - Controls
  - Dialogs
    - Controls

It's very important that the lower items don 't refer directly to the higher ones (like having a reference to Session in a WebPage). If you do, the Session and it's contents will never be destroyed, even when a user leaves your app. If you need such functionality, you 'll need to use a WeakRef.

Navigator example

This simple example uses a class to open a new web page or a new window, depending on the type of app.

Create a new desktop project and add a new class, called Navigator. In it, add a method called ShowScreen2 with this code:

#If TargetWeb Then
  WebPage2.Show
#ElseIf TargetDesktop Then
  Window2.Show
#Endif

The above code uses conditional compilation to display either WebPage2 or Window2 depending on the type of app. TargetWeb indicates it is a web app and TargetDesktop indicates it is a desktop app.

In Window1, add a Button and put this code in its Action event handler:

Var n As New Navigator
n.ShowScreen2

Now add a new Window (it should default to Window2 as the name). You should give this window a title that says “Window 2” so you know when it has opened. Run the project and click the button on the default window to see that Window2 opens.

Now create a new web project. Add a Button to WebPage1 and add the same code to its Pressed event handler:

Var n As New Navigator
n.ShowScreen2

Now copy the Navigator class from the desktop project to this web project.

Lastly, add a second web page, called WebPage2. Give it a title so you know when it displays. Run the project and click the button on the default web page to see that Web Page 2 appears.

You have now created a (very simple) class that can be used in either a desktop or web app. This technique can apply to just about anything. Code that refers to web-specific objects or features should be included in “#If TargetWeb” and code that is for desktop apps should use “#If TargetDesktop”.

Although you are using the same Navigator class, you are not actually sharing the exact same class between the two projects. Changes made to the Navigator in one project do not affect it in the other project. If you want to share the exact same class so that a change in one project is reflected in another, then you need to use an External Project Item as described in Sharing Code among multiple projects.